Support Hub/API & Integrations/Створення приймача biometric callback на Python, Node.js і PHP
Translated from the English article and reviewed by a person. Read the English original
Developer

Створення приймача biometric callback на Python, Node.js і PHP

Створення приймача 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-асистент, і асистент генерує повноцінну реалізацію в одному файлі для вашого стеку.

1

Завантажте файл промпту

Виберіть свою мову в наступному розділі та завантажте її текстовий файл промпту (.txt).

2

Вставте його в AI-асистент

Відкрийте 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 або інструментів автоматизації. Вузькоспрямований приймач легше захистити та підтримувати.

Часті запитання

Чи потрібно мені самому писати код?

Зазвичай ні. 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: Отримати промпти.

 

Was this article helpful?