Интеграции, REST API и вебхуки

1. Принцип

1.1. Всё, что видно в веб-интерфейсе n7kel Вахта, доступно внешним системам. Предусмотрены два способа обмена:

• REST API — внешняя система сама запрашивает данные или передаёт их платформе;
• вебхуки и оповещения — платформа сама сообщает о событиях: в вашу систему, на электронную почту, в Telegram.

1.2. Интеграция возможна практически с любой системой заказчика: если у системы есть API, база данных, файловая выгрузка или очередь сообщений, её можно подключить (раздел 10).

1.3. Машиночитаемое описание интерфейса и инструкции для разработчиков передаются ИТ-службе заказчика при подключении. В автономном варианте все интерфейсы работают внутри сети заказчика.

3. Ключи доступа и права

• каждой внешней системе выдаётся свой ключ с отдельным набором прав; ключ создаёт администратор организации;
• ключ показывается один раз; на сервере хранится только его отпечаток;
• ключ привязан к организации: данные других организаций для него не существуют;
• частота запросов ограничивается для каждого ключа отдельно;
• каждый запрос, включая отклонённые, записывается в журнал обращений;
• отзыв ключа действует немедленно; можно задать срок действия ключа.

5. Возможности REST API

• события с фильтрами по объекту, камере, посту, сотруднику, типу, уровню, периоду; периодический опрос только новых данных;
• карточка события с доказательной частью: результаты проверки подписи, цепочки и файлов; скачивание кадра и видеофрагмента при наличии права;
• нарушения с фильтрами по статусу, приоритету, ответственному, просрочке срока реакции, юридическому удержанию;
• аналитика и отчёты, в том числе «Касса» по кассам, кассирам и сменам;
• отчёты о проверке целостности;
• приём операций кассы.

Ответы и тексты ошибок — на русском языке. Таблицы CSV открываются в Excel без настройки, заголовки столбцов на русском. Текст, введённый людьми или переданный кассой, никогда не превращается в формулу при открытии выгрузки.

7. Доставка оповещений

• каждое сообщение подписано секретом канала — получатель проверяет, что оно отправлено вашей установкой и не изменено;
• фильтры канала: темы, минимальный уровень важности, объекты;
• каждое сообщение доставляется не менее одного раза; у каждого сообщения есть идентификатор для защиты от повторной обработки;
• неудачные доставки повторяются с растущей паузой; канал, который долго не принимает сообщения, отключается автоматически, причина видна администратору;
• журнал доставок позволяет сверить, не пропустил ли приёмник сообщения, и повторить доставку вручную;
• в сообщениях нет ссылок на изображения: кадры получают только по ключу с отдельным правом;
• если канал почты или Telegram не настроен, доставка помечается ошибкой — система не делает вид, что сообщение ушло.

Рекомендация в духе принципа «тишина важнее полноты»: людям — в почту и Telegram — отправлять только нарушения высокого приоритета, а полный поток событий — машинам через вебхуки.

8. Подключение кассовой системы

8.1. Модулю «Касса АЗС» нужны операции кассы. Подключение выполняется одним из двух способов:

• через API — кассовая система или промежуточный сервис передаёт операции пакетами до 500 штук; повторная передача той же операции не создаёт дубликатов;
• файлом CSV или XLSX — если кассовое ПО не умеет отправлять запросы. Платформа предлагает сопоставление колонок, проверку без сохранения, сама распознаёт кодировку, разделитель и русские названия операций.

8.2. Обязательные поля операции: идентификатор операции, номер кассы, вид операции, время. Желательные: логин кассира, номер чека, сумма, способ оплаты.

8.3. Часы касс часто расходятся с точным временем. Платформа сама оценивает поправку часов каждой кассы и учитывает её при сверке; поправку можно задать вручную. Синхронизация времени на кассах рекомендуется.

8.4. Платформа ждёт опоздавшие данные кассы: пока данных за проверяемый момент нет, нарушение «без чека» не открывается. Чек, пришедший после открытия нарушения, снимает его автоматически.

8.5. Принятые операции кассы защищены так же, как события блоков n7kel: изменить или удалить принятую операцию незаметно нельзя.

9. Интеграции n7kel Контроль АЗС

Платформа контроля и защиты от злоупотреблений для сети АЗС рассчитана на сеть из сотен станций:

• сверка чеков кассы и фискальных данных с зарегистрированными операциями: совпадение, чек без операции, дубликат, расхождение суммы с указанием разницы;
• дашборд в реальном времени и журнал кассовых операций;
• оповещения по e-mail, Telegram и SMS с проверяемым статусом доставки;
• отчёты в Excel и PDF;
• речевая аналитика через n7kel Voice — соблюдение скрипта обслуживания, запрещённые фразы, конфликты на русском, казахском и любых других языках; стоимость зависит от числа языков;
• телеметрия оборудования станций;
• кассовый киоск: вход кассира в смену по коду сотрудника и PIN-коду; вход по лицу — по решению заказчика и только с письменного согласия кассира;
• центр видит состояние связи каждой кассы; работа касс при длительной потере связи с центром обеспечивается нативным клиентом кассы и согласуется при обследовании.

Состав интеграций с конкретной кассовой системой и ERP определяется при обследовании.

10. Интеграция с любыми системами

10.1. Кроме типовых интеграций, n7kel подключает практически любые системы заказчика — в том числе собственные и унаследованные:

• API — REST, SOAP и другие протоколы;
• базы данных — чтение и запись по согласованной схеме, с отдельной учётной записью и минимальными правами;
• файловый обмен — CSV, XLSX, XML, JSON по расписанию или по событию;
• шины и очереди сообщений — для передачи потока событий в реальном времени;
• ERP и 1С, кассовые системы, СКУД, пульты охраны, системы видеонаблюдения других производителей;
• унаследованные системы — через промежуточный сервис, который разрабатывается в проекте.

10.2. Состав и способ интеграции определяются на обследовании и фиксируются в проекте. Все обмены идут внутри контура заказчика или по каналам, которые он согласовал; внешние сервисы n7kel для этого не нужны.

10.3. Все события продуктов n7kel могут сводиться в платформу n7kel Atlas — для поиска, связей и распределения задач.

11. Государственные базы

11.1. Если заказчику это требуется, продукты n7kel подключаются к базам розыска МВД, КНБ и других уполномоченных органов для проверки номеров автомобилей и лиц посетителей.

11.2. Подключение возможно только при наличии соглашения заказчика с соответствующими государственными органами и в порядке, установленном законом и этим соглашением. Способ обмена определяет орган; обмен выполняет сервер платформы в контуре заказчика, журнал проверок хранится на сервере заказчика.

11.3. При совпадении оповещение получает уполномоченный сотрудник службы безопасности заказчика и — согласно соглашению — орган. Каждая проверка и каждое совпадение записываются в журнал.