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

1

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

2

3

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

4

5

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

6

7

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

8

9

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

10

* **Управление данными владельцев и пропусков** — создание, изменение владельцев и пропусков с загрузкой данных из ВИС в НЕЙРОСС и наоборот, — из НЕЙРОСС в ВИС.

11

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

12

13

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

14

15

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

16

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

17

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

18

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

19

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

20

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

21

22

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

23

24

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

25

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

26

27

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

28

29

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

|=(((

Тип узла

)))|=(((

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

)))|=(((

Комментарий

)))

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

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

)))|(((

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

)))|(((

Использование сервиса взаимодействия с «внешней» информационной системой (ВИС) посредством утвержденного API.

44

)))

45

|(((

46

Плагин НЕЙРОСС ВИС: максимальное количество точек доступа

47

)))|(((

48

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

49

)))

50

|(((

51

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

52

)))|(((

53

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

)))

**ВАЖНО**

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

60

61

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

62

63

64

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

65

66

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

67

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

68

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

69

Дата выхода

70

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

Комментарий

)))

|(((

1.5. …

)))|(((

06.11.2025

)))|(((

Добавлен метод 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.

107

)))

108

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

109

1.0. …

110

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

111

11.08.2023

112

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

113

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

114

)))

115

116

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

117

118

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

119

120

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

121

122

123

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

124

125

126

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

Например:

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

[[image:attach:plugin_eis_accesslevels.png||height="198"]]

138

//Пример уровней доступа для интеграции с ВИС//

139

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

140

141

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

142

143

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

144

145

146

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

147

148

149

[[image:attach:plugin_eis_accessrules.png||width="900"]]

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

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

155

156

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

157

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

158

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

159

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

160

161

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

ВИС не может:

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

166

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

167

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

168

169

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

170

171

172

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

173

174

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

175

176

Сервис работы с ВИС поставляется в виде плагина интеграции — независимого программный модуля, предназначенного для расширения функционала Платформы НЕЙРОСС. Установка плагина является стандартной процедурой и не зависит от предоставляемых функций. Перечень разработанных плагинов и порядок их установки приведён в разделе ~[[[doc:ui.Параметры узла.Плагины.WebHome]]].

177

178

179

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

180

181

182

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

183

184

185

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

186

187

188

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

189

190

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

191

192

[[image:attach:plugin_eis5.png||width="900"]]

193

194

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

195

[[image:attach:plugin_eis6.png]]

|=(((

Параметр

)))|=(((

Комментарий

)))

|(((

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

204

)))|(((

205

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

206

)))

207

|(((

208

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

209

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

210

)))|(((

211

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

)))

|(((

API-токен

)))|(((

(((

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

218

219

220

Authorization: Bearer TOKEN

221

222

223

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

224

225

226

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

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

)))

)))

|(((

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

)))|(((

(((

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

239

240

241

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

)))

)))

|(((

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

247

)))|(((

248

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

)))

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

254

255

256

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

257

258

259

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

260

261

Для передачи запроса и ответа используется формат JSON и соответствующий Content-Type: application/json.

262

263

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

264

265

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

266

267

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

268

269

270

Authorization: Bearer TOKEN

271

272

273

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

274

275

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

URL запроса:

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

Тело ответа:

[

{

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

289

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

290

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

}

]

[[image:attach:plugin_eis7_example1.png||width="900"]]

296

297

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

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

[

{

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

305

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

306

"accessPoints":[

307

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

]

},

{

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

312

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

313

"accessPoints":[

314

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

]

},

{

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

319

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

320

"accessPoints":[

321

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

]

},

{

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

326

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

327

"accessPoints":[

328

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

]

}

]

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

335

336

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

URL запроса:

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

Тело ответа:

[

{

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

350

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

}

]

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

[

{

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

361

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

362

},

363

{

364

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

365

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

}

]

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

371

372

