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éférence de l’API

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

Référence de l’API

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.

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`

Référence de l’API

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.

Informations complémentaires

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.

HTTPS recommandé. Utilisez HTTPS avec un certificat SSL valide en production. Assurez un renouvellement automatique sans redémarrage du serveur.

Informations complémentaires

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.

Informations complémentaires

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é.