Вопросы и ответы, SDK и стоимость
Частые вопросы интеграторов, а также принципы работы SDK и тарификации API.
Дополнительная информация
Часто задаваемые вопросы
Частые вопросы об интеграции с Cams Biometrics Web API 3.0.
Общие вопросы
Вопрос: что такое Cams Biometric Gateway и его Biometric API?
Cams Biometric Gateway — универсальная облачная платформа, предоставляющая Biometric API, который позволяет любому веб-приложению в реальном времени обмениваться данными с биометрическими терминалами учёта посещаемости и контроля доступа. Платформа поддерживает 38 операций в Callback API (входящие) и RESTful API (исходящие) — без SDK устройства и без статического IP.
Cams Biometric Gateway — универсальная облачная платформа, предоставляющая Biometric API, который позволяет любому веб-приложению в реальном времени обмениваться данными с биометрическими терминалами учёта посещаемости и контроля доступа. Платформа поддерживает 38 операций в Callback API (входящие) и RESTful API (исходящие) — без SDK устройства и без статического IP.
Вопрос: нужен ли SDK для интеграции?
Нет. Cams не предоставляет SDK и не требует его. Весь обмен данными идёт через стандартные HTTP/HTTPS POST-запросы с JSON payload. Подойдёт любой язык, который умеет выполнять HTTP-вызовы.
Нет. Cams не предоставляет SDK и не требует его. Весь обмен данными идёт через стандартные HTTP/HTTPS POST-запросы с JSON payload. Подойдёт любой язык, который умеет выполнять HTTP-вызовы.
Вопрос: какие языки программирования поддерживаются?
Любой язык, способный отправлять и принимать HTTP POST с JSON — PHP, Python, Java, C#, Node.js, Go, Ruby и другие. Для 7 языков мы предоставляем промпты для генерации кода с помощью ИИ.
Любой язык, способный отправлять и принимать HTTP POST с JSON — PHP, Python, Java, C#, Node.js, Go, Ruby и другие. Для 7 языков мы предоставляем промпты для генерации кода с помощью ИИ.
Вопрос: что такое Cams Protocol Engine?
Это облачное промежуточное ПО между биометрическими устройствами и вашим сервером. Оно выполняет преобразование протоколов, нормализацию данных, офлайн-кэширование и предоставляет единый JSON API независимо от бренда и модели устройства.
Это облачное промежуточное ПО между биометрическими устройствами и вашим сервером. Оно выполняет преобразование протоколов, нормализацию данных, офлайн-кэширование и предоставляет единый JSON API независимо от бренда и модели устройства.
Вопрос: что такое API Monitor?
API Monitor — ваш административный портал, где вы настраиваете Callback URL, управляете AuthToken, задаёте Security Key, просматриваете статус устройств и получаете URL вашего RESTful endpoint и Service Tag ID.
API Monitor — ваш административный портал, где вы настраиваете Callback URL, управляете AuthToken, задаёте Security Key, просматриваете статус устройств и получаете URL вашего RESTful endpoint и Service Tag ID.
Совместимость устройств
Вопрос: какие биометрические устройства поддерживаются?
Все терминалы Cams Biometrics (список на camsbiometrics.com/product) поддерживают полный API через Native Push. Устройства, проверенные на developer.camsbiometrics.com, также полностью поддерживают Native Push.
Все терминалы Cams Biometrics (список на camsbiometrics.com/product) поддерживают полный API через Native Push. Устройства, проверенные на developer.camsbiometrics.com, также полностью поддерживают Native Push.
Вопрос: могут ли устройства не от Cams (ZkTeco, eSSL, BioMax и др.) использовать этот API?
Да, при условии Protocol Update. Устройства не от Cams и не проверенные работают через Hybrid Push. Некоторые функции могут быть ограничены в зависимости от режима подключения и возможностей оборудования.
Да, при условии Protocol Update. Устройства не от Cams и не проверенные работают через Hybrid Push. Некоторые функции могут быть ограничены в зависимости от режима подключения и возможностей оборудования.
Вопрос: в чём разница между Native Push и Hybrid Push?
Native Push: полная поддержка API без ограничений — работают все 38 операций. Доступно для терминалов Cams и проверенных устройств.
Hybrid Push: для устройств не от Cams и не проверенных. Доступность функций зависит от способа обмена данными (SDK, чтение из БД или обработка файла). См. Режимы подключения.
Native Push: полная поддержка API без ограничений — работают все 38 операций. Доступно для терминалов Cams и проверенных устройств.
Hybrid Push: для устройств не от Cams и не проверенных. Доступность функций зависит от способа обмена данными (SDK, чтение из БД или обработка файла). См. Режимы подключения.
Вопрос: какие биометрические методы поддерживаются?
Отпечаток пальца, распознавание лиц, вены ладони, RFID/бесконтактная карта, цифровой PIN-код/пароль, сканирование радужной оболочки и измерение температуры тела (в зависимости от устройства).
Отпечаток пальца, распознавание лиц, вены ладони, RFID/бесконтактная карта, цифровой PIN-код/пароль, сканирование радужной оболочки и измерение температуры тела (в зависимости от устройства).
Вопрос: некоторые функции API не работают с моим устройством. Почему?
Это зависит от (a) режима подключения — режимы чтения из БД и обработки файла поддерживают только отправку посещаемости, но не RESTful API, и (b) ограничений оборудования — некоторые модели устройств могут не поддерживать отдельные функции на уровне прошивки. Протестируйте на своём оборудовании и обратитесь за помощью в поддержку Cams.
Это зависит от (a) режима подключения — режимы чтения из БД и обработки файла поддерживают только отправку посещаемости, но не RESTful API, и (b) ограничений оборудования — некоторые модели устройств могут не поддерживать отдельные функции на уровне прошивки. Протестируйте на своём оборудовании и обратитесь за помощью в поддержку Cams.
Callback API (устройство → сервер)
Вопрос: что такое Callback API?
Callback API доставляет события биометрических устройств на ваш сервер в реальном времени. Когда происходит отметка или пользователь изменяется на устройстве, Cams Protocol Engine немедленно отправляет JSON payload методом POST на ваш настроенный Callback URL.
Callback API доставляет события биометрических устройств на ваш сервер в реальном времени. Когда происходит отметка или пользователь изменяется на устройстве, Cams Protocol Engine немедленно отправляет JSON payload методом POST на ваш настроенный Callback URL.
Вопрос: что должен ответить мой сервер?
Всегда возвращайте
Всегда возвращайте
{"status":"done"} с HTTP-статусом 200 — даже если внутренняя обработка завершилась ошибкой. Никогда не блокируйте Cams Protocol Engine. Ставьте ресурсоёмкую обработку в очередь для асинхронного выполнения.Вопрос: что произойдёт, если мой сервер не в сети в момент отметки?
Biometric Gateway кэширует все события и автоматически доставляет их, как только ваш сервер снова будет в сети. Данные не теряются.
Biometric Gateway кэширует все события и автоматически доставляет их, как только ваш сервер снова будет в сети. Данные не теряются.
Вопрос: как обрабатывать дублирующиеся отметки?
Реализуйте на сервере логику обнаружения дубликатов по сочетанию
Реализуйте на сервере логику обнаружения дубликатов по сочетанию
UserID + LogTime. Одна и та же отметка может быть отправлена повторно при восстановлении после офлайна или повторных попытках из-за сбоев сети.Вопрос: какие типы отметок поддерживаются?
CheckIn, CheckOut, BreakOut, BreakIn, OverTimeIn, OverTimeOut, MealIn, MealOut. Поле InputType показывает использованный биометрический метод: Fingerprint, Face, Palm, Card или Password.Вопрос: как работают шаблоны пользователей в Callback?
Когда пользователь обновляется на устройстве (операции №3–№9), шаблоны могут приходить по одному или группами в нескольких callback. Каждый callback содержит только изменившиеся шаблоны — не полный набор. Ваш сервер должен объединять/выполнять upsert по
Когда пользователь обновляется на устройстве (операции №3–№9), шаблоны могут приходить по одному или группами в нескольких callback. Каждый callback содержит только изменившиеся шаблоны — не полный набор. Ваш сервер должен объединять/выполнять upsert по
Type + Index как уникальному ключу. Никогда не перезаписывайте все шаблоны одним callback.Вопрос: можно ли получать фото посещаемости?
Да. Операция №10 RealTimeAttendancePhoto доставляет снимок в формате JPEG в кодировке Base64, сделанный в момент отметки. Она отделена от callback журнала отметок (№11) и доступна на устройствах с камерой.
Да. Операция №10 RealTimeAttendancePhoto доставляет снимок в формате JPEG в кодировке Base64, сделанный в момент отметки. Она отделена от callback журнала отметок (№11) и доступна на устройствах с камерой.
Вопрос: включает ли Callback температуру и определение маски?
Да, если устройство это поддерживает. Объект
Да, если устройство это поддерживает. Объект
PunchLog содержит Temperature (показание температуры тела) и FaceMask (булево значение — обнаружена ли маска на лице).RESTful API (сервер → устройство)
Вопрос: что такое RESTful API?
RESTful API позволяет вашему серверу отправлять команды биометрическим устройствам — добавлять и удалять пользователей, загружать журналы, регистрировать биометрию и управлять доступом. Вы отправляете JSON методом POST на URL endpoint из вашей учётной записи API Monitor.
RESTful API позволяет вашему серверу отправлять команды биометрическим устройствам — добавлять и удалять пользователей, загружать журналы, регистрировать биометрию и управлять доступом. Вы отправляете JSON методом POST на URL endpoint из вашей учётной записи API Monitor.
Вопрос: где найти URL моего RESTful endpoint?
Войдите в учётную запись API Monitor. URL вашего RESTful endpoint и Service Tag ID (
Войдите в учётную запись API Monitor. URL вашего RESTful endpoint и Service Tag ID (
stgid) указаны там.Вопрос: какая задержка у RESTful-команд?
Примерно 15 секунд. Biometric Gateway ставит команду в очередь и передаёт её устройству при следующем подключении (для устройств в сети оно почти непрерывное).
Примерно 15 секунд. Biometric Gateway ставит команду в очередь и передаёт её устройству при следующем подключении (для устройств в сети оно почти непрерывное).
Вопрос: каков максимальный интервал дат для LoadLog?
Рекомендуемый максимум — 30 дней на запрос. Для более длинных периодов выполняйте несколько запросов с последовательными временными окнами.
Рекомендуемый максимум — 30 дней на запрос. Для более длинных периодов выполняйте несколько запросов с последовательными временными окнами.
Вопрос: можно ли добавить пользователя сразу с несколькими биометрическими шаблонами?
Да. Массив Template принимает несколько записей. Например, операция №27 добавляет пользователя с картой + отпечатком пальца + паролем + лицом + ладонью + фото пользователя одним запросом.
Да. Массив Template принимает несколько записей. Например, операция №27 добавляет пользователя с картой + отпечатком пальца + паролем + лицом + ладонью + фото пользователя одним запросом.
Вопрос: что произойдёт, если устройство не в сети, когда я отправляю RESTful-команду?
Biometric Gateway ставит команду в очередь и автоматически доставляет её при повторном подключении устройства. Вы получите код статуса
Biometric Gateway ставит команду в очередь и автоматически доставляет её при повторном подключении устройства. Вы получите код статуса
5 (устройство не в сети), если устройство не ответит в течение тайм-аута.Вопрос: как проверить результат команды?
Ответы RESTful содержат поле
Ответы RESTful содержат поле
StatusCode. Код 0 означает успех. Полный список кодов ошибок и их значений см. в разделе Коды статусов ответа.Вопрос: можно ли запустить регистрацию отпечатка пальца удалённо?
Да. Операция №35 EnrollFingerPrint запускает сеанс регистрации на устройстве. Однако пользователь должен находиться непосредственно у устройства, чтобы отсканировать палец.
Да. Операция №35 EnrollFingerPrint запускает сеанс регистрации на устройстве. Однако пользователь должен находиться непосредственно у устройства, чтобы отсканировать палец.
Безопасность и сеть
Вопрос: можно ли использовать HTTPS для callback?
Да. HTTPS с действительным SSL-сертификатом на порту 443 полностью поддерживается и рекомендуется для рабочей среды.
Да. HTTPS с действительным SSL-сертификатом на порту 443 полностью поддерживается и рекомендуется для рабочей среды.
Вопрос: обязательно ли шифрование?
Нет. Шифрование AES-256 необязательно. Чтобы включить его, задайте Security Key в API Monitor. После включения все JSON payload шифруются и расшифровываются с помощью AES/ECB/PKCS5PADDING с кодировкой Base64.
Нет. Шифрование AES-256 необязательно. Чтобы включить его, задайте Security Key в API Monitor. После включения все JSON payload шифруются и расшифровываются с помощью AES/ECB/PKCS5PADDING с кодировкой Base64.
Вопрос: как убедиться, что callback действительно пришёл от Cams?
Каждый callback содержит поле
Каждый callback содержит поле
AuthToken. Сравните его с токеном, настроенным в вашем API Monitor. Отклоняйте любой запрос с несовпадающим токеном.Вопрос: какие порты нужно открыть?
Порт
Порт
80 (HTTP) или 443 (HTTPS) для рабочей среды. Порт 8123 доступен только для тестирования. См. Поддерживаемые порты.Вопрос: как тестировать локально без развёртывания на сервере?
Используйте публичный IP с пробросом портов или инструмент туннелирования, например ngrok. Пошаговое руководство — в разделе Локальное тестирование.
Используйте публичный IP с пробросом портов или инструмент туннелирования, например ngrok. Пошаговое руководство — в разделе Локальное тестирование.
Данные и вопросы проектирования
Вопрос: какой формат данных использует API?
Все запросы и ответы — чистый JSON в кодировке UTF-8. Используйте заголовок
Все запросы и ответы — чистый JSON в кодировке UTF-8. Используйте заголовок
Content-Type: application/json. Кодирование форм не применяется.Вопрос: какой формат меток времени используется?
YYYY-MM-DD HH:mm:ss GMT +OFFSET (например, 2020-09-17 07:48:22 GMT +0530). Поле Time указано в UTC; метки времени устройства (например, LogTime, OperationTime) могут использовать другой часовой пояс.Вопрос: как обрабатывать офлайн-отметки и данные, поступающие задним числом?
Проектируйте приложение так, чтобы оно принимало отметки, приходящие не в хронологическом порядке. Если устройство было офлайн, после переподключения оно отправит накопленные в кэше отметки. Возможно, потребуется задним числом обновить статус посещаемости (например, изменить статус пользователя с «отсутствует» на «присутствует»).
Проектируйте приложение так, чтобы оно принимало отметки, приходящие не в хронологическом порядке. Если устройство было офлайн, после переподключения оно отправит накопленные в кэше отметки. Возможно, потребуется задним числом обновить статус посещаемости (например, изменить статус пользователя с «отсутствует» на «присутствует»).
Вопрос: как определить вход/выход, если у пользователя несколько устройств?
Отсортируйте все отметки пользователя по
Отсортируйте все отметки пользователя по
LogTime со всех устройств, затем примените свою бизнес-логику. Не полагайтесь только на поле Type (CheckIn/CheckOut) с одного устройства, если пользователь отмечается на разных терминалах.Вопрос: что такое OperationID и как его использовать?
Уникальный строковый идентификатор каждой операции. Для входящих callback его генерирует Biometric Gateway. Для исходящих RESTful-запросов вы должны генерировать уникальный идентификатор для каждого запроса (UUID или на основе метки времени). Ответ возвращает его обратно, чтобы вы могли сопоставлять пары запрос/ответ.
Уникальный строковый идентификатор каждой операции. Для входящих callback его генерирует Biometric Gateway. Для исходящих RESTful-запросов вы должны генерировать уникальный идентификатор для каждого запроса (UUID или на основе метки времени). Ответ возвращает его обратно, чтобы вы могли сопоставлять пары запрос/ответ.
Вопрос: как хранятся и передаются биометрические шаблоны?
Биометрические данные (отпечаток пальца, лицо, ладонь, фото пользователя) кодируются в Base64 в поле
Биометрические данные (отпечаток пальца, лицо, ладонь, фото пользователя) кодируются в Base64 в поле
Data объекта Template. Шаблоны отпечатков пальцев и лиц также содержат Size (длина в байтах) и Index (номер слота). Номера карт и PIN-коды — обычные строки.Цены и лицензирование
Вопрос: как лицензируется API?
На каждый биометрический терминал. В первый год требуются активация API + годовая лицензия. В последующие годы — только продление годовой лицензии. Цены см. в разделе Стоимость API.
На каждый биометрический терминал. В первый год требуются активация API + годовая лицензия. В последующие годы — только продление годовой лицензии. Цены см. в разделе Стоимость API.
Вопрос: что произойдёт, если срок действия лицензии API истечёт?
Обмен данными по API для этого устройства прекращается до продления лицензии. Ваши существующие данные не затрагиваются, но новые callback и RESTful-команды обрабатываться не будут.
Обмен данными по API для этого устройства прекращается до продления лицензии. Ваши существующие данные не затрагиваются, но новые callback и RESTful-команды обрабатываться не будут.
Вопрос: есть ли вариант on-premise?
Да. Protocol Engine Lite можно установить на собственный сервер (Windows/Linux) для сред только с LAN или для самостоятельного размещения. Подробности — по адресу sales@camsbiometrics.com.
Да. Protocol Engine Lite можно установить на собственный сервер (Windows/Linux) для сред только с LAN или для самостоятельного размещения. Подробности — по адресу sales@camsbiometrics.com.
Дополнительная информация
SDK для биометрического учёта посещаемости
Cams не предоставляет традиционный SDK. Все операции используют стандартные HTTP Callback API и RESTful API — установка библиотек не требуется.
SDK не нужен. Обмен данными полностью осуществляется через Cams Protocol Engine с использованием Callback URL и RESTful HTTP endpoint.
Благодаря этому интеграция проста с любой веб-платформой:
OpenERPERPNextZoho PeopleSAPTallyHRAPPOdooСобственные веб-приложения
Дополнительная информация
Стоимость API
Лицензии API оплачиваются за каждый биометрический терминал. Первый год = активация + лицензия; последующие годы = только продление лицензии.
| Услуга | USD | Примечания |
|---|---|---|
| Native Push — устройства Cams и проверенные устройства | ||
| Активация API | $120 | Единовременно на каждый терминал. |
| Годовая лицензия API | $60 – $120 | Требуется ежегодное продление. |
| Protocol Update (не Cams) | $120 – $280 | Единовременно. Включает протокол Cams на устройствах не от Cams. |
| Hybrid Push — ZKTeco, eSSL и все сторонние бренды | ||
| Активация API | $150 | Единовременно на каждый терминал. |
| Годовая лицензия API | $90 – $150 | Требуется ежегодное продление. |
| Hybrid Connector (не проверенные) | $150 – $300 | Единовременно. Требуется для непроверенных устройств, использующих Hybrid Push. |
| Оборудование и прочее | ||
| Оборудование | $220 – $720 | Зависит от модели. |
Protocol Engine Lite (on-premise) — для сред только с LAN или самостоятельного размещения. Стоимость: $500–$10,000. Подробности — в отделе продаж.