Входящие вебхуки: подключение СКУД

Входящие вебхуки СКУД позволяют вашей системе контроля доступа сообщать UnSpot о входе и выходе сотрудников. UnSpot использует эти события для автоматического чекина бронирований и аналитики посещаемости. Поддерживаются два варианта: универсальный JSON-endpoint для любой СКУД и специализированная интеграция Sigur.

1. Создание подключения

В разделе Настройка > Интеграции создайте подключение СКУД типа JSON. Вы сами указываете, в каких полях вашего payload лежат данные — так UnSpot подстраивается под любой формат:

После сохранения UnSpot сгенерирует уникальный токен endpoint’а — ваша СКУД будет отправлять события POST-запросами на URL с ним.

Связь офиса с точкой доступа. В окне подписки (Настройка → Интеграции → Входящие подписки) есть блок «Связь офиса с точкой доступа СКУД»: по нему UnSpot определяет, в какой офис пришёл сотрудник. Нажмите «Добавить офис», выберите офис и в поле «Укажите точку доступа» перечислите значения, которые ваша СКУД передаёт в атрибуте офиса, — например, названия турникетов и дверей. Каждое значение фиксируется клавишей Enter, уходом из поля или галочкой. Блок необязателен: подписка сохраняется и без него. В примере запроса ниже в атрибуте офиса передаётся «Штаб-квартира Москва» — чтобы такое событие отнеслось к офису, это значение должно стоять среди точек доступа.

• для одного офиса — не больше 100 точек доступа, название точки — не длиннее 255 символов;
• пробелы по краям и регистр не учитываются: точки хранятся и показываются строчными буквами;
• точка доступа уникальна в пределах компании: повтор внутри подписки поле подсвечивает надписью «Такое значение уже используется», а точку, уже указанную в другой подписке, не даст сохранить сервер — «Не удалось сохранить подписку. Указанные точки доступа должны быть уникальны.»;
• в добавленной строке обязательны офис и хотя бы одна точка доступа («Укажите хотя бы одну точку доступа»); выбрать можно только офис, заблокированные и удалённые офисы в списке не показываются;
• привязки удаляются вместе с подпиской. Если удалить офис, его строка в подписке останется: события по её точкам будут приходить без офиса, а пересохранить подписку получится, только убрав эту строку.

2. Отправка событий — POST /api/scud/json/{token}

curl -X POST -H "Content-Type: application/json" -H "Un-Token: <access token>" \
  https://acme.unspot.ru/api/scud/json/3f2a...-connection-token \
  -d '{
    "space": "Штаб-квартира Москва",
    "user": "anna.ivanova@example.com",
    "status": "in_office"
  }'

curl -X POST -H "Content-Type: application/json" -H "Un-Token: <access token>" \
  https://acme.unspot.ru/api/scud/json/3f2a...-connection-token \
  -d '{
    "space": "Штаб-квартира Москва",
    "user": "anna.ivanova@example.com",
    "status": "in_office"
  }'

• Идентификация пользователя: если значение — email, поиск идёт только по email, и при промахе остальные способы не пробуются. Если значение на email не похоже, UnSpot ищет по номеру пропуска, затем по ФИО, затем по отображаемому имени — поиск по отображаемому имени добавлен 07.09.2026. Неоднозначное совпадение на любом из шагов отклоняется.
• Поиск по отображаемому имени сравнивает строку целиком: пробелы по краям обрезаются, несколько пробелов подряд считаются одним, регистр не учитывается — " Иванов Иван " найдёт сотрудника с отображаемым именем Иванов Иван. В отличие от поиска по ФИО, слова не отбрасываются и обратный порядок слов не пробуется, а значение из одного слова тоже ищется. Правило одинаково для JSON и для Sigur.
• Статус: значение должно означать «в офисе» или «вне офиса». Временем события считается момент получения запроса UnSpot.
• События обрабатываются асинхронно; каждое (включая ошибки) записывается в журнал интеграций (Отчёты > История интеграций).

3. Что UnSpot делает с событием

• Отмечает пользователя как присутствующего в офисе / покинувшего офис.
• Подтверждает чекин бронирований, если политики чекина требуют присутствия в офисе.
• Пополняет аналитику и отчёты посещаемости офиса.
• Определяет офис посещения: значение атрибута офиса ищется среди точек доступа этой подписки без учёта регистра и пробелов по краям. Нашлось — офис записывается в журнал посещений; он виден в колонке «Офис» отчёта «История посещения офиса (СКУД)» и учитывается фильтром по офису в аналитике по данным СКУД. Не нашлось или атрибут пуст — событие всё равно обрабатывается, статус сотрудника меняется, но офис в журнале остаётся пустым.

Вариант Sigur

Для Sigur создайте подключение типа Sigur и укажите в Sigur URL уведомлений POST /api/scud/sigur/{token}. Отличия от JSON-варианта: тело — form-encoded (как отправляет Sigur), заголовок Un-Token не используется, значения направления вход / выход конвертируются автоматически. Блок «Связь офиса с точкой доступа СКУД» у подписки Sigur тот же: точкой доступа считается значение переменной из атрибута офиса — по умолчанию %APNAME%, название точки доступа Sigur. Для делегирования Sigur и mobile-ID есть отдельные endpoint’ы, настраиваемые со страницы интеграции Sigur.

Ошибки

• Integration not found — неверный токен endpoint’а.
• Access to subscription denied — заголовок Un-Token не совпадает с настроенным access token.
• Subscription deactivated — подключение отключено в UnSpot.
• User not found / Multiple users found by pass number — идентификатор пользователя не разрешился однозначно.
• Отсутствуют ключи офиса/пользователя/статуса — событие отклоняется и логируется.