Довідник API: архітектура, поля та коди статусів

Базові елементи, спільні для всіх операцій: схема запитів, спільні поля JSON, типи шаблонів, коди статусів, порти та шифрування payload.

Довідник API

Архітектура API

Параметр	Callback API	RESTful API
Ініціатор	Пристрій / Biometric Gateway	Ваш сервер
Напрямок	Пристрій → ваш сервер	Ваш сервер → пристрій
Затримка	У реальному часі (мілісекунди)	~15 секунд
Тригер	Біометрична подія на пристрої	HTTP POST із вашого коду
Ваша роль	Прийняти та підтвердити	Надіслати команду та очікувати відповідь
Тіло відповіді	`{"status":"done"}`	`{"Status":"done","OperationID":"…","StatusCode":0}`
Поведінка в офлайні	Кешується рушієм; доставляється, коли сервер знову онлайн	Ставиться рушієм у чергу; доставляється, коли пристрій перепідключиться

Довідник API

Спільні поля

Усі запити — і Callback, і RESTful — використовують такі спільні поля верхнього рівня.

AuthTokenРядок. 32-символьний токен, що ідентифікує та автентифікує запити від конкретного пристрою. Налаштовується на порталі API Monitor. Перевіряйте його під час кожного вхідного callback.

OperationIDРядок. Унікальний ідентифікатор екземпляра операції (наприклад, "j95xfejt3vr1"). У відповідях RESTful повертається той самий OperationID, що дає змогу зіставляти запити та відповіді.

TimeРядок. Мітка часу UTC обробки події у форматі YYYY-MM-DD HH:mm:ss GMT +0000. Мітки часу пристрою всередині payload можуть використовувати інший часовий пояс.

stgid (параметр запиту)Рядок. Service Tag ID — ідентифікує цільовий пристрій для викликів RESTful API. Передається як параметр запиту URL на endpoint, указаний у вашому обліковому записі API Monitor: POST https://<your-endpoint>?stgid=YOUR_TAG_ID.

Типи шаблонів

Біометричні дані та дані облікових даних передаються в масиві Template. Кожен елемент має поле Type:

Злиття шаблонів — важливо для обробників callback
Коли дані користувача передаються з пристрою (операції Callback №3–№9), шаблони можуть надходити по одному або групами в кількох callback. Кожен callback не містить повний набір шаблонів користувача — лише додані або змінені шаблони.

Ваш сервер має об'єднувати вхідні шаблони з уже збереженими шаблонами цього користувача. Унікальний ключ шаблону — Type + Index. Наприклад:
• Callback 1 надходить із Fingerprint Index 0 → збережіть його
• Callback 2 надходить із Face Index 0 + Card → об'єднайте, не перезаписуючи відбиток
• Callback 3 надходить із Fingerprint Index 0 (нові дані) → оновіть наявний відбиток з Index 0
Ніколи не замінюйте всі шаблони під час callback — завжди виконуйте upsert за Type + Index.

Тип	Опис	Основні додаткові поля
`Card`	Номер RFID-картки / картки безконтактного доступу	`Data` (рядок із номером картки)
`Password`	Цифровий PIN-код	`Data` (рядок із PIN-кодом)
`Fingerprint`	Шаблон відбитка пальця — двійкові дані в кодуванні Base64	`Index` (індекс пальця 0–9), `Size`, `Data`
`Face`	Шаблон обличчя — JPEG або двійкові дані в кодуванні Base64	`Index`, `Size`, `Data`
`Palm`	Шаблон вен долоні — двійкові дані в кодуванні Base64	`Index`, `Data`
`UserPhoto`	Фото профілю користувача — JPEG у кодуванні Base64	`Data`

Довідник API

Коди статусу відповіді

Відповіді RESTful API містять числовий StatusCode. Відповіді Callback API завжди мають просту форму {"status":"done"} незалежно від результату.

