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 callback | API RESTful |
|---|---|---|
| Initiateur | Terminal / Biometric Gateway | Votre serveur |
| Sens | Terminal → Votre serveur | Votre serveur → Terminal |
| Latence | Temps réel (millisecondes) | ~15 secondes |
| Déclencheur | Événement biométrique sur le terminal | HTTP POST depuis votre code |
| Votre rôle | Recevoir & acquitter | Envoyer la commande & interroger/attendre la réponse |
| Corps de la réponse | {"status":"done"} | {"Status":"done","OperationID":"…","StatusCode":0} |
| Comportement hors ligne | Mis en cache par le moteur ; livré dès que le serveur est de nouveau en ligne | Mis 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.
"j95xfejt3vr1"). Les réponses RESTful renvoient le même OperationID afin que vous puissiez associer requêtes et réponses.YYYY-MM-DD HH:mm:ss GMT +0000. Les horodatages locaux du terminal dans le payload peuvent utiliser un autre décalage horaire.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 :
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 0Ne remplacez jamais tous les modèles lors d’un callback — faites toujours un upsert par
Type + Index.
| Type | Description | Champs supplémentaires clés |
|---|---|---|
Card | Numéro de carte RFID / de proximité | Data (chaîne du numéro de carte) |
Password | Code PIN numérique | Data (chaîne du code PIN) |
Fingerprint | Modèle d’empreinte digitale — binaire encodé en Base64 | Index (index du doigt 0–9), Size, Data |
Face | Modèle de visage — JPEG ou binaire encodé en Base64 | Index, Size, Data |
Palm | Modèle des veines de la paume — binaire encodé en Base64 | Index, Data |
UserPhoto | Photo de profil de l’utilisateur — JPEG encodé en Base64 | Data |
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.
| Code | Statut | Description |
|---|---|---|
0 | Succès | Opération terminée avec succès. |
1 | Données de requête invalides | Le corps JSON est mal formé ou contient des valeurs invalides. |
2 | Service Tag ID invalide | Le paramètre de requête stgid ne correspond à aucun terminal enregistré. |
3 | Requête invalide | La structure de la requête ne correspond pas au format d’opération attendu. |
4 | Chiffrement invalide | Le payload chiffré (AES-256) n’a pas pu être déchiffré. Vérifiez votre clé de chiffrement. |
5 | Terminal hors ligne | Le terminal cible n’est actuellement pas connecté à la Biometric Gateway. |
6 | Délai d’opération dépassé | Le terminal n’a pas acquitté la commande dans le délai imparti. |
7 | Jeton d’authentification invalide | L’AuthToken de la requête ne correspond pas au jeton configuré pour le terminal. |
8 | Utilisateur déjà existant | Une opération d’ajout a été tentée pour un UserID qui existe déjà sur le terminal. |
9 | Utilisateur introuvable | L’UserID spécifié n’existe pas sur le terminal. |
10 | Erreur de modèle | Les données du modèle biométrique sont corrompues ou dans un format non pris en charge. |
11 | Mémoire du terminal pleine | Le terminal a atteint sa capacité maximale d’utilisateurs ou de modèles. |
13 | Clé de sécurité invalide | La clé de sécurité configurée dans l’API Monitor ne correspond pas. |
15 | Fonctionnalité non prise en charge | L’opération demandée n’est pas prise en charge par ce modèle de terminal ou ce mode de communication. |
999 | Erreur inconnue | Une 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.
| Port | Protocole | Usage |
|---|---|---|
80 | HTTP | Production. Associez votre URL de callback au port 80. Configuré dans l’API Monitor et appelé automatiquement à chaque pointage. |
443 | HTTPS | Production (sécurisé). HTTPS avec un certificat SSL valide. Recommandé pour la production. |
8123 | HTTP | Tests uniquement. Port non standard disponible temporairement pendant le développement. |
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 :
Chiffrement
Un chiffrement AES-256 optionnel peut être activé pour toutes les données échangées entre le Cams Protocol Engine et votre serveur.
AES/ECB/PKCS5PADDING).Exemple 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");