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

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

Общие сведения

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

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

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

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

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

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

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

Содержание:

Лицензирование

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

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

ВАЖНО

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

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

Подготовка к настройке

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

Плагину интеграции будут доступны точки доступа, которые которые указаны хотя бы в одном УД ВИС — ТД ВИС, при этом они должны быть указаны в настройках плагина [Настройка плагина интеграции].
Задайте пропускам, транзакция по которым может быть инициирована из ВИС, один или несколько УД ВИС.

Одному пропуску могут быть назначены как УД ВИС, так и «чисто внутренние» УД НЕЙРОСС. Для задания нескольких уровней используйте режим доступа [Режимы доступа].
ОГРАНИЧЕНИЯ ВИС
АРМ НЕЙРОСС обеспечивает полное управление владельцами, пропусками и уровнями доступа ВИС. «Внешняя» информационная система может:
1. Получить из НЕЙРОСС только УД ВИС;
2. Получить из НЕЙРОСС и управлять только ТД ВИС;
3. Получить из НЕЙРОСС данные только тех пропусков и их владельцев, которые содержат хотя бы один УД ВИС;
4. Создавать любых новых владельцев и их пропуска и назначать им УД из множества УД ВИС.
ВИС оперирует только разрешённым подмножеством ТД, УД, владельцев и пропусков. При помощи добавления или удаления префикса в названии УД администратор НЕЙРОСС может управлять подмножеством данных, «видимых» для ВИС.
ВИС не может:
1. Удалять владельцев и пропуска;
2. Создавать, удалять и изменять УД;
3. Создавать, удалять и изменять ТД.
Эти функции требуется выполнять из АРМ НЕЙРОСС.

Настройка плагина интеграции

Добавление плагина

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

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

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

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

Настройка плагина

После установки наведите указатель мыши на строку с плагином и нажмите на кнопку Настроить.

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

Параметр	Комментарий
Максимальное количество точек доступа ВИС	Параметр, заданный в лицензии. Определяет количество точек доступа, которыми может управлять «внешняя» информационная система.
Таймаут ожидания транзакции доступа, мс	Период времени, в течение которого ожидается ответ от НЕЙРОСС о результате транзакции доступа, инициированной из ВИС (удалённое предъявление идентификатора на точку доступа НЕЙРОСС). Транзакция доступа завершается по факту получения события «Доступ разрешён» или «Доступ запрещён» от контроллера доступа [События БОРЕЙ]. Если точка доступа не готова обработать транзакцию (например, — еще не закрыта дверь в результате предыдущей транзакции, или точка доступа находится в состоянии Взлом), плагин НЕЙРОСС ВИС будет ожидать ответа в течение заданного времени таймаута, после чего завершит транзакцию ВИС с ошибкой.
API-токен	Данный токен должен передаваться ВИС в каждом запросе в следующем виде: Authorization: Bearer TOKEN , где TOKEN — указанный в поле символьный ряд, например: Authorization: Bearer ce6b228c-9f09-47bd-b5d6-933abc894905 Вы можете изменить автоматически сгенерированный токен на собственный.
Точки доступа	Перечень точек доступа НЕЙРОСС, которые будут «видимы» для ВИС и разрешены для транзакций доступа, инициируемых из ВИС. Количество точек доступа ограничивается параметрами лицензии. При выборе количества, превышающего значение в поле «Максимальное количество точек доступа ВИС», вы получите сообщение об ошибке.
Текущее количество владельцев пропусков ВИС	Количество владельцев пропусков, в режиме доступа которых задан хотя бы один уровень доступа ВИС. Владельцы и пропуска ВИС могут создаваться и изменяться как из ВИС, так и напрямую в АРМ НЕЙРОСС Доступ. Удаление владельцев и пропусков доступно только из сети НЕЙРОСС.

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

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

Описание интеграционного HTTP-API

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

Авторизация

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

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

Authorization: Bearer TOKEN

, где TOKEN — указанный в настройках плагина API-токен.

Список УД ВИС

URL запроса:

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

Тело ответа:

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

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

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

