Créer un récepteur de rappel biométrique en Python, Node.js et PHP
Un récepteur de rappel est le petit morceau de code qui transforme chaque scan d'empreinte, de visage ou de carte en un enregistrement dans votre propre système. Cams Biometrics Gateway envoie chaque scan vérifié à votre serveur sous forme de requête JSON, et votre serveur répond pour confirmer la bonne réception. Vous n'avez pas besoin d'écrire ce récepteur de zéro. Cams fournit des AI Code Generator Prompts pour Python, Node.js et PHP : collez-en un dans un assistant IA tel que Claude ou ChatGPT, et vous obtenez un fichier complet et fonctionnel comprenant un récepteur de rappel, un client REST et une interface de test. Ce tutoriel explique ce que doit faire un récepteur, comment en générer un pour votre langage, comment le configurer et comment le tester avant la mise en production.
01 · Les six tâches
Ce que doit faire un récepteur de rappel
Quel que soit le langage utilisé, chaque récepteur de rappel biométrique accomplit les mêmes six tâches. Ce sont aussi les points à vérifier dans tout code que vous générez.
| Tâche | Ce que cela signifie | Pourquoi c'est important |
|---|---|---|
| 1. Accepter la requête | Recevoir une requête POST HTTP/HTTPS avec un corps JSON brut | C'est ainsi que la Gateway transmet chaque événement |
| 2. Vérifier le jeton | Vérifier l'AuthToken par rapport au jeton de rappel attendu | Empêche toute autre personne d'envoyer de fausses présences à votre URL |
| 3. Router selon le type d'événement | Examiner la clé présente dans RealTime et la traiter en conséquence | Tous les rappels ne sont pas des pointages ; certains signalent des photos ou des modifications d'utilisateurs |
| 4. Ignorer les doublons | Utiliser l'OperationID pour ignorer les événements déjà enregistrés | Une livraison répétée ne crée jamais un double enregistrement |
| 5. Stocker et journaliser | Enregistrer les champs nécessaires et journaliser chaque rappel | Crée l'enregistrement qu'utiliseront votre SIRH, votre paie ou votre tableau de bord |
| 6. Répondre « done » | Renvoyer {“status”:”done”} avec HTTP 200 | Indique à la Gateway que l'événement est bien arrivé |
02 · Connaître vos données
La charge utile que vous recevrez
Le rappel le plus courant est un journal de pointage, envoyé à chaque scan. Enregistrez cet exemple sous sample.json, car vous l'utiliserez plus tard pour tester votre récepteur.
|
API de rappel, requête PunchLog envoyée à votre récepteur {
"RealTime": {
"OperationID": "9nu1wak5616p",
"LabelName": "Burj Khalifa",
"SerialNumber": "ZHM11xxxxxxxx",
"PunchLog": {
"Type": "CheckOut",
"Temperature": "36.8",
"FaceMask": false,
"InputType": "Fingerprint",
"UserId": "2",
"LogTime": "2020-09-17 07:48:22 GMT +0530"
},
"AuthToken": "COJJ7eiIPBGUfmIQPvh2PJWWDLX7OuKs",
"Time": "2020-09-17 04:19:03 GMT +0000"
}
}
|
Après avoir traité un rappel, votre récepteur doit répondre avec HTTP 200 et exactement ce corps :
|
API de rappel, réponse que votre récepteur doit renvoyer { "status": "done" } (HTTP 200)
|
Types d'événements de rappel
Chaque rappel arrive dans un objet RealTime. Votre récepteur décide quoi faire en vérifiant laquelle de ces clés est présente :
| Clé dans RealTime | Ce qu'elle signale |
|---|---|
| PunchLog | Un scan de présence : qui, arrivée ou départ, quand et comment |
| UserUpdated | Les informations d'un utilisateur ont été mises à jour sur l'appareil |
Deux détails qui piègent les développeurs
| Détail | Points d'attention |
|---|---|
| La clé de réponse est en minuscules | Renvoyer status en minuscules avec la valeur done. Ne copiez pas le champ Status en majuscule des réponses de l'API RESTful |
| Le format de LogTime | LogTime ressemble à 2020-09-17 07:48:22 GMT +0530. Il s'agit de l'heure réelle du scan avec le décalage de l'appareil. Analysez-la en tenant compte du décalage et utilisez-la comme heure de pointage |
03 · Laissez l'IA écrire le code
Générez votre récepteur avec les AI Code Generator Prompts
Cams publie un fichier de prompt prêt à l'emploi pour chaque langage serveur pris en charge. Chaque prompt contient un résumé de la spécification Cams Web API 3.0 et des instructions claires sur ce qu'il faut construire. Vous le collez dans un assistant IA, et l'assistant génère une implémentation complète en un seul fichier pour votre environnement.
|
Téléchargez le fichier de prompt Choisissez votre langage dans la section suivante et téléchargez son fichier de prompt .txt. |
|
|
Collez-le dans un assistant IA Ouvrez Claude, ChatGPT, Copilot ou tout outil de codage IA, puis collez l'intégralité du contenu du prompt. |
|
|
Obtenez un fichier complet et fonctionnel L'IA génère un fichier unique. Définissez vos valeurs de configuration, déployez-le et exécutez-le. |
| Chaque fichier généré comprend | Ce qu'il fait |
|---|---|
| Récepteur de rappel | Lit le corps POST brut, valide l'AuthToken, route selon le type d'événement, journalise chaque rappel, enregistre les journaux de pointage, sauvegarde les photos de présence et répond « done » |
| Client REST | Une fonction de requête générique ainsi que des fonctions d'encapsulation pour les 27 opérations RESTful, telles que AddUser, DeleteUser, ResendAllUser et UpdateAccessTime |
| Interface de test HTML | Une page de navigateur avec vos champs de configuration, une liste déroulante des opérations, un éditeur JSON prérempli avec des modèles de requêtes, un afficheur de réponses et une liste des rappels récents |
|
La documentation en ligne passe en premier Chaque prompt demande à l'IA de lire l'intégralité de la documentation Cams Web API et de la considérer comme la source de référence pour les opérations, les schémas JSON, les noms de champs et les codes de réponse. Si un élément du résumé du prompt entre en contradiction avec la documentation en ligne, la documentation prévaut. |
04 · Choisissez votre langage
Prompts pour Python, Node.js et PHP
Chaque prompt est optimisé pour produire un code idiomatique, avec un minimum de dépendances pour son langage.
|
|
|
Des prompts sont également disponibles pour C# (.NET 8) avec Minimal API, Java avec le HttpServer intégré et sans dépendances, Go avec net/http et la bibliothèque standard uniquement, et Ruby avec Sinatra et SQLite. Vous pouvez tous les trouver dans la section AI Code Generator Prompts de la documentation Cams Web API. Obtenir les prompts.
05 · Trois valeurs à définir
Configurer le fichier généré
Le fichier généré comporte un bloc de configuration en haut. Dans la version PHP, il ressemble à ceci, et les autres langages utilisent les mêmes trois valeurs :
|
Bloc de configuration, version PHP $CONFIG = [
'base_url' => 'https://YOUR_RESTFUL_ENDPOINT_URL',
'stgid' => 'YOUR_SERVICE_TAG_ID',
'auth_token' => 'YOUR_AUTH_TOKEN',
];
|
| Paramètre | Ce qu'il faut saisir |
|---|---|
| base_url | L'URL du point de terminaison RESTful issue de votre compte Cams API Monitor |
| stgid | Votre identifiant de Service Tag. |
| auth_token | Votre AuthToken, inclus dans vos requêtes RESTful sortantes et vérifié par rapport à l'AuthToken des requêtes de rappel entrantes. |
|
Gardez les jetons hors du code partagé Pour un test rapide, saisir les valeurs directement dans le bloc de configuration convient. Avant la production, placez les jetons dans des variables d'environnement ou dans un gestionnaire de secrets, afin qu'ils n'apparaissent jamais dans le contrôle de version ou dans un fichier partagé. |
Une fois configuré et déployé à une adresse HTTPS publique, renseignez cette adresse comme URL de rappel dans Cams Gateway. À partir de ce moment, chaque scan vérifié atteint votre récepteur en temps réel.
06 · Tester avant de connecter les appareils
Tester votre récepteur
Vous n'avez pas besoin d'un appareil biométrique pour tester le récepteur de rappel. Envoyez-lui vous-même l'exemple de charge utile avec cURL, en utilisant un jeton de rappel correspondant, puis vérifiez la réponse.
|
Terminal, envoyer un rappel de test # Save the sample payload as sample.json, then send it to your receiver:
curl -X POST https://YOUR_SERVER/YOUR_CALLBACK_PATH \
-H "Content-Type: application/json" \
-d @sample.json
# Expected response (HTTP 200):
# {"status":"done"}
|
| Test | Ce qu'il faut envoyer | Résultat attendu |
|---|---|---|
| Événement valide | sample.json, avec l'AuthToken défini sur votre auth_token | HTTP 200 avec done, et le pointage est enregistré |
| Événement en double | La même requête une seconde fois | HTTP 200 avec done, et aucun second enregistrement n'est créé |
| Mauvais jeton | sample.json avec un AuthToken différent | Rejeté, et rien n'est enregistré |
| Événement d'arrivée | sample.json avec Type remplacé par CheckIn | Enregistré comme une arrivée |
| Opération RESTful | Utiliser l'interface de test HTML intégrée pour envoyer une opération | Une réponse avec Status et StatusCode |
L'interface de test HTML générée facilite l'essai du côté RESTful : ouvrez le fichier dans un navigateur, choisissez une opération dans la liste déroulante, ajustez le JSON prérempli, puis envoyez-le. L'afficheur des rappels récents, sur la même page, confirme que vos rappels de test ont bien été reçus.
07 · Liste de contrôle de production
Vérifier avant la mise en service
Le code généré par l'IA est un point de départ rapide et fiable, mais, comme tout code, il doit être vérifié avant de traiter de vraies données d'employés.
| Élément | Terminé lorsque |
|---|---|
| Code relu | Un développeur a lu le fichier généré et comprend le rôle de chaque section |
| HTTPS uniquement | Le récepteur n'est accessible que via HTTPS avec un certificat valide |
| Jetons protégés | Les AuthTokens sont stockés dans des variables d'environnement ou un gestionnaire de secrets |
| Doublons gérés | L'OperationID est enregistré et vérifié afin que les livraisons répétées soient ignorées |
| Stockage adapté | Le stockage dans un fichier JSON convient aux petites installations ; les déploiements plus importants peuvent passer à une base de données de production |
| Interface de test protégée | La page de test HTML est protégée par mot de passe ou désactivée sur les serveurs publics |
| Photos traitées avec soin | Les photos de présence enregistrées sur disque sont soumises à un contrôle d'accès et conservées uniquement le temps nécessaire |
| Supervision en place | Les erreurs et les volumes de rappels inhabituels sont journalisés et signalés par votre propre supervision |
|
Placez les règles métier ailleurs La mission du récepteur est d'accepter, de vérifier, de router, de stocker et de confirmer. Déterminer qui est en retard, calculer les heures supplémentaires ou envoyer des notifications relève des systèmes qui lisent les événements enregistrés, tels que votre SIRH, votre ERP ou vos outils d'automatisation. Un récepteur ciblé est plus facile à sécuriser et à maintenir. |
Questions fréquentes
|
Dois-je écrire moi-même du code ? En général, non. Les AI Code Generator Prompts produisent un fichier complet et fonctionnel. Vous définissez trois valeurs de configuration, déployez-le et testez-le. Un développeur doit tout de même relire le code avant la mise en production. |
|
Quels assistants IA fonctionnent avec les prompts ? Tout assistant de codage IA performant, notamment Claude, ChatGPT et Copilot. Collez l'intégralité du contenu du prompt en une seule fois afin que l'assistant dispose de la spécification complète. |
|
Où trouver l'URL du point de terminaison RESTful et le Service Tag ID ? Les deux proviennent de votre compte Cams API Monitor. Les requêtes RESTful sont envoyées à l'URL du point de terminaison avec ?stgid= suivi de votre Service Tag ID. |
|
Pourquoi répondre done pour un événement en double ? Parce que l'événement est bien arrivé, même si vous l'avez déjà enregistré. Répondre done indique à la Gateway qu'il n'est pas nécessaire de le renvoyer. |
|
Puis-je utiliser un langage qui n'est pas listé ? Oui. Le récepteur de rappel doit seulement accepter une requête POST HTTPS et renvoyer du JSON. Les prompts sont un raccourci, et la même API fonctionne avec tout langage capable de faire cela. |
Conclusion : du prompt à la présence en temps réel en un après-midi
Un récepteur de rappel biométrique est petit, mais c'est lui qui transforme chaque scan vérifié en données en direct pour votre SIRH, votre paie, vos tableaux de bord et vos automatisations. Avec les AI Code Generator Prompts de Cams, vous n'avez plus besoin de le construire à partir d'une page blanche. Téléchargez le prompt pour Python, Node.js ou PHP, collez-le dans votre assistant IA, définissez trois valeurs et testez. Ensuite, vérifiez-le, sécurisez-le et laissez les données de présence en temps réel commencer à circuler.
Cams Biometrics Gateway fournit les événements dont votre récepteur a besoin. Son API de rappel envoie chaque scan vérifié en temps réel, dans un format JSON unique et cohérent, depuis des appareils de plus de 15 marques, et son API RESTful propose 27 opérations que votre client généré peut appeler. Toutes les communications passent par HTTP/HTTPS avec validation du jeton d'authentification et chiffrement AES-256 facultatif. Découvrez la plateforme sur CamsBiometrics.com et consultez la documentation complète de la Web API, y compris chaque AI Code Generator Prompt : Obtenir les prompts.