Створення приймача biometric callback на Python, Node.js і PHP
Callback-приймач — це невеликий фрагмент коду, який перетворює кожне сканування відбитка пальця, обличчя чи картки на запис у вашій власній системі. Cams Biometrics Gateway надсилає кожне перевірене сканування на ваш сервер як запит JSON, а ваш сервер відповідає, підтверджуючи, що подію отримано. Не обов’язково писати цей приймач з нуля. Cams надає AI Code Generator Prompts для Python, Node.js і PHP: вставте один із них в AI-асистент, наприклад 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. Це реальний час скánування зі зсувом пристрою. Розберіть його з урахуванням зсуву і використовуйте як час відвідуваності |
03 · Нехай ШІ напише код
Згенеруйте свій приймач за допомогою AI Code Generator Prompts
Cams публікує готовий файл промпту для кожної підтримуваної серверної мови. Кожен промпт містить короткий опис специфікації Cams Web API 3.0 і чіткі інструкції щодо того, що створити. Ви вставляєте його в AI-асистент, і асистент генерує повноцінну реалізацію в одному файлі для вашого стеку.
|
Завантажте файл промпту Виберіть свою мову в наступному розділі та завантажте її текстовий файл промпту (.txt). |
|
|
Вставте його в AI-асистент Відкрийте 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 або інструментів автоматизації. Вузькоспрямований приймач легше захистити та підтримувати. |
Часті запитання
|
Чи потрібно мені самому писати код? Зазвичай ні. AI Code Generator Prompts створюють готовий робочий файл. Ви задаєте три значення конфігурації, розгортаєте файл і тестуєте його. Перед використанням у робочому середовищі код все одно має перевірити розробник. |
|
З якими AI-асистентами працюють промпти? Будь-який здатний AI-асистент для програмування, зокрема 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 AI Code Generator Prompts вам більше не потрібно будувати його з порожнього аркуша. Завантажте промпт для Python, Node.js або PHP, вставте його в AI-асистент, задайте три значення і протестуйте. Потім перевірте, захистіть його і дозвольте даним відвідуваності в реальному часі почати надходити.
Cams Biometrics Gateway доставляє події, які потрібні вашому приймачу. Його Callback API надсилає кожне перевірене сканування в реальному часі, в єдиному послідовному форматі JSON, з пристроїв понад 15 брендів, а його RESTful API пропонує 27 операцій, які може викликати згенерований вами клієнт. Уся комунікація відбувається через HTTP/HTTPS з перевіркою auth-токена та необов’язковим шифруванням AES-256. Ознайомтеся з платформою на CamsBiometrics.com і прочитайте повну документацію Web API, включно з усіма AI Code Generator Prompts: Отримати промпти.