[
   {
      "uuid": "820a1259-fbe0-4594-913e-4ab869e60b19",
      "name": "[И] КПП 2",
      "accessPoints":[
      "uuid:fe53892b-2e0e-44a8-98e1-5de2795b289f:6e71dce6-e1aa-4ff4-b213-55391c989b2c"
      ]
   },
   {
      "uuid": "3260b54b-03f9-48cc-8593-4387b9e867e6",
      "name": "[И] КПП 3",
      "accessPoints":[
      "uuid:fe53892b-2e0e-44a8-98e1-5de2795b289f:f5d4ba84-ab03-42e4-8e4d-2fc4e12de1ba"
      ]
   },
   {
      "uuid": "3db2237d-04bc-4932-8d03-86d1677c020d",
      "name": "[И] КПП 4",
      "accessPoints":[
      "uuid:fe53892b-2e0e-44a8-98e1-5de2795b289f:1e1614f2-372a-402a-90ee-13fa3c5899fe"
      ]
   },
   {
      "uuid": "0dfb462d-d5c3-402d-9075-e726ea94bd49",
      "name": "[И] КПП 1",
      "accessPoints":[
      "uuid:fe53892b-2e0e-44a8-98e1-5de2795b289f:987f1ea2-93c9-449f-b38f-5e20d7e8edcd"
      ]
   }
]

Полученные уникальные идентификаторы (UUID) уровней доступа ВИС должны использоваться при создании пропусков [Создание и изменение владельцев и пропусков ВИС].

Список ТД ВИС

URL запроса:

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

Тело ответа:

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

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

[
   {
      "token": "uuid:fe53892b-2e0e-44a8-98e1-5de2795b289f:987f1ea2-93c9-449f-b38f-5e20d7e8edcd",
      "name": "Точка доступа 0.1"
   },
   {
      "token": "uuid:fe53892b-2e0e-44a8-98e1-5de2795b289f:f5d4ba84-ab03-42e4-8e4d-2fc4e12de1ba",
      "name": "Точка доступа 2.1"
   }
]

Полученные уникальные идентификаторы (UUID) точек доступа ВИС должны использоваться при инициировании транзакции доступа [Инициирование транзакции доступа].

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

URL запроса:

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

Тело ответа:

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

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

{
      "count": 7
}

Список владельцев ВИС

URL запроса:

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

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

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

Тело ответа:

[
   {
      "uuid": String, // обязательно, сквозной идентификатор владельца в формате UUID
      "surname": String, // обязательно, фамилия сотрудника
      "name": String, // обязательно, имя сотрудника
      "patronymic": Option[String], // опционально, отчество сотрудника
	  "organization": Option[String], // опционально, организация сотрудника
      "division": Option[String], // опционально, подразделение сотрудника
      "post": Option[String], // опционально, должность сотрудника
      "clock_number": Option[String], // опционально, табельный номер сотрудника
      "document_number": Option[String], // опционально, номер документа сотрудника
      "phone": Option[String], // опционально, номер телефона
      "email": Option[String], // опционально, адрес электронной почты
      "accessLevels": Option[List[String]], // опционально, массив идентификаторов уровней доступа ВИС в формате UUID
      "passType": Option[String], // опционально, тип пропуска. Возможные значения: REGULAR - постоянный, TEMPORARY - временный, ONETIME - разовый. Если значение не указано - используется тип REGULAR
      "activation_date": Option[Long], // опционально, дата начала действия пропуска в формате Unix timestamp (в секундах)
      "expiration_date": Option[Long], // опционально, дата окончания действия пропуска в формате Unix timestamp (в секундах)
	  "card": Option[Long], // опционально, номер карты владельца
	  "facility": Option[Long], // опционально, код предприятия карты владельца
      "info": { // опционально, произвольные данные о сотруднике в формате "ключ-значение"
         "anyKey": "anyValue"
      }
   }
]

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

[
   {
      "uuid": "21e10f5d-7af7-44ba-b1a3-d0b9cf429437",
      "surname": "Аспидов",
      "name": "Иван",
      "patronymic": "Сергеевич",
      "accessLevels":[
      "0dfb462d-d5c3-402d-9075-e726ea94bd49"
      ],
      "passType": "REGULAR",
      "info":{
      "inactivity": "false",
      "Birthday": "1994-12-05"
      }
   },
   {
      "uuid": "022abfc4-3809-4ce3-bfc4-cbdb4a07f726",
      "surname": "Акимов",
      "name": "Сергей",
      "patronymic": "Сергеевич",
      "accessLevels":[
      "0dfb462d-d5c3-402d-9075-e726ea94bd49"
      ],
      "passType": "REGULAR",
      "info":{
      "inactivity": "false",
      "Birthday": "1994-02-18"
      }
   },
   {
      "uuid": "54b9fa8c-4a36-4431-8f74-c6ad5897fb7f",
      "surname": "Петров",
      "name": "Петр",
      "patronymic": "Сергеевич",
      "accessLevels":[
      "0dfb462d-d5c3-402d-9075-e726ea94bd49"
      ],
      "passType": "REGULAR",
      "info":{"pacs:folder": "c84e7f59-d37a-4d09-9cf9-fab38b11221a", "neyross:automation:responsibleTelegramChatId": "1055492440", "inactivity": "false",…}
   },

]

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

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

