Справочник 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 с помощью одного и того же ключа.