Support Hub/API & Integrations/Создание приёмника биометрических callback-запросов на…
Translated from the English article and reviewed by a person. Read the English original
Developer

Создание приёмника биометрических callback-запросов на Python, Node.js и PHP

Создание приёмника биометрических callback-запросов на Python, Node.js и PHP

Приёмник callback-запросов — это небольшой фрагмент кода, который превращает каждое сканирование отпечатка пальца, лица или карты в запись в вашей собственной системе. Cams Biometrics Gateway отправляет каждое подтверждённое сканирование на ваш сервер в виде JSON-запроса, а сервер отвечает, подтверждая получение. Писать этот приёмник с нуля не нужно. Cams предоставляет промпты для генератора кода на базе ИИ для Python, Node.js и PHP: вставьте один из них в ИИ-ассистент, например Claude или ChatGPT, и вы получите готовый рабочий файл с приёмником callback-запросов, REST-клиентом и тестовым интерфейсом. В этом руководстве объясняется, что должен делать приёмник, как сгенерировать его для вашего языка, как его настроить и как протестировать перед запуском в эксплуатацию.

01 · Шесть задач

Что должен делать приёмник callback-запросов

Независимо от языка, любой биометрический приёмник callback-запросов выполняет одни и те же шесть задач. Именно их нужно проверять в любом сгенерированном коде.

Задача Что это означает Почему это важно
1. Принять запрос Получить HTTP/HTTPS POST-запрос с необработанным JSON в теле Так Gateway доставляет каждое событие
2. Проверить токен Сверить AuthToken с ожидаемым callback-токеном Не позволяет посторонним отправлять на ваш URL поддельные данные о посещаемости
3. Направить по типу события Определить, какой ключ находится внутри RealTime, и обработать событие соответствующим образом Не каждый callback — это отметка; некоторые передают фотографии или изменения данных пользователей
4. Пропускать дубликаты Использовать OperationID, чтобы игнорировать события, которые уже сохранены Повторная доставка никогда не создаёт двойную запись
5. Сохранить и вести журнал Сохранить нужные поля и записывать в журнал каждый callback Создаёт запись, которую будут использовать ваша HRMS, расчёт зарплаты или панель мониторинга
6. Ответить «done» Вернуть {“status”:”done”} с HTTP 200 Сообщает Gateway, что событие благополучно получено

02 · Знайте свои данные

Полезная нагрузка, которую вы будете получать

Самый распространённый callback — это журнал отметок, который отправляется при каждом сканировании. Сохраните этот пример как sample.json, так как позже он понадобится для тестирования приёмника.

Callback API, запрос PunchLog, отправляемый на ваш приёмник

{
  "RealTime": {
    "OperationID": "9nu1wak5616p",
    "LabelName": "Burj Khalifa",
    "SerialNumber": "ZHM11xxxxxxxx",
    "PunchLog": {
      "Type": "CheckOut",
      "Temperature": "36.8",
      "FaceMask": false,
      "InputType": "Fingerprint",
      "UserId": "2",
      "LogTime": "2020-09-17 07:48:22 GMT +0530"
    },
    "AuthToken": "COJJ7eiIPBGUfmIQPvh2PJWWDLX7OuKs",
    "Time": "2020-09-17 04:19:03 GMT +0000"
  }
}

После обработки любого callback ваш приёмник должен вернуть HTTP 200 и ровно такое тело ответа:

Callback API, ответ, который должен вернуть ваш приёмник

{ "status": "done" } (HTTP 200)

Типы событий callback

Каждый callback приходит внутри объекта RealTime. Ваш приёмник определяет, что делать, проверяя, какой из следующих ключей присутствует:

Ключ внутри RealTime Что он передаёт
PunchLog Отметка посещаемости: кто, приход или уход, когда и каким способом
UserUpdated Данные пользователя были обновлены на устройстве

Две детали, которые могут сбить разработчиков с толку

Деталь На что обратить внимание
Ключ ответа написан строчными буквами Возвращайте status строчными буквами со значением done. Не копируйте поле Status с заглавной буквы из ответов RESTful API
Формат LogTime LogTime выглядит так: 2020-09-17 07:48:22 GMT +0530. Это реальное время сканирования с учётом смещения часового пояса устройства. Разберите его с учётом смещения и используйте как время посещаемости

03 · Пусть ИИ напишет код

Сгенерируйте приёмник с помощью промптов для генератора кода на базе ИИ