Получение информации о конкретном владельце и пропуске ВИС

URL запроса:

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

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

Тело ответа:

{
   "uuid": String, // обязательно, сквозной идентификатор владельца в формате UUID
   "surname": String, // обязательно, фамилия сотрудника
   "name": String, // обязательно, имя сотрудника
   "patronymic": Option[String], // опционально, отчество сотрудника
   "organization": Option[String], // опционально, организация сотрудника
   "division": Option[String], // опционально, подразделение сотрудника
   "post": Option[String], // опционально, должность сотрудника
   "clock_number": Option[String], // опционально, табельный номер сотрудника
   "document_number": Option[String], // опционально, номер документа сотрудника
   "phone": Option[String], // опционально, номер телефона
   "email": Option[String], // опционально, адрес электронной почты
   "accessLevels": List[String], // обязательно, массив идентификаторов уровней доступа ВИС в формате UUID
   "passType": Option[String], // опционально, тип пропуска. Возможные значения: REGULAR - постоянный, TEMPORARY - временный, ONETIME - разовый. Если значение не указано - используется тип REGULAR
   "activation_date": Option[Long], // опционально, дата начала действия пропуска в формате Unix timestamp (в секундах)
   "expiration_date": Option[Long], // опционально, дата окончания действия пропуска в формате Unix timestamp (в секундах)
   "card": Option[Long], // опционально, номер карты владельца
   "facility": Option[Long], // опционально, код предприятия карты владельца
   "info": { // опционально, произвольные данные о сотруднике в формате "ключ-значение"
      "anyKey": "anyValue"
   }
}

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

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

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

Создание и изменение владельца и пропуска ВИС

URL запроса:

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

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

{
   "uuid": String, // обязательно, сквозной идентификатор владельца в формате UUID
   "surname": String, // обязательно, фамилия сотрудника
   "name": String, // обязательно, имя сотрудника
   "patronymic": Option[String], // опционально, отчество сотрудника
   "organization": Option[String], // опционально, организация сотрудника
   "division": Option[String], // опционально, подразделение сотрудника
   "post": Option[String], // опционально, должность сотрудника
   "clock_number": Option[String], // опционально, табельный номер сотрудника
   "document_number": Option[String], // опционально, номер документа сотрудника
   "phone": Option[String], // опционально, номер телефона
   "email": Option[String], // опционально, адрес электронной почты
   "accessLevels": List[String], // обязательно, массив идентификаторов уровней доступа ВИС в формате UUID
   "passType": Option[String], // опционально, тип пропуска. Возможные значения: REGULAR - постоянный, TEMPORARY - временный, ONETIME - разовый. Если значение не указано - используется тип REGULAR
   "activation_date": Option[Long], // опционально, дата начала действия пропуска в формате Unix timestamp (в секундах)
   "expiration_date": Option[Long], // опционально, дата окончания действия пропуска в формате Unix timestamp (в секундах)
   "info": { // опционально, произвольные данные о сотруднике в формате "ключ-значение"
      "anyKey": "anyValue"
   },
   "photo": Option[String] // опционально, фото сотрудника в формате BASE64. Если не передано - создаётся владелец без фотографии \ не изменяется сохранённая ранее фотография
}

Тело ответа:

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

Создание и изменение нескольких владельцев и пропусков ВИС

URL запроса:

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

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

[ // обязательно, массив владельцев
  {
   "uuid": String, // обязательно, сквозной идентификатор владельца в формате UUID
   "surname": String, // обязательно, фамилия сотрудника
   "name": String, // обязательно, имя сотрудника
   "patronymic": Option[String], // опционально, отчество сотрудника
   "organization": Option[String], // опционально, организация сотрудника
   "division": Option[String], // опционально, подразделение сотрудника
   "post": Option[String], // опционально, должность сотрудника
   "clock_number": Option[String], // опционально, табельный номер сотрудника
   "document_number": Option[String], // опционально, номер документа сотрудника
   "phone": Option[String], // опционально, номер телефона
   "email": Option[String], // опционально, адрес электронной почты
   "accessLevels": List[String], // обязательно, массив идентификаторов уровней доступа ВИС в формате UUID
   "passType": Option[String], // опционально, тип пропуска. Возможные значения: REGULAR - постоянный, TEMPORARY - временный, ONETIME - разовый. Если значение не указано - используется тип REGULAR
   "activation_date": Option[Long], // опционально, дата начала действия пропуска в формате Unix timestamp (в секундах)
   "expiration_date": Option[Long], // опционально, дата окончания действия пропуска в формате Unix timestamp (в секундах)
   "info": { // опционально, произвольные данные о сотруднике в формате "ключ-значение"
      "anyKey": "anyValue"
   },
   "photo": Option[String] // опционально, фото сотрудника в формате BASE64. Если не передано - создаётся владелец без фотографии \ не изменяется сохранённая ранее фотография
  }
]

