Интеграция с «внешними» информационными системами (ВИС)

1

Платформа НЕЙРОСС может обеспечивать взаимодействие с информационными системами «сторонних» производителей в части получения и передачи авторизованных HTTP-запросов из/в СКУД НЕЙРОСС.

2

3

== {{id name="Интеграцияс«внешними»информационнымисистемами(ВИС)-Общиесведения"/}}(% style="color:#172b4d" %)Общие сведения(%%) ==

4

5

(% style="letter-spacing:0.0px" %)В качестве интегрируемой системы может выступать п(% style="color:#333333; letter-spacing:0.0px" %)рикладное программное средство, приложение, программа, выполняющая функции по назначению, и в своих бизнес-процессах использующая данные сети НЕЙРОСС и возможности управления.

6

7

(% style="color:#333333" %)В качестве средства интеграции выступает «Плагин НЕЙРОСС ВИС», устанавливаемый на узел Платформа НЕЙРОСС. (% style="color:#464646" %)Плагин НЕЙРОСС ВИС предназначен для интеграции с «внешней» информационной системой (ВИС) в части функций (% style="color:#333333" %)системы контроля и управления доступом (СКУД):

8

9

* (% style="color:#333333" %)**Первичной синхронизации подмножества базы данных владельцев и пропусков из НЕЙРОСС в ВИС **— выгрузка имеющихся данных.

10

* (% style="color:#333333" %)**Управление данными владельцев и пропусков** — создание, изменение владельцев и пропусков с загрузкой данных из ВИС в НЕЙРОСС и наоборот, — из НЕЙРОСС в ВИС.

11

* (% style="color:#333333" %)**Удалённый СКУД** — и(%%)нициирование транзакций доступа из ВИС в НЕЙРОСС на конкретной ТД и уведомление ВИС от НЕЙРОСС о результате транзакции.

12

13

Плагин реализует HTTP-API, позволяющее:

14

15

1. Получить из НЕЙРОСС список всех уровней доступа, разрешенных «внешней» системе (УД ВИС);

16

1. Получить из НЕЙРОСС список всех точек доступа ВИС, которые указаны хотя бы в одном УД ВИС (ТД ВИС);

17

1. Получить из НЕЙРОСС данные одного владельца или список всех владельцев пропусков, которым назначен хотя бы один УД ВИС (пропуска ВИС);

18

1. Создавать новых владельцев пропусков ВИС и назначать им уровень доступа только из множества УД ВИС;

19

1. Изменить данные по одному или нескольким владельцам и пропускам;

20

1. Инициировать из ВИС транзакцию доступа владельцев пропусков ВИС через ТД ВИС.

21

22

Дополнительно к непосредственному управлению СКУД, ВИС может осуществлять:

23

24

* Учёт рабочего времени на основе событий входа и выхода по точкам доступа, помеченных соответствующими пользовательскими метками;

25

* Использовать выданные карты для авторизации пользователей вне СКУД НЕЙРОСС.

26

27

[[image:attach:ui.Параметры узла.WebHome@content.png||thumbnail="true" height="10"]] Содержание:

== {{id name="Интеграцияс«внешними»информационнымисистемами(ВИС)-Лицензирование"/}}Лицензирование ==

32

33

Для обеспечения функции взаимодействия по HTTP API, проверьте наличие требуемых лицензий в параметрах лицензии ~[[[doc:ui.Параметры узла.Основные параметры.Просмотр параметров и обновление лицензии.WebHome]]]. (% style="color:#333333" %)В противном случае требуется приобрести лицензии ~[[[doc:neyross.Лицензирование | Платформа НЕЙРОСС.WebHome]]].

34

35

(% class="wrapped" %)

36

|=(% style="width: 131.0px;" %)(((

37

Тип узла

38

)))|=(% style="width: 127.0px;" %)(((

39

Параметр лицензии

40

)))|=(% style="width: 943.0px;" %)(((

41

Комментарий

42

)))

43

|(% rowspan="3" style="width:131.0px" %)(((

44

Платформа НЕЙРОСС

45

)))|(% style="text-align:left; width:127.0px" %)(((

46

Плагин НЕЙРОСС ВИС

47

)))|(% style="text-align:left; width:943.0px" %)(((

48

(% style="color:#2f343d" %)Использование сервиса взаимодействия с «внешней» информационной системой (ВИС) посредством утвержденного API.

49

)))

50

|(% style="text-align:left; width:127.0px" %)(((

51

(% style="color:#2f343d" %)Плагин НЕЙРОСС ВИС: максимальное количество точек доступа

52

)))|(% style="text-align:left; width:943.0px" %)(((

53

(% style="color:#2f343d" %)Управление одним виртуальным считывателем из ВИС (виртуальный считыватель точки доступа БОРЕЙ). Лицензирование по количеству точек доступа, запросы к считывателям которых требуется отправлять.

54

)))

55

|(% style="width:127.0px" %)(((

56

[Доступ] Пропуск, шт.

57

)))|(% style="width:943.0px" %)(((

58

Лицензия на количество активных пропусков в системе. Данное количество должно быть достаточным для всех владельцев пропусков ВИС.

)))

**ВАЖНО**

Обращаем внимание, что передача лицензии на использование плагина НЕЙРОСС ВИС и представленное API НЕЙРОСС ВИС осуществляются на условиях «КАК ЕСТЬ» («AS IS»), в соответствии с общепринятым в международной практике принципом, и не накладывает на компанию ИТРИУМ обязательств по бесплатному сопровождению разработки интегрированного решения. Для обсуждения условий сотрудничества по разработке обратитесь в отдел продаж ИТРИУМ.

65

66

Также по запросу возможно предоставление полного HTTP API НЕЙРОСС ~[[[doc:neyross.Настройка Платформы НЕЙРОСС.Инструменты интеграции.WebHome]]].

67

68

