FAQ, SDK et coût

Les questions fréquentes des intégrateurs, ainsi que le fonctionnement du SDK et de la tarification de l’API.

Informations complémentaires

Foire aux questions

Questions fréquentes sur l’intégration avec la Web API 3.0 de Cams Biometrics.

Généralités

Q : Qu’est-ce que la Cams Biometric Gateway et son API biométrique ?
La Cams Biometric Gateway est une plateforme cloud universelle qui expose une API biométrique permettant à toute application web de communiquer en temps réel avec des terminaux biométriques de pointage et de contrôle d’accès. Elle prend en charge 38 opérations réparties entre les API de callback (entrantes) et RESTful (sortantes) — sans nécessiter de SDK de terminal ni d’IP fixe.
Q : Ai-je besoin d’un SDK pour l’intégration ?
Non. Cams ne fournit ni n’exige de SDK. Toute la communication repose sur des requêtes HTTP/HTTPS POST standard avec des payloads JSON. Tout langage capable d’effectuer des appels HTTP convient.
Q : Quels langages de programmation sont pris en charge ?
Tout langage capable d’envoyer/recevoir des requêtes HTTP POST avec du JSON — PHP, Python, Java, C#, Node.js, Go, Ruby, etc. Nous fournissons des prompts de génération de code par IA pour 7 langages.
Q : Qu’est-ce que le Cams Protocol Engine ?
C’est le middleware cloud placé entre les terminaux biométriques et votre serveur. Il gère la traduction de protocoles, la normalisation des données, la mise en cache hors ligne et fournit une API JSON cohérente quelle que soit la marque ou le modèle du terminal.
Q : Qu’est-ce que l’API Monitor ?
L’API Monitor est votre portail d’administration où vous configurez les URL de callback, gérez les AuthTokens, définissez les Security Keys, consultez l’état des terminaux et accédez à l’URL de votre point de terminaison RESTful et à vos Service Tag IDs.

Compatibilité des terminaux

Q : Quels terminaux biométriques sont pris en charge ?
Tous les terminaux Cams Biometrics (listés sur camsbiometrics.com/product) prennent en charge l’API complète avec Native Push. Les appareils vérifiés sur developer.camsbiometrics.com bénéficient également de la prise en charge complète de Native Push.
Q : Les terminaux non-Cams (ZkTeco, eSSL, BioMax, etc.) peuvent-ils utiliser cette API ?
Oui, avec une mise à jour de protocole (Protocol Update). Les terminaux non-Cams et non vérifiés fonctionnent via Hybrid Push. Certaines fonctionnalités peuvent être limitées selon le mode de connexion et les capacités matérielles.
Q : Quelle est la différence entre Native Push et Hybrid Push ?
Native Push : prise en charge complète de l’API sans limitation — les 38 opérations fonctionnent. Disponible pour les terminaux Cams et les appareils vérifiés.
Hybrid Push : pour les terminaux non-Cams/non vérifiés. La disponibilité des fonctionnalités dépend du mode de communication (SDK, lecture de base de données ou traitement de fichier). Voir Modes de connexion.
Q : Quelles méthodes biométriques sont prises en charge ?
Empreinte digitale, reconnaissance faciale, veines de la paume, carte RFID/de proximité, code PIN/mot de passe numérique, lecture de l’iris et mesure de la température corporelle (selon le terminal).
Q : Certaines fonctionnalités de l’API ne marchent pas avec mon terminal. Pourquoi ?
Cela dépend (a) du mode de connexion — les modes lecture de base de données et traitement de fichier ne prennent en charge que l’envoi des présences, pas les API RESTful, et (b) des limites matérielles — certains modèles de terminaux peuvent ne pas prendre en charge des fonctions précises au niveau du firmware. Testez avec votre matériel et contactez l’assistance Cams pour obtenir de l’aide.

API de callback (Terminal → Serveur)