=== {{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

403

404

405

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

406

407

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

408

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

Тело ответа:

[

{

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

416

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

417

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

418

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

419

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

420

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

421

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

422

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

423

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

424

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

425

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

426

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

427

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

428

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

429

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

430

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

431

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

432

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

"anyKey": "anyValue"

}

}

]

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

[

{

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

445

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

446

"name": "Иван",

447

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

448

"accessLevels":[

449

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

450

],

451

"passType": "REGULAR",

452

"info":{

453

"inactivity": "false",

454

"Birthday": "1994-12-05"

}

},

{

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

459

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

460

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

461

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

462

"accessLevels":[

463

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

464

],

465

"passType": "REGULAR",

466

"info":{

467

"inactivity": "false",

468

"Birthday": "1994-02-18"

}

},

{

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

473

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

474

"name": "Петр",

475

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

476

"accessLevels":[

477

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

478

],

479

"passType": "REGULAR",

480

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

},

]

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

487

488

489

В ответе выдаются только UUID УД ВИС, даже в случае, если в пропуске у владельца имеются и УД ВИС, и прочие УД.

490

491

492

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

URL запроса:

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

498

499

500

, где $PERSON_UUID — идентификатор владельца пропуска ВИС

Тело ответа:

{

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

507

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

508

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

509

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

510

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

511

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

512

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

513

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

514

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

515

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

516

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

517

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

518

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

519

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

520

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

521

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

522

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

523

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

"anyKey": "anyValue"

}

}

Если владелец пропуска для данного UUID не найден, возвращается HTTP-код 404.

532

533

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

534

535

1. Данные должны быть указаны в соответствующих полях из формы ввода по умолчанию.

536

1. Одному владельцу выдан один только один пропуск. В противном случае будет передан первый найденный номер. При создании большего количества пропусков корректная работа не гарантируется.

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

URL запроса:

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

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

{

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

553

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

554

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

555

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

556

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

557

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

558

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

559

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

560

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

561

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

562

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

563

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

564

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

565

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

566

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

567

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

568

"anyKey": "anyValue"

569

},

570

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

}

Тело ответа:

{

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

579

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

}

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

URL запроса:

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

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

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

595

{

596

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

597

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

598

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

599

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

600

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

601

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

602

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

603

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

604

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

605

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

606

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

607

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

608

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

609

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

610

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

611

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

612

"anyKey": "anyValue"

613

},

614

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

}

]

Тело ответа:

{

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

624

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

625

{

626

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

627

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

}

]

}

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

635

636

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

637

638

В случае, если у владельца пропуска на момент изменения имеются и УД ВИС, и прочие УД, то алгоритм формирования итогового списка УД для владельца следующий:

639

640

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

641

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

642

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

643

644

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

645

646

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

647

648

649

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

URL запроса:

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

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

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

"$UUID_1",

"$UUID_2"

]

Тело ответа:

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

670

{

671

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

672

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

673

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

674

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

675

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

676

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

677

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

678

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

679

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

680

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

681

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

682

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

683

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

684

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

685

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

686

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

687

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

688

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

"anyKey": "anyValue"

}

}

]

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

697

698

699

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

700

701

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

702

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

703

704

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

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"). Значение по умолчанию - месяц назад относительно текущей даты

719

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

}

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

724

725

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

726

727

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

728

729

730

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

"$UUID_1",

"$UUID_2"

]

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

URL запроса:

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

Тело ответа:

[

{

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

750

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

751

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

}

]

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

757

758

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

759

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

760

761

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

762

763

764

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

(% style="font-weight:bold" %)**Инициирование транзакции доступа**

769

770

771

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

URL запроса:

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

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

{

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

786

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

}

Тело ответа:

{

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

795

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

796

"person": String,

797

"accessPoint": String,

798

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

799

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

800

},

801

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

}

Ответ с result == success возвращается по факту получения события //«Проход совершён»// от контроллера доступа.

806

807

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

808

809

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

810

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

811

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

812

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

813

814

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

815

816

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

817

818

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

819

820

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

821

822

1. Событие отправлено от точки доступа ВИС — такой точки доступа, которая добавлена в УД ВИС и активирована/лицензирована в настройках плагина;

823

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

824

825

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

826

827

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

828

829

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

URL запроса:

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

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

{

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

}

Тело ответа:

{

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

}

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

URL запроса:

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

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

863

864

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

{

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

869

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

870

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

871

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

872

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

873

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

874

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

}

Пример отправляемого события:

{

"eventId": 21,

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

884

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

"eventTags": [

"PACS",

"AccessGranted"

],

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

890

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

891

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

}

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

896

897

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

898

899

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

900

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

901

902

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

903

904

905

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

906

907

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

908

909

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

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

914

915

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

916

917

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

918

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

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

923

924