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

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

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

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

32

33

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

|=(((

Тип узла

)))|=(((

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

)))|=(((

Комментарий

)))

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

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

)))|(((

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

)))|(((

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

48

)))

49

|(((

50

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

51

)))|(((

52

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

53

)))

54

|(((

55

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

56

)))|(((

57

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

)))

**ВАЖНО**

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

64

65

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

66

67

68

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

69

70

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

71

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

72

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

73

Дата выхода

74

)))|=(% 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.

111

)))

112

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

113

1.0. …

114

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

115

11.08.2023

116

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

117

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

118

)))

119

120

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

121

122

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

123

124

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

125

126

127

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

128

129

130

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

Например:

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

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

142

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

143

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

144

145

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

146

147

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

148

149

150

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

151

152

153

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

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

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

159

160

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

161

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

162

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

163

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

164

165

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

ВИС не может:

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

170

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

171

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

172

173

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

174

175

176

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

177

178

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

179

180

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

181

182

183

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

184

185

186

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

187

188

189

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

190

191

192

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

193

194

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

195

196

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

197

198

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

199

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

|=(((

Параметр

)))|=(((

Комментарий

)))

|(((

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

208

)))|(((

209

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

210

)))

211

|(((

212

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

213

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

214

)))|(((

215

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

)))

|(((

API-токен

)))|(((

(((

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

222

223

224

Authorization: Bearer TOKEN

225

226

227

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

228

229

230

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

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

)))

)))

|(((

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

)))|(((

(((

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

243

244

245

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

)))

)))

|(((

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

251

)))|(((

252

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

)))

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

258

259

260

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

261

262

263

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

264

265

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

266

267

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

268

269

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

270

271

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

272

273

274

Authorization: Bearer TOKEN

275

276

277

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

278

279

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

URL запроса:

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

Тело ответа:

[

{

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

293

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

294

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

}

]

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

300

301

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

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

[

{

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

309

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

310

"accessPoints":[

311

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

]

},

{

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

316

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

317

"accessPoints":[

318

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

]

},

{

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

323

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

324

"accessPoints":[

325

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

]

},

{

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

330

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

331

"accessPoints":[

332

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

]

}

]

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

339

340

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

URL запроса:

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

Тело ответа:

[

{

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

354

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

}

]

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

[

{

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

365

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

366

},

367

{

368

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

369

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

}

]

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

375

376

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

407

408

409

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

410

411

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

412

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

Тело ответа:

[

{

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

420

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

421

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

422

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

423

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

424

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

425

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

426

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

427

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

428

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

429

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

430

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

431

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

432

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

433

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

434

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

435

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

436

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

"anyKey": "anyValue"

}

}

]

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

[

{

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

449

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

450

"name": "Иван",

451

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

452

"accessLevels":[

453

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

454

],

455

"passType": "REGULAR",

456

"info":{

457

"inactivity": "false",

458

"Birthday": "1994-12-05"

}

},

{

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

463

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

464

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

465

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

466

"accessLevels":[

467

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

468

],

469

"passType": "REGULAR",

470

"info":{

471

"inactivity": "false",

472

"Birthday": "1994-02-18"

}

},

{

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

477

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

478

"name": "Петр",

479

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

480

"accessLevels":[

481

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

482

],

483

"passType": "REGULAR",

484

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

},

]

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

491

492

493

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

494

495

496

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

URL запроса:

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

502

503

504

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

Тело ответа:

{

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

511

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

512

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

513

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

514

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

515

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

516

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

517

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

518

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

519

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

520

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

521

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

522

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

523

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

524

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

525

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

526

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

527

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

"anyKey": "anyValue"

}

}

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

536

537

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

538

539

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

540

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

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

URL запроса:

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

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

{

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

557

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

558

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

559

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

560

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

561

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

562

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

563

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

564

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

565

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

566

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

567

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

568

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

569

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

570

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

571

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

572

"anyKey": "anyValue"

573

},

574

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

}

Тело ответа:

{

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

583

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

}

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

URL запроса:

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

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

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

599

{

600

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

601

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

602

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

603

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

604

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

605

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

606

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

607

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

608

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

609

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

610

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

611

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

612

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

613

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

614

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

615

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

616

"anyKey": "anyValue"

617

},

618

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

}

]

Тело ответа:

{

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

628

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

629

{

630

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

631

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

}

]

}

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

639

640

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

641

642

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

643

644

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

645

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

646

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

647

648

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

649

650

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

651

652

653

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

URL запроса:

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

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

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

"$UUID_1",

"$UUID_2"

]

Тело ответа:

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

674

{

675

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

676

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

677

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

678

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

679

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

680

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

681

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

682

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

683

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

684

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

685

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

686

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

687

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

688

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

689

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

690

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

691

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

692

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

"anyKey": "anyValue"

}

}

]

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

701

702

703

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

704

705

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

706

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

707

708

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

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

723

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

}

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

728

729

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

730

731

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

732

733

734

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

"$UUID_1",

"$UUID_2"

]

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

URL запроса:

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

Тело ответа:

[

{

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

754

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

755

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

}

]

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

761

762

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

763

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

764

765

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

766

767

768

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

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

773

774

775

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

URL запроса:

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

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

{

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

790

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

}

Тело ответа:

{

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

799

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

800

"person": String,

801

"accessPoint": String,

802

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

803

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

804

},

805

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

}

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

810

811

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

812

813

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

814

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

815

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

816

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

817

818

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

819

820

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

821

822

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

823

824

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

825

826

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

827

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

828

829

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

830

831

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

832

833

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

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="Интеграцияс«внешними»информационнымисистемами(ВИС)-Получениесобытий"/}}Получение событий ===

867

868

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

{

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

873

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

874

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

875

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

876

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

877

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

878

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

}

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

{

"eventId": 21,

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

888

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

"eventTags": [

"PACS",

"AccessGranted"

],

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

894

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

895

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

}

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

900

901

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

902

903

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

904

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

905

906

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

907

908

909

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

910

911

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

912

913

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

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

918

919

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

920

921

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

922

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

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

927

928