Q : Qu’est-ce que l’API de callback ?
L’API de callback envoie en temps réel les événements des terminaux biométriques à votre serveur. Lorsqu’un pointage a lieu ou qu’un utilisateur est modifié sur le terminal, le Cams Protocol Engine envoie immédiatement (POST) un payload JSON à votre URL de callback configurée.
Q : Que doit répondre mon serveur ?
Renvoyez toujours {"status":"done"} avec le statut HTTP 200 — même si votre traitement interne échoue. Ne bloquez jamais le Cams Protocol Engine. Mettez en file d’attente les traitements lourds pour une exécution asynchrone.
Q : Que se passe-t-il si mon serveur est hors ligne lors d’un pointage ?
La Biometric Gateway met en cache tous les événements et les livre automatiquement dès que votre serveur est de nouveau en ligne. Aucune donnée n’est perdue.
Q : Comment gérer les pointages en double ?
Implémentez une logique de détection des doublons sur votre serveur à partir de la combinaison UserID + LogTime. Un même pointage peut être renvoyé lors d’une reprise après une période hors ligne ou de nouvelles tentatives réseau.
Q : Quels types de pointage sont pris en charge ?
CheckIn, CheckOut, BreakOut, BreakIn, OverTimeIn, OverTimeOut, MealIn, MealOut. Le champ InputType indique la méthode biométrique utilisée : Fingerprint, Face, Palm, Card ou Password.
Q : Comment fonctionnent les modèles utilisateur dans les callbacks ?
Lorsqu’un utilisateur est mis à jour sur le terminal (opérations n°3–9), les modèles peuvent arriver un par un ou par groupes sur plusieurs callbacks. Chaque callback ne porte que les modèles modifiés — pas l’ensemble complet. Votre serveur doit fusionner/upserter avec Type + Index comme clé unique. N’écrasez jamais tous les modèles sur un seul callback.
Q : Puis-je recevoir des photos de présence ?
Oui. L’opération n°10 RealTimeAttendancePhoto fournit un instantané JPEG encodé en Base64, capturé au moment du pointage. Elle est distincte du callback du journal de pointage (n°11) et disponible sur les terminaux dotés d’une caméra.
Q : Le callback inclut-il la température et la détection de masque ?
Oui, si le terminal le prend en charge. L’objet PunchLog inclut Temperature (mesure de la température corporelle) et FaceMask (booléen — indique si un masque facial a été détecté).

API RESTful (Serveur → Terminal)

Q : Qu’est-ce que l’API RESTful ?
L’API RESTful permet à votre serveur d’envoyer des commandes aux terminaux biométriques — ajout/suppression d’utilisateurs, chargement de journaux, enrôlement biométrique et contrôle d’accès. Vous envoyez (POST) du JSON à l’URL du point de terminaison disponible dans votre compte API Monitor.
Q : Où trouver l’URL de mon point de terminaison RESTful ?
Connectez-vous à votre compte API Monitor. L’URL de votre point de terminaison RESTful et vos Service Tag IDs (stgid) y sont listés.
Q : Quelle est la latence des commandes RESTful ?
Environ 15 secondes. La Biometric Gateway met votre commande en file d’attente et la remet au terminal à sa prochaine connexion (quasi continue pour les terminaux en ligne).
Q : Quelle est la plage de dates maximale pour LoadLog ?
La limite recommandée est de 30 jours par requête. Pour des plages plus longues, effectuez plusieurs requêtes avec des fenêtres de temps consécutives.
Q : Puis-je ajouter un utilisateur avec plusieurs modèles biométriques à la fois ?
Oui. Le tableau Template accepte plusieurs entrées. Par exemple, l’opération n°27 ajoute un utilisateur avec Carte + Empreinte + Mot de passe + Visage + Paume + UserPhoto en une seule requête.
Q : Que se passe-t-il si le terminal est hors ligne quand j’envoie une commande RESTful ?
La Biometric Gateway met la commande en file d’attente et la livre automatiquement à la reconnexion du terminal. Vous recevrez le code de statut 5 (Terminal hors ligne) si le terminal ne répond pas dans le délai imparti.
Q : Comment vérifier le résultat d’une commande ?
Les réponses RESTful incluent un champ StatusCode. Le code 0 signifie succès. Consultez les codes de statut de réponse pour la liste complète des codes d’erreur et leur signification.
Q : Puis-je déclencher l’enrôlement d’une empreinte à distance ?
Oui. L’opération n°35 EnrollFingerPrint déclenche une session d’enrôlement sur le terminal. Toutefois, l’utilisateur doit être physiquement présent devant le terminal pour scanner son doigt.

Sécurité & réseau

Q : Puis-je utiliser HTTPS pour les callbacks ?
Oui. HTTPS avec un certificat SSL valide sur le port 443 est entièrement pris en charge et recommandé en production.
Q : Le chiffrement est-il obligatoire ?
Non. Le chiffrement AES-256 est optionnel. Pour l’activer, configurez une Security Key dans l’API Monitor. Une fois activé, tous les payloads JSON sont chiffrés/déchiffrés avec AES/ECB/PKCS5PADDING et encodés en Base64.
Q : Comment vérifier qu’un callback provient bien de Cams ?
Chaque callback inclut un champ AuthToken. Comparez-le au jeton configuré dans votre API Monitor. Rejetez toute requête dont le jeton ne correspond pas.
Q : Quels ports dois-je ouvrir ?
Le port 80 (HTTP) ou 443 (HTTPS) pour la production. Le port 8123 est disponible uniquement pour les tests. Voir Ports pris en charge.
Q : Comment tester en local sans déployer sur un serveur ?
Utilisez une IP publique avec redirection de port, ou un outil de tunneling comme ngrok. Consultez Tests en local pour un guide pas à pas.

