Référence de l’API : architecture, champs et codes de statut

Les éléments communs à toutes les opérations : flux des requêtes, champs JSON communs, types de modèles, codes de statut, ports et chiffrement des payloads.

Réponses rapides

Quels sont les deux flux d’API ?

L’API de callback envoie les événements du terminal (via la Cams Biometric Gateway) vers votre serveur en temps réel. L’API RESTful permet à votre serveur d’envoyer des commandes à un terminal, et la réponse arrive en 15 secondes environ. Si votre serveur est hors ligne, le moteur met les callbacks en cache ; les commandes REST sont mises en file d’attente jusqu’à la reconnexion du terminal.

Quels codes de statut l’API RESTful renvoie-t-elle ?

Un StatusCode numérique : 0 succès, 1 données de requête invalides, 2 Service Tag ID invalide, 3 requête invalide, 4 chiffrement invalide, 5 terminal hors ligne, 6 délai d’opération dépassé, 7 jeton d’authentification invalide, 8 utilisateur déjà existant, 9 utilisateur introuvable, 10 erreur de modèle, 11 mémoire du terminal pleine, 13 clé de sécurité invalide, 15 fonctionnalité non prise en charge, 999 erreur inconnue. Les réponses aux callbacks utilisent toujours {"status":"done"}.

Que signifie le code de statut 5 (terminal hors ligne) ?

Le terminal cible n’est actuellement pas connecté à la Biometric Gateway. Voir le code de statut 5.

Comment authentifier les requêtes ?

Chaque requête porte un AuthToken, un jeton de 32 caractères qui identifie un terminal et qui est défini dans le portail API Monitor. Validez-le à chaque callback entrant. Les appels REST indiquent aussi le terminal via le paramètre de requête stgid (Service Tag ID). Voir Champs communs.

De quels ports mon serveur a-t-il besoin ?

Port 80 (HTTP) ou 443 (HTTPS) en production ; HTTPS avec un certificat valide est recommandé. Le port 8123 (HTTP) est réservé aux tests. Voir Ports pris en charge.

Comment le payload est-il chiffré ?

Le chiffrement est facultatif. Lorsqu’il est activé, les payloads utilisent AES-256 en mode ECB avec bourrage PKCS5 (AES/ECB/PKCS5PADDING), avec la clé de sécurité définie dans API Monitor, et sont encodés en Base64 pour le transport HTTP. Déchiffrez les callbacks entrants et chiffrez les corps REST sortants avec la même clé. Voir Chiffrement.

Comment gérer les modèles qui arrivent en plusieurs callbacks ?

Fusionnez-les. Chaque callback ne contient que les modèles ajoutés ou modifiés. La clé unique d’un modèle est Type + Index ; faites donc un upsert sur cette paire et ne remplacez jamais l’ensemble des modèles d’un utilisateur. Voir Types de modèles.

Quels types de modèles existent ?

Card, Password, Fingerprint, Face, Palm et UserPhoto. Les modèles Fingerprint, Face et Palm sont encodés en Base64, et l’index d’empreinte va de 0–9.

Architecture de l’API

PropriétéAPI de callbackAPI RESTful
InitiateurTerminal / Biometric GatewayVotre serveur
SensTerminal → Votre serveurVotre serveur → Terminal
LatenceTemps réel (millisecondes)~15 secondes
DéclencheurÉvénement biométrique sur le terminalHTTP POST depuis votre code
Votre rôleRecevoir & acquitterEnvoyer la commande & interroger/attendre la réponse
Corps de la réponse{"status":"done"}{"Status":"done","OperationID":"…","StatusCode":0}
Comportement hors ligneMis en cache par le moteur ; livré dès que le serveur est de nouveau en ligneMis en file d’attente par le moteur ; livré à la reconnexion du terminal

Champs communs

Toutes les requêtes — callback comme RESTful — partagent ces champs de premier niveau.

AuthTokenString. Jeton de 32 caractères qui identifie et authentifie les requêtes d’un terminal donné. Configuré dans le portail API Monitor. Validez-le à chaque callback entrant.
OperationIDString. Identifiant unique de cette instance d’opération (par ex. "j95xfejt3vr1"). Les réponses RESTful renvoient le même OperationID afin que vous puissiez associer requêtes et réponses.
TimeString. Horodatage UTC du traitement de l’événement, au format YYYY-MM-DD HH:mm:ss GMT +0000. Les horodatages locaux du terminal dans le payload peuvent utiliser un autre décalage horaire.
stgid (paramètre de requête)String. Service Tag ID — identifie le terminal cible pour les appels d’API RESTful. À transmettre comme paramètre de requête d’URL au point de terminaison disponible dans votre compte API Monitor : POST https://<your-endpoint>?stgid=YOUR_TAG_ID.

Types de modèles

Les données biométriques et d’identification sont transportées dans un tableau Template. Chaque élément comporte un champ Type :