Код	Статус	Опис
`0`	Успішно	Операцію виконано успішно.
`1`	Недійсні дані запиту	Тіло JSON має неправильний формат або містить недійсні значення.
`2`	Недійсний Service Tag ID	Параметр запиту `stgid` не відповідає жодному зареєстрованому пристрою.
`3`	Недійсний запит	Структура запиту не відповідає очікуваному формату операції.
`4`	Недійсне шифрування	Не вдалося розшифрувати payload (AES-256). Перевірте ключ шифрування.
`5`	Пристрій офлайн	Цільовий пристрій наразі не підключений до Biometric Gateway.
`6`	Тайм-аут операції	Пристрій не підтвердив команду протягом відведеного часу.
`7`	Недійсний Auth Token	`AuthToken` у запиті не збігається з токеном, налаштованим для пристрою.
`8`	Користувач уже існує	Спробу операції Add виконано для UserID, який уже існує на пристрої.
`9`	Користувача не знайдено	Указаний UserID не існує на пристрої.
`10`	Помилка шаблону	Дані біометричного шаблону пошкоджені або мають непідтримуваний формат.
`11`	Пам'ять пристрою заповнена	Пристрій досяг максимальної місткості за користувачами або шаблонами.
`13`	Недійсний ключ безпеки	Ключ безпеки, указаний в API Monitor, не збігається.
`15`	Функція не підтримується	Запитувана операція не підтримується цією моделлю пристрою або режимом обміну даними.
`999`	Невідома помилка	Сталася непередбачена помилка. Зверніться до служби підтримки Cams, указавши OperationID.

Додаткова інформація

Підтримувані порти

Щоб отримувати дані про відвідуваність у реальному часі, ваш сервер має надавати HTTP(S) endpoint, доступний для Cams Protocol Engine.

Порт	Протокол	Призначення
`80`	HTTP	Робоче середовище. Прив'яжіть ваш callback URL до порту 80. Налаштовується в API Monitor і викликається автоматично під час відміток.
`443`	HTTPS	Робоче середовище (захищено). HTTPS із дійсним SSL-сертифікатом. Рекомендовано для робочого середовища.
`8123`	HTTP	Лише для тестування. Нестандартний порт, тимчасово доступний на час розробки.

Рекомендовано HTTPS. Використовуйте HTTPS із дійсним SSL-сертифікатом у робочому середовищі. Забезпечте автоматичне подовження без перезапуску сервера.

Додаткова інформація

Приклади даних

Приклади запитів і відповідей payload для всіх 38 операцій наведено вище в розділі кожної операції. Зведене подання:

Ця сторінкаУ кожному розділі операції вище є готові до копіювання JSON запиту та відповіді з прикладами даних.

Застаріла сторінка з прикладамиbiometric-web-api-sample-request-response.html — випадаючий список для вибору кожної операції.

Додаткова інформація

Шифрування

Для всіх даних, якими обмінюються Cams Protocol Engine і ваш сервер, можна ввімкнути додаткове шифрування AES-256.

АлгоритмAES-256 у режимі ECB із доповненням PKCS5 (AES/ECB/PKCS5PADDING).

Налаштування ключаВкажіть свій ключ як Security Key в API Monitor. Після налаштування всі чисті JSON-payload шифруються.

КодуванняЗашифровані payload кодуються в Base64 для безпечної передачі по HTTP.

Приклад на Java

Шифрування / розшифрування (Java)

// Encryption
Cipher cipher = Cipher.getInstance("AES/ECB/PKCS5PADDING");
SecretKeySpec keySpec = new SecretKeySpec(securityKey.getBytes("UTF-8"), "AES");
cipher.init(Cipher.ENCRYPT_MODE, keySpec);
String encrypted = Base64.getEncoder().encodeToString(cipher.doFinal(rawJson.getBytes("UTF-8")));

// Decryption
cipher.init(Cipher.DECRYPT_MODE, keySpec);
byte[] decoded = Base64.getDecoder().decode(encryptedPayload);
String decrypted = new String(cipher.doFinal(decoded), "UTF-8");

Важливо: якщо шифрування ввімкнено, розшифровуйте вхідні payload Callback і шифруйте тіла вихідних запитів RESTful за допомогою того самого ключа.