Запитання та відповіді, 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 мов ми надаємо промпти для генерації коду за допомогою AI.
Будь-яка мова, здатна надсилати й приймати HTTP POST із JSON — PHP, Python, Java, C#, Node.js, Go, Ruby та інші. Для 7 мов ми надаємо промпти для генерації коду за допомогою AI.
Питання: що таке 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. Подробиці — у відділі продажів.