Comportement de fusion des modèles — important pour les gestionnaires de callback
Lorsque les données utilisateur sont envoyées par le terminal (opérations de callback n°3 à 9), les modèles peuvent arriver un par un ou par groupes, sur plusieurs callbacks. Chaque callback ne contient pas l’ensemble complet des modèles de l’utilisateur — il ne porte que les modèles ajoutés ou modifiés.

Votre serveur doit fusionner les modèles reçus avec ceux déjà stockés pour cet utilisateur. La clé unique de chaque modèle est Type + Index. Par exemple :
• Le callback 1 arrive avec Fingerprint Index 0 → stockez-le
• Le callback 2 arrive avec Face Index 0 + Card → fusionnez, n’écrasez pas l’empreinte
• Le callback 3 arrive avec Fingerprint Index 0 (nouvelles données) → mettez à jour l’empreinte existante à l’Index 0
Ne remplacez jamais tous les modèles lors d’un callback — faites toujours un upsert par Type + Index.
TypeDescriptionChamps supplémentaires clés
CardNuméro de carte RFID / de proximitéData (chaîne du numéro de carte)
PasswordCode PIN numériqueData (chaîne du code PIN)
FingerprintModèle d’empreinte digitale — binaire encodé en Base64Index (index du doigt 0–9), Size, Data
FaceModèle de visage — JPEG ou binaire encodé en Base64Index, Size, Data
PalmModèle des veines de la paume — binaire encodé en Base64Index, Data
UserPhotoPhoto de profil de l’utilisateur — JPEG encodé en Base64Data

Codes de statut de réponse

Les réponses de l’API RESTful incluent un StatusCode numérique. Les réponses de l’API de callback utilisent toujours la forme simple {"status":"done"}, quel que soit le résultat.

CodeStatutDescription
0SuccèsOpération terminée avec succès.
1Données de requête invalidesLe corps JSON est mal formé ou contient des valeurs invalides.
2Service Tag ID invalideLe paramètre de requête stgid ne correspond à aucun terminal enregistré.
3Requête invalideLa structure de la requête ne correspond pas au format d’opération attendu.
4Chiffrement invalideLe payload chiffré (AES-256) n’a pas pu être déchiffré. Vérifiez votre clé de chiffrement.
5Terminal hors ligneLe terminal cible n’est actuellement pas connecté à la Biometric Gateway.
6Délai d’opération dépasséLe terminal n’a pas acquitté la commande dans le délai imparti.
7Jeton d’authentification invalideL’AuthToken de la requête ne correspond pas au jeton configuré pour le terminal.
8Utilisateur déjà existantUne opération d’ajout a été tentée pour un UserID qui existe déjà sur le terminal.
9Utilisateur introuvableL’UserID spécifié n’existe pas sur le terminal.
10Erreur de modèleLes données du modèle biométrique sont corrompues ou dans un format non pris en charge.
11Mémoire du terminal pleineLe terminal a atteint sa capacité maximale d’utilisateurs ou de modèles.
13Clé de sécurité invalideLa clé de sécurité configurée dans l’API Monitor ne correspond pas.
15Fonctionnalité non prise en chargeL’opération demandée n’est pas prise en charge par ce modèle de terminal ou ce mode de communication.
999Erreur inconnueUne erreur inattendue s’est produite. Contactez l’assistance Cams en indiquant l’OperationID.

Ports pris en charge

Pour recevoir les informations de présence en temps réel, votre serveur doit exposer un point de terminaison HTTP(S) accessible par le Cams Protocol Engine.

PortProtocoleUsage
80HTTPProduction. Associez votre URL de callback au port 80. Configuré dans l’API Monitor et appelé automatiquement à chaque pointage.
443HTTPSProduction (sécurisé). HTTPS avec un certificat SSL valide. Recommandé pour la production.
8123HTTPTests uniquement. Port non standard disponible temporairement pendant le développement.
HTTPS recommandé. Utilisez HTTPS avec un certificat SSL valide en production. Assurez un renouvellement automatique sans redémarrage du serveur.

Exemples de données

Des exemples de payloads de requête et de réponse pour les 38 opérations sont documentés ci-dessus dans chaque section d’opération. Pour une vue consolidée :

Cette pageChaque section d’opération ci-dessus inclut des JSON de requête et de réponse prêts à copier, avec des données d’exemple.
Ancienne page d’exemplesbiometric-web-api-sample-request-response.html — sélecteur déroulant pour chaque opération.

Chiffrement

Un chiffrement AES-256 optionnel peut être activé pour toutes les données échangées entre le Cams Protocol Engine et votre serveur.

AlgorithmeAES-256 en mode ECB avec remplissage PKCS5 (AES/ECB/PKCS5PADDING).
Configuration de la cléDéfinissez votre clé comme Security Key dans l’API Monitor. Une fois configurée, tous les payloads JSON bruts sont chiffrés.
EncodageLes payloads chiffrés sont encodés en Base64 pour un transport HTTP sûr.

Exemple Java

Chiffrer / Déchiffrer (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");
Important : lorsque le chiffrement est activé, déchiffrez les payloads de callback entrants et chiffrez les corps de requêtes RESTful sortantes avec la même clé.