Données & considérations de conception

Q : Quel format de données l’API utilise-t-elle ?
Toutes les requêtes et réponses sont du JSON brut en encodage UTF-8. Utilisez l’en-tête Content-Type: application/json. Pas d’encodage de formulaire.
Q : Quel format d’horodatage est utilisé ?
YYYY-MM-DD HH:mm:ss GMT +OFFSET (par ex. 2020-09-17 07:48:22 GMT +0530). Le champ Time est en UTC ; les horodatages locaux du terminal (comme LogTime, OperationTime) peuvent utiliser un autre décalage horaire.
Q : Comment gérer les pointages hors ligne et les données rétroactives ?
Concevez votre application pour accepter des pointages qui arrivent dans le désordre chronologique. Lorsqu’un terminal était hors ligne, il enverra les pointages mis en cache une fois reconnecté. Vous devrez peut-être mettre à jour rétroactivement le statut de présence (par ex. passer un utilisateur affiché comme « absent » à « présent »).
Q : Comment déterminer ENTRÉE/SORTIE lorsqu’un utilisateur a plusieurs terminaux ?
Triez tous les pointages d’un utilisateur par LogTime sur l’ensemble des terminaux, puis appliquez votre logique métier. Ne vous fiez pas uniquement au champ Type (CheckIn/CheckOut) d’un seul terminal si l’utilisateur pointe sur différentes machines.
Q : Qu’est-ce que l’OperationID et comment l’utiliser ?
Un identifiant unique de type chaîne pour chaque opération. Pour les callbacks entrants, il est généré par la Biometric Gateway. Pour les requêtes RESTful sortantes, vous devez en générer un unique par requête (UUID ou basé sur l’horodatage). La réponse le renvoie afin que vous puissiez associer les paires requête/réponse.
Q : Comment les modèles biométriques sont-ils stockés et transmis ?
Les données biométriques (empreinte digitale, visage, paume, photo utilisateur) sont encodées en Base64 dans le champ Data de l’objet Template. Les modèles d’empreinte et de visage incluent aussi Size (longueur en octets) et Index (numéro d’emplacement). Les numéros de carte et les codes PIN sont de simples chaînes.

Tarification & licences

Q : Comment l’API est-elle licenciée ?
Par terminal biométrique. La première année nécessite l’activation de l’API + une licence annuelle. Les années suivantes ne nécessitent que le renouvellement de la licence annuelle. Voir Coût de l’API pour les tarifs.
Q : Que se passe-t-il si ma licence d’API expire ?
La communication API de ce terminal s’arrête jusqu’au renouvellement de la licence. Vos données existantes ne sont pas affectées, mais plus aucun callback ni commande RESTful ne sera traité.
Q : Existe-t-il une option sur site ?
Oui. Le Protocol Engine Lite peut être installé sur votre propre serveur (Windows/Linux) pour les environnements LAN uniquement ou auto-hébergés. Contactez sales@camsbiometrics.com pour plus de détails.
Informations complémentaires

SDK de pointage biométrique

Cams ne fournit pas de SDK traditionnel. Toutes les opérations utilisent les API HTTP de callback et RESTful standard — aucune installation de bibliothèque n’est nécessaire.

Aucun SDK nécessaire. La communication passe entièrement par le Cams Protocol Engine, via des URL de callback et des points de terminaison HTTP RESTful.

L’intégration est ainsi simple avec n’importe quelle plateforme web :

OpenERPERPNextZoho PeopleSAPTallyHRAPPOdooApplications web sur mesure
Informations complémentaires

Coût de l’API

Les licences d’API sont facturées par terminal biométrique. Première année = activation + licence ; années suivantes = renouvellement de licence uniquement.

ServiceUSDRemarques
Native Push — Terminaux Cams & vérifiés
Activation de l’API$120Une seule fois par terminal.
Licence annuelle de l’API$60 – $120Renouvellement annuel requis.
Protocol Update (non-Cams)$120 – $280Une seule fois. Active le protocole Cams sur les terminaux non-Cams.
Hybrid Push — ZKTeco, eSSL & toutes les marques tierces
Activation de l’API$150Une seule fois par terminal.
Licence annuelle de l’API$90 – $150Renouvellement annuel requis.
Hybrid Connector (non vérifié)$150 – $300Une seule fois. Requis pour les terminaux non vérifiés utilisant Hybrid Push.
Matériel & autres
Matériel$220 – $720Varie selon le modèle.
Protocol Engine Lite (sur site) — Pour les environnements LAN uniquement ou auto-hébergés. Coût : $500–$10,000. Contactez les ventes pour plus de détails.