Cams публикует готовый файл промпта для каждого поддерживаемого серверного языка. Каждый промпт содержит краткое описание спецификации Cams Web API 3.0 и понятные инструкции о том, что нужно создать. Вы вставляете его в ИИ-ассистент, и ассистент генерирует полную однофайловую реализацию для вашего стека.

1

Скачайте файл промпта

Выберите язык в следующем разделе и скачайте его текстовый файл промпта (.txt).

2

Вставьте его в ИИ-ассистент

Откройте Claude, ChatGPT, Copilot или любой ИИ-инструмент для программирования и вставьте полное содержимое промпта.

3

Получите готовый рабочий файл

ИИ генерирует один файл. Укажите значения конфигурации, разверните файл и запустите его.

Каждый сгенерированный файл включает Что он делает
Приёмник callback-запросов Читает необработанное тело POST-запроса, проверяет AuthToken, направляет по типу события, записывает в журнал каждый callback, сохраняет отметки посещаемости, сохраняет фотографии посещаемости и отвечает «done»
REST-клиент Общая функция запроса и функции-обёртки для всех 27 операций RESTful, таких как AddUser, DeleteUser, ResendAllUser и UpdateAccessTime
HTML-интерфейс для тестирования Страница в браузере с полями конфигурации, выпадающим списком операций, редактором JSON с предзаполненными шаблонами запросов, просмотрщиком ответов и списком последних callback-запросов

Сначала учитывается размещённая документация

Каждый промпт указывает ИИ прочитать полную документацию Cams Web API и считать её авторитетным источником по операциям, схемам JSON, именам полей и кодам ответов. Если что-либо в кратком описании промпта противоречит размещённой документации, приоритет имеет документация.

04 · Выберите язык

Промпты для Python, Node.js и PHP

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

Python

Flask, SQLite, только стандартная библиотека

Получить промпт для Python

Node.js

Express, хранилище в файле JSON

Получить промпт для Node.js

PHP

Чистый PHP, SQLite, без Composer

Скачать промпт для PHP

Промпты также доступны для C# (.NET 8) с Minimal API, Java со встроенным HttpServer без зависимостей, Go с net/http и только стандартной библиотекой, а также Ruby с Sinatra и SQLite. Все они находятся в разделе AI Code Generator Prompts документации Cams Web API. Получить промпты.

05 · Три значения для настройки

Настройка сгенерированного файла

Сгенерированный файл содержит блок конфигурации в начале. В версии для PHP он выглядит так, а в остальных языках используются те же три значения:

Блок конфигурации, версия для PHP

$CONFIG = [
    'base_url'            => 'https://YOUR_RESTFUL_ENDPOINT_URL',
    'stgid'               => 'YOUR_SERVICE_TAG_ID',
    'auth_token'          => 'YOUR_AUTH_TOKEN',
];
Параметр Что ввести
base_url URL конечной точки RESTful из вашей учётной записи Cams API Monitor
stgid Ваш Service Tag ID.
auth_token Ваш AuthToken, который включается в исходящие запросы RESTful и сверяется с AuthToken во входящих callback-запросах.

Не храните токены в общем коде

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

После настройки и развёртывания по публичному адресу HTTPS укажите этот адрес как Callback URL в Cams Gateway. С этого момента каждое подтверждённое сканирование будет поступать в ваш приёмник в режиме реального времени.

06 · Проверьте перед подключением устройств

Тестирование приёмника

Для тестирования приёмника callback-запросов биометрическое устройство не нужно. Отправьте ему тестовый пример самостоятельно с помощью cURL, используя совпадающий callback-токен, и проверьте ответ.

Терминал, отправка тестового callback-запроса

# Сохраните пример полезной нагрузки как sample.json, затем отправьте его на приёмник:
curl -X POST https://YOUR_SERVER/YOUR_CALLBACK_PATH \
  -H "Content-Type: application/json" \
  -d @sample.json

# Ожидаемый ответ (HTTP 200):
# {"status":"done"}
Тест Что отправить Ожидаемый результат
Корректное событие sample.json, в котором AuthToken равен вашему auth_token HTTP 200 с done, отметка сохранена
Повторное событие Тот же запрос второй раз HTTP 200 с done, вторая запись не сохраняется
Неверный токен sample.json с другим AuthToken Отклонено, ничего не сохраняется
Событие прихода sample.json, в котором Type изменён на CheckIn Сохранено как приход
Операция RESTful Используйте встроенный HTML-интерфейс для тестирования, чтобы отправить операцию Ответ с Status и StatusCode