Тело ответа:

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

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

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

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

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

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

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

Список лицензированных ТД ВИС

URL запроса:

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

Тело ответа:

[
   {
      "token": String, // обязательно, сквозной идентификатор ТД
      "name": String, // обязательно, название ТД
      "tags": Option[String] // опционально, массив произвольных строковых меток ТД (при наличии)
   }
]

Поле tags характеризует дополнительные не обязательные свойства точки доступа, в частности:

AccessPointEntry — устанавливается в поле tags в случае, если в Платформе НЕЙРОСС для элемента данной ТД установлена пользовательская метка ТочкаДоступаВход
AccessPointExit– — аналогично для пользовательской метки ТочкаДоступаВыход

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

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

Инициирование транзакции доступа

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

URL запроса:

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

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

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

Тело ответа:

{
   "result": String, // обязательно, результат транзакции. Возможные значения: success - проход совершён, error - проход не совершён, нет прав на ТД и т. п.
   "meta": { // обязательно, метаданные о транзакции
     "person": String,
     "accessPoint": String,
     "transactionBegin": String, // дата и время старта транзакции в формате ISO (UTC). Пример: 2020-07-10 15:00:00
     "transactionEnd": String // дата и время окончания транзакции
   },
   "error": Option[String] // обязательно при result == error. Текстовое описание ошибки
}

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

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

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

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

Работа с событиями доступа ВИС

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

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

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

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

Подписки на события в реальном времени

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

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

Получение событий

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

{
     "eventId": Long // обязательно, id события ВИС
     "headline": String, // обязательно, текстовое описание события
     "person": String, // обязательно, идентификатор владельца пропуска ВИС
     "eventTags": List[String], // обязательно, метки событий
     "sent": String, // обязательно, время отправки события с контроллера, дата и время в ISO 8601
     "registered": String // обязательно, время получения события Платформой НЕЙРОСС, дата и время в ISO 8601
     "accessPoint": Option[String] // опционально, идентификатор ТД-источника события
}

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

{
    "eventId": 21,
    "headline": "Доступ разрешен",
    "person": "d5c919ce-7e7e-4778-aaac-0fb101600e0e",
    "eventTags": [
        "PACS",
        "AccessGranted"
    ],
    "sent": "2023-11-15T08:34:19+03:00",
    "registered": "2023-11-15T08:34:19+03:00",
    "accessPoint": "uuid:8d9e4802-5540-498b-b35b-39f946196251:7d3feddb-fecc-413d-86a6-1f7ecfbd941e"
}

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

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

AccessGranted – доступ разрешён
AccessDenied – доступ запрещён

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

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

Вычитывание исторических событий

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

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

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

URL запроса:

GET /plugin/eis-pacs-integration/events/history_events_by_id/?id=:eventId

В ответ отправляется событие по данному eventId, если оно есть (формат см. выше).

Получение исторических событий по нескольким eventId

URL запроса:

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

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

{
    "eventIds": List[Long] // обязательно, массив eventId
}

В ответ отправляется массив событий по данным eventIds

Получение исторических событий за указанный промежуток времени

URL запроса:

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

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

{
    "timeFrom": String, // обязательно, дата и время начала поиска в формате ISO 8601
    "timeTo": String, // обязательно, дата и время конца поиска в формате ISO 8601
    "limit": Option[Long], // опционально, максимальное количество возвращаемых событий. Значение по умолчанию 1000
    "offset": Option[Long] // опционально, сдвиг для постраничного поиска. Значение по умолчанию 0
}

В ответ отправляется массив событий для указанных параметров.

Быстрые ссылки

Дерево страниц

Общие сведения

Лицензирование

Подготовка к настройке

Настройка плагина интеграции

Добавление плагина

Настройка плагина

Описание интеграционного HTTP-API

Авторизация

Список УД ВИС

Список ТД ВИС

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

Список владельцев ВИС

Создание и изменение владельца и пропуска ВИС

Создание и изменение нескольких владельцев и пропусков ВИС

Список лицензированных ТД ВИС

Работа с событиями доступа ВИС

Подписки на события в реальном времени

Получение событий

Вычитывание исторических событий