69

== {{id name="Интеграцияс«внешними»информационнымисистемами(ВИС)-Журналверсий"/}}Журнал версий ==

70

71

|=(% style="text-align: left;" %)(((

72

Версия плагина

73

)))|=(% style="text-align: left;" %)(((

74

Дата выхода

75

)))|=(% style="text-align: left;" %)(((

Комментарий

)))

|(((

1.5. …

)))|(((

(% style="color:#333333" %)06.11.2025

82

)))|(((

83

(% style="color:#333333" %)Добавлен метод API для получения владельцев/пропусков ВИС, изменённых за указанный интервал времени; добавлен метод API, позволяющий получить информацию о владельцах/пропусках ВИС по нескольким UUID.

)))

|(((

1.4. …

)))|(((

29.04.2025

)))|(((

Добавлено поле accessPoints в модель данных событий доступа ВИС, позволяющее идентифицировать источник события ~[[[#Список УД ВИС>>doc:||anchor="Интеграцияс«внешними»информационнымисистемами(ВИС)-СписокУДВИС"]]]. Добавлена выдача поля перечня меток tags в ответ на запрос списка ТД ВИС ~[[[#Список лицензированных ТД ВИС>>doc:||anchor="Интеграцияс«внешними»информационнымисистемами(ВИС)-СписоклицензированныхТДВИС"]]].

)))

|(((

1.3. …

)))|(((

03.02.2025

)))|(((

Добавлено описание API для получения конкретного владельца пропуска ВИС и для создания/изменения нескольких владельцев одновременно; расширен перечень полей владельца пропуска.

)))

|(((

1.2. …

)))|(((

21.02.2024

)))|(((

Добавлено описание API работы с событиями доступа ВИС.

)))

|(((

1.1. …

)))|(((

03.10.2023

)))|(((

В API получения списка лицензированных ТД ВИС произведена замена идентификатора UUID на TOKEN.

112

)))

113

|(% style="text-align:left" %)(((

114

1.0. …

115

)))|(% style="text-align:left" %)(((

116

11.08.2023

117

)))|(% style="text-align:left" %)(((

118

Первая исходная версия плагина НЕЙРОСС ВИС.

119

)))

120

121

== {{id name="Интеграцияс«внешними»информационнымисистемами(ВИС)-Подготовкакнастройке"/}}Подготовка к настройке ==

122

123

=== {{id name="Интеграцияс«внешними»информационнымисистемами(ВИС)-НастройкаУДВИС"/}}Настройка УД ВИС ===

124

125

В приложении АРМ НЕЙРОСС Доступ перейдите в раздел **Уровни доступа** ~[[[doc:neyross.АРМ НЕЙРОСС Доступ.Уровни доступа.WebHome]]] и настройте УД ВИС — уровни доступа, которые следует разрешить «внешней» информационной системе. Вы можете создать новые уровни доступа с требуемым префиксом, либо просто переименовать созданные ранее уровни, добавив в начало имени префикс [И] и пробел.

126

127

128

«Внешней» информационной системе предоставляется доступ только к уровням доступа НЕЙРОСС, помеченных как «ВИС» определённым образом: имя уровня доступа содержит префикс в виде

129

130

131

[И] - русская заглавная буква И в квадратных скобках, отделённая от имени пробелом

Например:

[И] Уровень доступа ВИС 1

[[image:attach:plugin_eis_accesslevels.png||data-cizoom="0" height="198"]]

143

(% style="letter-spacing:0.0px" %)//Пример уровней доступа для интеграции с ВИС//(%%)

144

\\(% style="letter-spacing:0.0px" %)Плагину интеграции будут доступны точки доступа, которые которые указаны хотя бы в одном УД ВИС — ТД ВИС, при этом они должны быть указаны в настройках плагина ~[[[#Настройка плагина интеграции>>doc:||anchor="Интеграцияс«внешними»информационнымисистемами(ВИС)-Настройкаплагинаинтеграции"]]].

145

146

=== {{id name="Интеграцияс«внешними»информационнымисистемами(ВИС)-СозданиепулапропусковсУДВИС"/}}(% style="letter-spacing:0.0px" %)**Создание пула пропусков с УД ВИС**(%%) ===

147

148

(% style="letter-spacing:0.0px" %)Задайте пропускам, транзакция по которым может быть инициирована из ВИС, режим доступа ~[[[Режимы доступа>>doc:neyross.АРМ НЕЙРОСС Доступ.Режимы доступа.WebHome]]], (%%)включающий один или несколько УД ВИС.

149

150

151

Одному пропуску могут быть назначены как УД ВИС, так и «чисто внутренние» УД НЕЙРОСС. Для задания нескольких уровней используйте режим доступа ~[[[doc:neyross.АРМ НЕЙРОСС Доступ.Режимы доступа.WebHome]]].

152

153

154

[[image:attach:plugin_eis_accessrules.png||data-cizoom="1" style="cursor:zoom-in" width="900"]]

**ОГРАНИЧЕНИЯ ВИС**

АРМ НЕЙРОСС обеспечивает полное управление владельцами, пропусками и уровнями доступа ВИС. «Внешняя» информационная система может:

160

161

1. Получить из НЕЙРОСС только УД ВИС;

162

1. Получить из НЕЙРОСС и управлять только ТД ВИС;

163

1. Получить из НЕЙРОСС данные только тех пропусков и их владельцев, которые содержат хотя бы один УД ВИС;

164

1. Создавать любых новых владельцев и их пропуска и назначать им УД из множества УД ВИС.

165

166

ВИС оперирует только разрешённым подмножеством ТД, УД, владельцев и пропусков. При помощи добавления или удаления префикса в названии УД администратор НЕЙРОСС может управлять подмножеством данных, «видимых» для ВИС.

ВИС не может:

1. Удалять владельцев и пропуска;

171

1. Создавать, удалять и изменять УД;

172

1. Создавать, удалять и изменять ТД.

173

174

Эти функции требуется выполнять из АРМ НЕЙРОСС.

175

176

177

== {{id name="Интеграцияс«внешними»информационнымисистемами(ВИС)-Настройкаплагинаинтеграции"/}}Настройка плагина интеграции ==

178

179

=== {{id name="Интеграцияс«внешними»информационнымисистемами(ВИС)-Добавлениеплагина"/}}Добавление плагина ===

180

181

Сервис работы с ВИС поставляется в виде (% style="color:#172b4d" %)плагина интеграции — (% style="color:#0c0e0d" %)независимого программный модуля, предназначенного для расширения функционала Платформы НЕЙРОСС(% style="color:#172b4d" %). Установка плагина является стандартной процедурой и не зависит от предоставляемых функций. П(% style="color:#333333" %)еречень разработанных плагинов и порядок их установки приведён в разделе ~[[[doc:ui.Параметры узла.Плагины.WebHome]]].

182

183

184

Право использования функции плагина задано в параметрах лицензии. Дополнительная активация плагина не требуется.

185

186

187

Выполните установку плагина согласно инструкции по ссылке выше, дождитесь окончания процедуры установки плагина и выполните перезагрузку Платформы НЕЙРОСС.

188

189

190

Установка плагина может занимать длительное время. Не перезагружайте компьютер и не отключайте его от сети. Перезапуск осуществляется только после полной установки плагина и отображения требования о перезагрузке.

191

192

193

=== {{id name="Интеграцияс«внешними»информационнымисистемами(ВИС)-Настройкаплагина"/}}Настройка плагина ===

194

195

После установки наведите указатель мыши на строку с плагином и нажмите на кнопку [[image:attach:ui.Параметры узла.WebHome@fa-edit-square.png||thumbnail="true" height="19"]] **Настроить**.

196

197

[[image:attach:plugin_eis5.png||data-cizoom="1" style="cursor:zoom-in" width="900"]]

198

199

Откроется окно настройки плагина. Задайте настройки согласно таблице ниже и сохраните изменения.

200

[[image:attach:plugin_eis6.png||data-cizoom="0"]]

201

202

(% class="wrapped" %)

|=(((

Параметр

)))|=(((

Комментарий

)))

|(((

Максимальное количество точек доступа ВИС

210

)))|(((

211

Параметр, заданный в лицензии. Определяет количество точек доступа, которыми может управлять «внешняя» информационная система.

212

)))

213

|(((

214

(% style="text-align: left;" %)

215

Таймаут ожидания транзакции доступа, мс

216

)))|(((

217

Период времени, в течение которого ожидается ответ от НЕЙРОСС о результате транзакции доступа, инициированной из ВИС (удалённое предъявление идентификатора на точку доступа НЕЙРОСС). Транзакция доступа завершается по факту получения события «Доступ разрешён» или «Доступ запрещён» от контроллера доступа ~[[[doc:borey3.Руководство администратора БОРЕЙ Н.События БОРЕЙ.WebHome]]]. Если точка доступа не готова обработать транзакцию (например, — еще не закрыта дверь в результате предыдущей транзакции, или точка доступа находится в состоянии //Взлом//), плагин НЕЙРОСС ВИС будет ожидать ответа в течение заданного времени таймаута, после чего завершит транзакцию ВИС с ошибкой.

)))

|(((

API-токен

)))|(((

(% class="content-wrapper" %)

223

(((

224

Данный токен должен передаваться ВИС в каждом запросе в следующем виде:

225

226

227

Authorization: Bearer TOKEN

228

229

230

, где TOKEN — указанный в поле символьный ряд, например:

231

232

233

Authorization: Bearer ce6b228c-9f09-47bd-b5d6-933abc894905

Вы можете изменить автоматически сгенерированный токен на собственный.

)))

)))

|(((

Точки доступа

)))|(((

(% class="content-wrapper" %)

245

(((

246

Перечень точек доступа НЕЙРОСС, которые будут «видимы» для ВИС и разрешены для транзакций доступа, инициируемых из ВИС.

247

248

249

Количество точек доступа ограничивается параметрами лицензии. При выборе количества, превышающего значение в поле «Максимальное количество точек доступа ВИС», вы получите сообщение об ошибке.

)))

)))

|(((

Текущее количество владельцев пропусков ВИС

255

)))|(((

256

Количество владельцев пропусков, в режиме доступа которых задан хотя бы один уровень доступа ВИС. Владельцы и пропуска ВИС могут создаваться и изменяться как из ВИС, так и напрямую в АРМ НЕЙРОСС Доступ. Удаление владельцев и пропусков доступно только из сети НЕЙРОСС.

)))

По окончании настройки сохраните изменения по кнопке **Сохранить** и перезагрузите Платформу НЕЙРОСС.

262

263

264

Перезапуск требуется, если изменяли значение таймаута ожидания транзакции доступа, и в некоторых других случаях.

265

266

267

== {{id name="Интеграцияс«внешними»информационнымисистемами(ВИС)-ОписаниеинтеграционногоHTTP-API"/}}Описание интеграционного HTTP-API ==

268

269

(% style="color:#333333" %)Для передачи запроса и ответа используется формат JSON и соответствующий Content-Type: application/json.

270

271

=== {{id name="Интеграцияс«внешними»информационнымисистемами(ВИС)-Авторизация"/}}Авторизация ===

272

273

Все запросы в рамках взаимодействия ВИС-НЕЙРОСС должны быть авторизованы.

274

275

Авторизация запроса осуществляется посредством HTTP-заголовка Authorization, в котором передаётся API-токен в следующем виде:

276

277

278

Authorization: Bearer TOKEN

279

280

281

, где {{code language="java"}}TOKEN{{/code}} — указанный в настройках плагина API-токен.

282

283

=== {{id name="Интеграцияс«внешними»информационнымисистемами(ВИС)-СписокУДВИС"/}}Список УД ВИС ===

URL запроса:

GET /plugin/eis-pacs-integration/access-levels/

Тело ответа:

[

{

"uuid": String, // обязательно, сквозной идентификатор УД

297

"name": String, // обязательно, название УД

298

"accessPoints": List[String] // обязательно, массив идентификаторов ТД

}

]

[[image:attach:plugin_eis7_example1.png||data-cizoom="1" style="cursor:zoom-in" width="900"]]

304

305

Запрос уровней доступа посредством расширения браузера Google Chrome — Talend API Tester. JSON с запросами может быть предоставлен.

Пример ответа:

[

{

"uuid": "820a1259-fbe0-4594-913e-4ab869e60b19",

313

"name": "[И] КПП 2",

314

"accessPoints":[

315

"uuid:fe53892b-2e0e-44a8-98e1-5de2795b289f:6e71dce6-e1aa-4ff4-b213-55391c989b2c"

]

},

{

"uuid": "3260b54b-03f9-48cc-8593-4387b9e867e6",

320

"name": "[И] КПП 3",

321

"accessPoints":[

322

"uuid:fe53892b-2e0e-44a8-98e1-5de2795b289f:f5d4ba84-ab03-42e4-8e4d-2fc4e12de1ba"

]

},

{

"uuid": "3db2237d-04bc-4932-8d03-86d1677c020d",

327

"name": "[И] КПП 4",

328

"accessPoints":[

329

"uuid:fe53892b-2e0e-44a8-98e1-5de2795b289f:1e1614f2-372a-402a-90ee-13fa3c5899fe"

]

},

{

"uuid": "0dfb462d-d5c3-402d-9075-e726ea94bd49",

334

"name": "[И] КПП 1",

335

"accessPoints":[

336

"uuid:fe53892b-2e0e-44a8-98e1-5de2795b289f:987f1ea2-93c9-449f-b38f-5e20d7e8edcd"

]

}

]

Полученные уникальные идентификаторы (UUID) уровней доступа ВИС должны использоваться при создании пропусков ~[[[#Создание и изменение владельцев и пропусков ВИС>>doc:||anchor="Интеграцияс«внешними»информационнымисистемами(ВИС)-СозданиеиизменениевладельцевипропусковВИС"]]].

343

344

=== {{id name="Интеграцияс«внешними»информационнымисистемами(ВИС)-СписокТДВИС"/}}Список ТД ВИС ===

URL запроса:

GET /plugin/eis-pacs-integration/access-points/

Тело ответа:

[

{

"token": String, // обязательно, сквозной идентификатор ТД

358

"name": String // обязательно, название ТД

}

]

Пример ответа:

[

{

"token": "uuid:fe53892b-2e0e-44a8-98e1-5de2795b289f:987f1ea2-93c9-449f-b38f-5e20d7e8edcd",

369

"name": "Точка доступа 0.1"

370

},

371

{

372

"token": "uuid:fe53892b-2e0e-44a8-98e1-5de2795b289f:f5d4ba84-ab03-42e4-8e4d-2fc4e12de1ba",

373

"name": "Точка доступа 2.1"

}

]

Полученные уникальные идентификаторы (UUID) точек доступа ВИС должны использоваться при инициировании транзакции доступа ~[[[#Инициирование транзакции доступа>>doc:||anchor="Интеграцияс«внешними»информационнымисистемами(ВИС)-Инициированиетранзакциидоступа"]]].

379

380

=== {{id name="Интеграцияс«внешними»информационнымисистемами(ВИС)-КоличествовладельцевпропусковВИС"/}}Количество владельцев пропусков ВИС ===

URL запроса:

GET /plugin/eis-pacs-integration/persons/count/

Тело ответа:

{

"count": Long // обязательно, количество владельцев пропусков в подмножестве ВИС

}

Пример ответа:

{

"count": 7

}

=== {{id name="Интеграцияс«внешними»информационнымисистемами(ВИС)-СписоквладельцевВИС"/}}Список владельцев ВИС ===

URL запроса:

GET /plugin/eis-pacs-integration/persons/search/?limit=$LIMIT&offset=$OFFSET

411

412

413

Параметры запроса (могут отсутствовать):

414

415

* $LIMIT – максимальное количество владельцев в выдаче. Значение по умолчанию 1000

416

* $OFFSET – сдвиг владельцев в выдаче (для постраничной выдачи). Значение по умолчанию 0

Тело ответа:

[

{

"uuid": String, // обязательно, сквозной идентификатор владельца в формате UUID

424

"surname": String, // обязательно, фамилия сотрудника

425

"name": String, // обязательно, имя сотрудника

426

"patronymic": Option[String], // опционально, отчество сотрудника

427

"organization": Option[String], // опционально, организация сотрудника

428

"division": Option[String], // опционально, подразделение сотрудника

429

"post": Option[String], // опционально, должность сотрудника

430

"clock_number": Option[String], // опционально, табельный номер сотрудника

431

"document_number": Option[String], // опционально, номер документа сотрудника

432

"phone": Option[String], // опционально, номер телефона

433

"email": Option[String], // опционально, адрес электронной почты

434

"accessLevels": Option[List[String]], // опционально, массив идентификаторов уровней доступа ВИС в формате UUID

435

"passType": Option[String], // опционально, тип пропуска. Возможные значения: REGULAR - постоянный, TEMPORARY - временный, ONETIME - разовый. Если значение не указано - используется тип REGULAR

436

"activation_date": Option[Long], // опционально, дата начала действия пропуска в формате Unix timestamp (в секундах)

437

"expiration_date": Option[Long], // опционально, дата окончания действия пропуска в формате Unix timestamp (в секундах)

438

"card": Option[Long], // опционально, номер карты владельца

439

"facility": Option[Long], // опционально, код предприятия карты владельца

440

"info": { // опционально, произвольные данные о сотруднике в формате "ключ-значение"

"anyKey": "anyValue"

}

}

]

Пример ответа:

[

{

"uuid": "21e10f5d-7af7-44ba-b1a3-d0b9cf429437",

453

"surname": "Аспидов",

454

"name": "Иван",

455

"patronymic": "Сергеевич",

456

"accessLevels":[

457

"0dfb462d-d5c3-402d-9075-e726ea94bd49"

458

],

459

"passType": "REGULAR",

460

"info":{

461

"inactivity": "false",

462

"Birthday": "1994-12-05"

}

},

{

"uuid": "022abfc4-3809-4ce3-bfc4-cbdb4a07f726",

467

"surname": "Акимов",

468

"name": "Сергей",

469

"patronymic": "Сергеевич",

470

"accessLevels":[

471

"0dfb462d-d5c3-402d-9075-e726ea94bd49"

472

],

473

"passType": "REGULAR",

474

"info":{

475

"inactivity": "false",

476

"Birthday": "1994-02-18"

}

},

{

"uuid": "54b9fa8c-4a36-4431-8f74-c6ad5897fb7f",

481

"surname": "Петров",

482

"name": "Петр",

483

"patronymic": "Сергеевич",

484

"accessLevels":[

485

"0dfb462d-d5c3-402d-9075-e726ea94bd49"

486

],

487

"passType": "REGULAR",

488

"info":{"pacs:folder": "c84e7f59-d37a-4d09-9cf9-fab38b11221a", "neyross:automation:responsibleTelegramChatId": "1055492440", "inactivity": "false",...}

},

]

Владельцы пропусков отсортированы по UUID.

495

496

497

В ответе выдаются только UUID УД ВИС, даже в случае, если (% style="color:#333333" %)в пропуске у владельца имеются и УД ВИС, и прочие УД.

498

499

500

(% style="font-size:16.0px; font-weight:bold; letter-spacing:-0.006em" %)**Получение информации о конкретном владельце и пропуске ВИС**

URL запроса:

GET /plugin/eis-pacs-integration/persons/$PERSON_UUID

506

507

508

, где $PERSON_UUID — (% style="color:#333333" %)идентификатор владельца пропуска ВИС

Тело ответа:

{

"uuid": String, // обязательно, сквозной идентификатор владельца в формате UUID

515

"surname": String, // обязательно, фамилия сотрудника

516

"name": String, // обязательно, имя сотрудника

517

"patronymic": Option[String], // опционально, отчество сотрудника

518

"organization": Option[String], // опционально, организация сотрудника

519

"division": Option[String], // опционально, подразделение сотрудника

520

"post": Option[String], // опционально, должность сотрудника

521

"clock_number": Option[String], // опционально, табельный номер сотрудника

522

"document_number": Option[String], // опционально, номер документа сотрудника

523

"phone": Option[String], // опционально, номер телефона

524

"email": Option[String], // опционально, адрес электронной почты

525

"accessLevels": List[String], // обязательно, массив идентификаторов уровней доступа ВИС в формате UUID

526

"passType": Option[String], // опционально, тип пропуска. Возможные значения: REGULAR - постоянный, TEMPORARY - временный, ONETIME - разовый. Если значение не указано - используется тип REGULAR

527

"activation_date": Option[Long], // опционально, дата начала действия пропуска в формате Unix timestamp (в секундах)

528

"expiration_date": Option[Long], // опционально, дата окончания действия пропуска в формате Unix timestamp (в секундах)

529

"card": Option[Long], // опционально, номер карты владельца

530

"facility": Option[Long], // опционально, код предприятия карты владельца

531

"info": { // опционально, произвольные данные о сотруднике в формате "ключ-значение"

"anyKey": "anyValue"

}

}

(% style="color:#333333" %)Если владелец пропуска для данного UUID не найден, возвращается HTTP-код 404.

540

541

(% style="color:#333333" %)Номер карты и код предприятия может быть передан в ВИС при выполнении следующих условий:

542

543

1. (% style="color:#333333" %)Данные должны быть указаны в соответствующих полях из формы ввода по умолчанию.

544

1. (% style="color:#333333" %)Одному владельцу выдан один только один пропуск. В противном случае будет передан первый найденный номер. При создании большего количества пропусков корректная работа не гарантируется.

=== {{id name="Интеграцияс«внешними»информационнымисистемами(ВИС)-СозданиеиизменениевладельцаипропускаВИС"/}}Создание и изменение владельца и пропуска ВИС ===

URL запроса:

POST /plugin/eis-pacs-integration/persons/upsert/

Тело запроса:

{

"uuid": String, // обязательно, сквозной идентификатор владельца в формате UUID

561

"surname": String, // обязательно, фамилия сотрудника

562

"name": String, // обязательно, имя сотрудника

563

"patronymic": Option[String], // опционально, отчество сотрудника

564

"organization": Option[String], // опционально, организация сотрудника

565

"division": Option[String], // опционально, подразделение сотрудника

566

"post": Option[String], // опционально, должность сотрудника

567

"clock_number": Option[String], // опционально, табельный номер сотрудника

568

"document_number": Option[String], // опционально, номер документа сотрудника

569

"phone": Option[String], // опционально, номер телефона

570

"email": Option[String], // опционально, адрес электронной почты

571

"accessLevels": List[String], // обязательно, массив идентификаторов уровней доступа ВИС в формате UUID

572

"passType": Option[String], // опционально, тип пропуска. Возможные значения: REGULAR - постоянный, TEMPORARY - временный, ONETIME - разовый. Если значение не указано - используется тип REGULAR

573

"activation_date": Option[Long], // опционально, дата начала действия пропуска в формате Unix timestamp (в секундах)

574

"expiration_date": Option[Long], // опционально, дата окончания действия пропуска в формате Unix timestamp (в секундах)

575

"info": { // опционально, произвольные данные о сотруднике в формате "ключ-значение"

576

"anyKey": "anyValue"

577

},

578

"photo": Option[String] // опционально, фото сотрудника в формате BASE64. Если не передано - создаётся владелец без фотографии \ не изменяется сохранённая ранее фотография

}

Тело ответа:

{

"result": String, // обязательно, возможные значения: "success" - владелец создан \ обновлён, "error" - возникли ошибки

587

"error": Option[String] // обязательно для result == error, текстовое пояснение ошибки

}

=== {{id name="Интеграцияс«внешними»информационнымисистемами(ВИС)-СозданиеиизменениенесколькихвладельцевипропусковВИС"/}}(% style="font-size:16.0px; font-weight:bold; letter-spacing:-0.006em" %)**Создание и изменение нескольких владельцев и пропусков ВИС**(%%) ===

URL запроса:

POST /plugin/eis-pacs-integration/persons/upsert/multiple

Тело запроса:

[ // обязательно, массив владельцев

603

{

604

"uuid": String, // обязательно, сквозной идентификатор владельца в формате UUID

605

"surname": String, // обязательно, фамилия сотрудника

606

"name": String, // обязательно, имя сотрудника

607

"patronymic": Option[String], // опционально, отчество сотрудника

608

"organization": Option[String], // опционально, организация сотрудника

609

"division": Option[String], // опционально, подразделение сотрудника

610

"post": Option[String], // опционально, должность сотрудника

611

"clock_number": Option[String], // опционально, табельный номер сотрудника

612

"document_number": Option[String], // опционально, номер документа сотрудника

613

"phone": Option[String], // опционально, номер телефона

614

"email": Option[String], // опционально, адрес электронной почты

615

"accessLevels": List[String], // обязательно, массив идентификаторов уровней доступа ВИС в формате UUID

616

"passType": Option[String], // опционально, тип пропуска. Возможные значения: REGULAR - постоянный, TEMPORARY - временный, ONETIME - разовый. Если значение не указано - используется тип REGULAR

617

"activation_date": Option[Long], // опционально, дата начала действия пропуска в формате Unix timestamp (в секундах)

618

"expiration_date": Option[Long], // опционально, дата окончания действия пропуска в формате Unix timestamp (в секундах)

619

"info": { // опционально, произвольные данные о сотруднике в формате "ключ-значение"

620

"anyKey": "anyValue"

621

},

622

"photo": Option[String] // опционально, фото сотрудника в формате BASE64. Если не передано - создаётся владелец без фотографии \ не изменяется сохранённая ранее фотография

}

]

Тело ответа:

{

"successList": List[String], // обязательно, массив идентификаторов владельцев пропуска, которые успешно обработаны

632

"errorList": [ // обязательно, информация о возникших ошибках

633

{

634

"uuid": String, // обязательно, идентификатор владельца пропуска, для которого возникла ошибка

635

"error": String // обязательно, причина ошибки

}

]

}

(% style="color:#333333" %)В предложенной модели ВИС может создавать только владельцев и пропуска, ассоциированные хотя бы с одним УД ВИС. Поэтому поле {{code language="none"}}accessLevels{{/code}} в запросе не может быть пустым и должно содержать один или несколько UUID УД ВИС. Наличие других УД в данном поле не допускается.

643

644

(% style="color:#333333" %)Также, через данное API можно изменять только тех владельцев пропусков, у которых на момент перед получением запроса в БД НЕЙРОСС уже есть хотя бы один УД ВИС.

645

646

(% style="letter-spacing:0.0px" %)В случае, если у владельца пропуска на момент изменения имеются и УД ВИС, и прочие УД, то алгоритм формирования итогового списка УД для владельца следующий:

647

648

1. Старые УД ВИС удаляются из пропуска.

649

1. Переданные УД ВИС устанавливаются в пропуск.

650

1. Прочие УД (не ВИС) остаются в пропуске без изменений.

651

652

При изменении владельца и пропуска из ВИС в БД НЕЙРОСС у него могут быть дополнительные поля. Они останутся без изменений.

653

654

При создании новых владельцев и пропусков они размещаются в группе НЕЙРОСС **Все**. Администратор НЕЙРОСС, при необходимости, может выполнить перенос пропусков в конкретную группу.

655

656

657

=== {{id name="Интеграцияс«внешними»информационнымисистемами(ВИС)-ПоисквладельцевипропусковВИСпонаборуUUID"/}}Поиск владельцев и пропусков ВИС по набору UUID ===

URL запроса:

POST /plugin/eis-pacs-integration/persons/search/by-uuids

Тело запроса:

[ // обязательно, массив UUID владельцев

"$UUID_1",

"$UUID_2"

]

Тело ответа:

[ // обязательно, массив результатов поиска

678

{

679

"uuid": String, // обязательно, сквозной идентификатор владельца в формате UUID

680

"surname": String, // обязательно, фамилия сотрудника

681

"name": String, // обязательно, имя сотрудника

682

"patronymic": Option[String], // опционально, отчество сотрудника

683

"organization": Option[String], // опционально, организация сотрудника

684

"division": Option[String], // опционально, подразделение сотрудника

685

"post": Option[String], // опционально, должность сотрудника

686

"clock_number": Option[String], // опционально, табельный номер сотрудника

687

"document_number": Option[String], // опционально, номер документа сотрудника

688

"phone": Option[String], // опционально, номер телефона

689

"email": Option[String], // опционально, адрес электронной почты

690

"accessLevels": Option[List[String]], // опционально, массив идентификаторов уровней доступа ВИС в формате UUID

691

"passType": Option[String], // опционально, тип пропуска. Возможные значения: REGULAR - постоянный, TEMPORARY - временный, ONETIME - разовый. Если значение не указано - используется тип REGULAR

692

"activation_date": Option[Long], // опционально, дата начала действия пропуска в формате Unix timestamp (в секундах)

693

"expiration_date": Option[Long], // опционально, дата окончания действия пропуска в формате Unix timestamp (в секундах)

694

"card": Option[Long], // опционально, номер карты владельца

695

"facility": Option[Long], // опционально, код предприятия карты владельца

696

"info": { // опционально, произвольные данные о сотруднике в формате "ключ-значение"

"anyKey": "anyValue"

}

}

]

=== {{id name="Интеграцияс«внешними»информационнымисистемами(ВИС)-ПоискUUIDвладельцевВИС,созданныхилиизменённыхзауказанныйинтервалвремени"/}}Поиск UUID владельцев ВИС, созданных или изменённых за указанный интервал времени ===

705

706

707

Факты создания и изменения владельцев и пропусков ВИС выводятся по соответствующим записям системного журнала за указанный интервал времени. Это значит, что туда попадают все изменения, сделанные оператором на текущем сетевом узле, все изменения от других узлов, и все изменения через ВИС API. При анализе **игнорируются** некоторые изменения, вносимые в рамках процедуры прохода, в частности:

708

709

* Изменения времени последнего прохода по пропуску

710

* Изменения зоны контроля повторного прохода

711

712

В случае автоматического изъятия разового пропуска по факту прохода через точку доступа, помеченную меткой "ТочкаДоступаВыход", изменения **учитываются** в данном алгоритме.

URL запроса:

POST /plugin/eis-pacs-integration/persons/uuids/search/by-modified

Тело запроса:

{

"modifiedFrom": Option[String], // опционально, дата и время начала поиска в формате ISO 8601 по формату yyyy-MM-dd'T'HH:mm:ss.SSSXXX (пример: "2023-11-15T08:34:19.000+03:00"). Значение по умолчанию - месяц назад относительно текущей даты

727

"modifiedTo": Option[String] // опционально, дата и время конца поиска в формате ISO 8601 по формату (пример: "2023-11-15T08:34:19.000+03:00"). Значение по умолчанию - текущая дата

}

В случае, если дата начала поиска после даты конца – возвращается ошибка.

732

733

В случае, если между датой начала и конца больше 6 месяцев – возвращается ошибка.

734

735

В остальных случаях тело ответа:

736

737

738

[ // обязательно, массив результатов поиска

"$UUID_1",

"$UUID_2"

]

=== {{id name="Интеграцияс«внешними»информационнымисистемами(ВИС)-СписоклицензированныхТДВИС"/}}Список лицензированных ТД ВИС ===

URL запроса:

GET /plugin/eis-pacs-integration/access-points/

750

751

752

(% style="letter-spacing:0.0px" %)Тело ответа:

[

{

"token": String, // обязательно, сквозной идентификатор ТД

758

"name": String, // обязательно, название ТД

759

"tags": Option[String] // опционально, массив произвольных строковых меток ТД (при наличии)

}

]

Поле {{code language="none"}}tags{{/code}} характеризует дополнительные не обязательные свойства точки доступа, в частности:

765

766

* {{code language="none"}}AccessPointEntry — {{/code}}устанавливается в поле {{code language="none"}}tags{{/code}} в случае, если в Платформе НЕЙРОСС для элемента данной ТД установлена пользовательская метка {{code language="none"}}ТочкаДоступаВход{{/code}}

767

* {{code language="none"}}AccessPointExit{{/code}}— аналогично для пользовательской метки {{code language="none"}}ТочкаДоступаВыход{{/code}}

768

769

Данные метки могут быть использованы ВИС для последующего различения событий доступа от входных и выходных точек доступа (см. ниже)

770

771

772

**По умолчанию элементы точек доступа не содержат пользовательских меток**. Это дополнительный механизм, позволяющий придать расширенную семантику точкам доступа, при необходимости. (% style="letter-spacing:0.0px" %)ВИС может как ориентироваться на данные метки (при условии их расстановки в Платформе НЕЙРОСС ~[[[doc:ui.Параметры узла.Элементы.Пользовательские метки.WebHome]]]), так и вести собственный учёт входных и выходных ТД ВИС.

(% style="font-size:16.0px; font-weight:bold; letter-spacing:-0.006em" %)**Инициирование транзакции доступа**

777

778

779

(% style="color:#333333" %)Для использования данной функции необходимо, чтобы в Платформе НЕЙРОСС имелся хотя бы один пользователь с правом общего конфигурирования, и учётные записи должны быть синхронизированы с контроллерами доступа.

URL запроса:

POST /plugin/eis-pacs-integration/pacs-transaction/

Тело запроса:

{

"person": String, // обязательно, идентификатор владельца пропуска, осуществляющего доступ

794

"accessPoint": String // обязательно, идентификатор ТД, через которую осуществляется доступ

}

(% style="letter-spacing:0.0px" %)Тело ответа:

{

"result": String, // обязательно, результат транзакции. Возможные значения: success - проход совершён, error - проход не совершён, нет прав на ТД и т. п.

803

"meta": { // обязательно, метаданные о транзакции

804

"person": String,

805

"accessPoint": String,

806

"transactionBegin": String, // дата и время старта транзакции в формате ISO (UTC). Пример: 2020-07-10 15:00:00

807

"transactionEnd": String // дата и время окончания транзакции

808

},

809

"error": Option[String] // обязательно при result == error. Текстовое описание ошибки

}

(% style="letter-spacing:0.0px" %)Ответ с result == success возвращается по факту получения события //«Проход совершён»// от контроллера доступа.

814

815

Ответ с result == error возвращается в следующих случаях:

816

817

1. Не найден владелец или ТД, либо они не находятся в подмножестве ВИС.

818

1. В уровне доступа владельца нет прав на переданную ТД ВИС.

819

1. Не удалось отправить запрос на контроллер (сетевые проблемы и т. п.)

820

1. Получено событие о запрете доступа от контроллера в результате детальной проверки прав (просрочен пропуск и т. п.).

821

822

Если в течение заданного таймаута ожидания транзакции доступа не удалось получить информацию о решении контроллера (не дошло событие), транзакция также завершается с ошибкой.

823

824

== {{id name="Интеграцияс«внешними»информационнымисистемами(ВИС)-РаботассобытиямидоступаВИС"/}}Работа с событиями доступа ВИС ==

825

826

Плагин НЕЙРОСС ВИС позволяет «внешней» системе осуществлять подписку на получение событий доступа, связанных с пропусками ВИС, асинхронно получать их в реальном времени и инициировать процедуру «довычитывания» пропущенных событий (например, за период отсутствия связи).

827

828

События доступа ВИС – это такие события доступа, которые удовлетворяют следующим критериям:

829

830

1. Событие отправлено от точки доступа ВИС — (% style="color:#333333" %)такой точки доступа, которая добавлена в УД ВИС и активирована/лицензирована в настройках плагина(%%);

831

1. Событие связано с владельцем пропуска ВИС — (% style="color:#333333" %)такие владельцы пропусков, у которых есть хотя бы один УД ВИС(%%).

832

833

«Внешняя» информационная система может оформить подписку на Платформу НЕЙРОСС, указав URL, на который Платформа будет посылать все события доступа ВИС. Данная функция может быть использована «внешней» системой для самостоятельного формирования данных по учёту рабочего времени.

834

835

=== {{id name="Интеграцияс«внешними»информационнымисистемами(ВИС)-Подпискинасобытиявреальномвремени"/}}Подписки на события в реальном времени ===

836

837

**Оформление подписки**

838

839

(% style="letter-spacing:0.0px" %)URL запроса:

840

841

842

POST /plugin/eis-pacs-integration/events/subscriptions

Тело запроса:

{

"consumerReference": String // обязательно, полный URL-адрес получателя событий, например: https://webhook.site/2a8f447d-d0ed-40c2-a6ae-d8c1a41e09f0

}

(% style="letter-spacing:0.0px" %)Тело ответа:

{

"subscriptionId": String // обязательно, уникальный строковый идентификатор подписки

}

**Удаление подписки**

862

863

(% style="letter-spacing:0.0px" %)URL запроса:

864

865

866

DELETE /plugin/eis-pacs-integration/events/subscriptions/:subscriptionId

=== {{id name="Интеграцияс«внешними»информационнымисистемами(ВИС)-Получениесобытий"/}}Получение событий ===

871

872

При получении события доступа, связанного с пропуском ВИС, оно пересылается в реальном времени на URL-адрес каждой подписки посредством HTTP-запроса с методом POST. Запрос имеет заголовок Content-Type: application/json и тело в следующем формате:

{

"eventId": Long // обязательно, id события ВИС

877

"headline": String, // обязательно, текстовое описание события

878

"person": String, // обязательно, идентификатор владельца пропуска ВИС

879

"eventTags": List[String], // обязательно, метки событий

880

"sent": String, // обязательно, время отправки события с контроллера, дата и время в ISO 8601

881

"registered": String // обязательно, время получения события Платформой НЕЙРОСС, дата и время в ISO 8601

882

"accessPoint": Option[String] // опционально, идентификатор ТД-источника события

}

(% style="letter-spacing:0.0px" %)Пример отправляемого события:

{

"eventId": 21,

"headline": "Доступ разрешен",

892

"person": "d5c919ce-7e7e-4778-aaac-0fb101600e0e",

"eventTags": [

"PACS",

"AccessGranted"

],

"sent": "2023-11-15T08:34:19+03:00",

898

"registered": "2023-11-15T08:34:19+03:00",

899

"accessPoint": "uuid:8d9e4802-5540-498b-b35b-39f946196251:7d3feddb-fecc-413d-86a6-1f7ecfbd941e"

}

Поле {{code language="none"}}eventId {{/code}}содержит последовательно возрастающее уникальное число, такое, что каждое последующее событие имеет {{code language="none"}}eventId {{/code}}больше предыдущего. Анализ данного поля может быть использован «внешней» системой для детектированиz пропущенных событий.

904

905

Поле {{code language="none"}}eventTags {{/code}}содержит массив меток — строк, определяющих тип и семантику события. В общем случае метки могут быть любые, для типовых сценариев учёта рабочего времени необходимо понимать смысл следующих меток:

906

907

1. //AccessGranted //– доступ разрешён

908

1. //AccessDenied //– доступ запрещён

909

910

Сетевой таймаут ожидания ответа от подписчика равен 10 секундам, может быть изменён в конфигурационном файле.

911

912

913

После регистрации события от пропуска ВИС оно остаётся "событием ВИС" навсегда – даже если администратор изменит настройки УД ВИС таким образом, что пропуск, с которым связано событие, перестанет быть пропуском ВИС.

914

915

Аналогичным образом, уже полученное событие от не-ВИС пропуска не может стать видимым для ВИС, даже при назначении пропуску УД ВИС.

916

917

События, зарегистрированные до установки плагина \ назначения УД ВИС, недоступны для ВИС

=== {{id name="Интеграцияс«внешними»информационнымисистемами(ВИС)-Вычитываниеисторическихсобытий"/}}Вычитывание исторических событий ===

922

923

«Внешняя» информационная система может инициативно выполнить процедуру вычитывания архивных событий ВИС из Платформы с различными параметрами. Типовые сценарии использования данной функции:

924

925

1. Вычитывание событий ВИС, которые были зарегистрированы до момента оформления подписки на «живые» события;

926

1. Детектирование «внешней» системой пропущенных «живых» событий и их довычитывание.

**Получение исторического события по конкретному eventId**

931

932