Сгенерированный HTML-интерфейс для тестирования упрощает проверку части RESTful: откройте файл в браузере, выберите операцию в выпадающем списке, при необходимости измените предзаполненный JSON и отправьте его. Просмотрщик последних callback-запросов на той же странице подтверждает, что ваши тестовые callback-запросы получены.

07 · Контрольный список для эксплуатации

Проверка перед запуском в эксплуатацию

Код, сгенерированный ИИ, — быстрая и надёжная отправная точка, но, как и любой код, он должен быть проверен, прежде чем начнёт обрабатывать реальные данные сотрудников.

Пункт Готово, когда
Код проверен Разработчик прочитал сгенерированный файл и понимает назначение каждого раздела
Только HTTPS Приёмник доступен только по HTTPS с действующим сертификатом
Токены защищены AuthToken хранятся в переменных окружения или в менеджере секретов
Дубликаты обрабатываются OperationID сохраняется и проверяется, поэтому повторные доставки игнорируются
Хранилище подходит Хранилище в файлах JSON подходит для небольших систем; для крупных развёртываний может потребоваться переход на промышленную базу данных
Тестовый интерфейс защищён HTML-страница для тестирования защищена паролем или отключена на публичных серверах
Фотографии обрабатываются аккуратно Фотографии посещаемости, сохранённые на диск, защищены контролем доступа и хранятся только столько, сколько необходимо
Мониторинг настроен Ошибки и необычный объём callback-запросов записываются в журнал и отслеживаются вашей собственной системой мониторинга

Храните бизнес-правила отдельно

Задача приёмника — принимать, проверять, направлять, сохранять и подтверждать события. Определение опозданий, расчёт сверхурочной работы или отправка уведомлений относится к системам, которые читают сохранённые события, таким как ваша HRMS, ERP или средства автоматизации. Узко специализированный приёмник легче защищать и поддерживать.

Часто задаваемые вопросы

Нужно ли мне самому писать код?

Обычно нет. Промпты для генератора кода на базе ИИ создают полный рабочий файл. Вы задаёте три значения конфигурации, разворачиваете файл и тестируете его. Перед эксплуатацией код всё равно должен проверить разработчик.

С какими ИИ-ассистентами работают промпты?

С любым подходящим ИИ-ассистентом для программирования, включая Claude, ChatGPT и Copilot. Вставьте полное содержимое промпта целиком, чтобы у ассистента была полная спецификация.

Где найти URL конечной точки RESTful и Service Tag ID?

Оба значения берутся из вашей учётной записи Cams API Monitor. Запросы RESTful отправляются на URL конечной точки с параметром ?stgid=, после которого указывается ваш Service Tag ID.

Зачем отвечать done на повторное событие?

Потому что событие действительно благополучно получено, даже если вы уже сохранили его. Ответ done сообщает Gateway, что повторно отправлять событие не нужно.

Можно ли использовать язык, которого нет в списке?

Да. Приёмнику callback-запросов нужно только принимать HTTPS POST-запрос и возвращать JSON. Промпты — это быстрый путь, но тот же API работает с любым языком, который умеет это делать.

Заключение: от промпта до посещаемости в реальном времени за один день

Биометрический приёмник callback-запросов небольшой по объёму, но именно он превращает каждое подтверждённое сканирование в актуальные данные для вашей HRMS, расчёта зарплаты, панелей мониторинга и автоматизации. С промптами Cams для генератора кода на базе ИИ больше не нужно создавать его с чистого листа. Скачайте промпт для Python, Node.js или PHP, вставьте его в ИИ-ассистент, задайте три значения и протестируйте. Затем проверьте, защитите его и дайте начаться потоку данных о посещаемости в реальном времени.

Cams Biometrics Gateway передаёт события, которые нужны вашему приёмнику. Его Callback API отправляет каждое подтверждённое сканирование в режиме реального времени в едином формате JSON с устройств более чем 15 брендов, а его RESTful API предлагает 27 операций, которые может вызывать ваш сгенерированный клиент. Вся связь осуществляется через HTTP/HTTPS с проверкой auth-токена и опциональным шифрованием AES-256. Познакомьтесь с платформой на CamsBiometrics.com и прочитайте полную документацию Web API, включая все промпты для генератора кода на базе ИИ: Получить промпты.

 

Was this article helpful?