Создание приёмника биометрических 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 и понятные инструкции о том, что нужно создать. Вы вставляете его в ИИ-ассистент, и ассистент генерирует полную однофайловую реализацию для вашего стека.
|
Скачайте файл промпта Выберите язык в следующем разделе и скачайте его текстовый файл промпта (.txt). |
|
|
Вставьте его в ИИ-ассистент Откройте Claude, ChatGPT, Copilot или любой ИИ-инструмент для программирования и вставьте полное содержимое промпта. |
|
|
Получите готовый рабочий файл ИИ генерирует один файл. Укажите значения конфигурации, разверните файл и запустите его. |
| Каждый сгенерированный файл включает | Что он делает |
|---|---|
| Приёмник callback-запросов | Читает необработанное тело POST-запроса, проверяет AuthToken, направляет по типу события, записывает в журнал каждый callback, сохраняет отметки посещаемости, сохраняет фотографии посещаемости и отвечает «done» |
| REST-клиент | Общая функция запроса и функции-обёртки для всех 27 операций RESTful, таких как AddUser, DeleteUser, ResendAllUser и UpdateAccessTime |
| HTML-интерфейс для тестирования | Страница в браузере с полями конфигурации, выпадающим списком операций, редактором JSON с предзаполненными шаблонами запросов, просмотрщиком ответов и списком последних callback-запросов |
|
Сначала учитывается размещённая документация Каждый промпт указывает ИИ прочитать полную документацию Cams Web API и считать её авторитетным источником по операциям, схемам JSON, именам полей и кодам ответов. Если что-либо в кратком описании промпта противоречит размещённой документации, приоритет имеет документация. |
04 · Выберите язык
Промпты для Python, Node.js и 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, включая все промпты для генератора кода на базе ИИ: Получить промпты.