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

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

1. Создание подписки

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

В блоке «Формат отправки данных» окно показывает образец JSON с вашими ключами. Кнопка «Добавить токен» создаёт секретный токен: его нужно передавать в каждом запросе в заголовке Un-Token. Токен показывается один раз — скопируйте его до сохранения, потом получить его будет невозможно. Без токена подписка тоже работает.

После сохранения подписка появится в списке, а в колонке «Ваш URL» — адрес с уникальным токеном подписки: на него ваша СКУД отправляет события POST-запросами.

Подписки, созданные до появления поля «Место». Если у старой подписки поле «Место» пустое, при её изменении — например, чтобы привязать точки доступа — окно не сохранится, пока поле не заполнено. После этого ключ места должен приходить в каждом событии, поэтому сначала убедитесь, что ваша СКУД его передаёт, или укажите ключ, который в событиях есть всегда.

Связь офиса с точкой доступа

В нижней части окна подписки — блок «Связь офиса с точкой доступа СКУД». По нему UnSpot определяет, в какой офис пришёл сотрудник. Блок необязателен: подписка сохраняется и без него, но тогда офис у событий не записывается.

1. Нажмите «Добавить офис» и в поле «Офис» выберите пространство — офис или вложенное в него пространство, например этаж. Отключённые пространства в списке не показываются.
2. В поле «Укажите точку доступа» нажмите «Добавить» и введите значение, которое ваша СКУД передаёт в ключе офиса, — например, название турникета или двери. Значение фиксируется клавишей Enter, уходом из поля или галочкой.
3. Повторите для остальных точек доступа этого офиса, а для другого офиса добавьте новую строку. Строку целиком убирает кнопка «Удалить».

Правила для точек доступа:

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

Пример: если в ключе офиса СКУД присылает Турникет 1, а эта точка доступа привязана к офису «Москва», событие запишется с офисом «Москва».

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"
  }'

Пример записан в старом формате ключей — space, user и status, без ключа места. С настройками формы по умолчанию тело запроса должно содержать ключи office, location, email и status, иначе событие будет отклонено с ошибкой Invalid payload. Значение Штаб-квартира Москва, которое здесь стоит в space, передавайте в ключе office: это точка доступа, и чтобы событие отнеслось к офису, она должна быть привязана к нему в подписке.

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