Support Hub/API & Integrations/Comment gérer les événements de pointage en double et hors…
Translated from the English article and reviewed by a person. Read the English original
Developer

Comment gérer les événements de pointage en double et hors d'ordre

Comment gérer les événements de pointage en double et hors d'ordre

 

La présence biométrique en temps réel semble simple : une personne scanne, votre système reçoit un événement, et vous l'enregistrez. En pratique, les données de présence sont plus désordonnées. Le même événement peut arriver deux fois. Un employé peut passer son badge deux fois de suite sur le lecteur. Un appareil qui a perdu sa connexion peut envoyer un pointage de sortie du matin dans l'après-midi. Quelqu'un peut appuyer sur le mauvais bouton d'entrée. Si votre système enregistre chaque événement exactement tel qu'il arrive, ces petits problèmes se transforment en heures travaillées erronées, en litiges de paie et en rapports auxquels personne ne fait confiance. Ce guide explique les différents types d'événements de pointage en double et hors d'ordre, pourquoi ils se produisent, et un ensemble de règles claires, fondées sur OperationID et LogTime, qui permettent de garder vos enregistrements de présence propres.

01 · Le problème

Pourquoi des données de présence propres sont plus difficiles à obtenir qu'il n'y paraît

Les événements de présence proviennent d'appareils physiques, répartis sur plusieurs sites, utilisés par des personnes réelles et connectés via des réseaux qui peuvent parfois se couper. Chacun de ces éléments crée une façon pour les données d'arriver de manière imparfaite. Aucun d'entre eux n'est un défaut du système biométrique. Ce sont simplement les conséquences de la rencontre entre le monde physique et le logiciel.

La bonne nouvelle est que chaque événement de pointage issu de Cams Biometrics Gateway contient les informations nécessaires pour le nettoyer. Deux champs font l'essentiel du travail :

Champ Ce que c'est Ce qu'il permet de faire
OperationID Une référence unique pour chaque événement envoyé par la Gateway Reconnaître exactement le même événement s'il arrive plus d'une fois
LogTime L'heure à laquelle la personne a réellement scanné, avec le décalage du fuseau horaire de l'appareil Placer les événements dans leur véritable ordre chronologique, quelle que soit leur date d'arrivée

Trois autres champs aident pour les cas plus complexes : UserId identifie la personne, SerialNumber identifie l'appareil, et Type indique si la personne a pointé l'entrée ou la sortie.

Un événement de pointage issu de l'API Callback

{
  "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"
  }
}

02 · Tous les doublons ne se ressemblent pas

Quatre types de doublons d'événements de pointage

L'erreur la plus courante consiste à traiter tous les doublons de la même manière. Il en existe quatre types différents, et chacun nécessite une solution différente. Certains sont techniques, d'autres proviennent de la façon dont les personnes utilisent les appareils.

Type de doublon À quoi il ressemble Comment le reconnaître Que faire
Événement renvoyé Le même événement exact arrive deux fois Même OperationID Ignorer la deuxième copie, mais répondre quand même avec done
Import en chevauchement Un événement reçu par callback est importé à nouveau lors d'une réconciliation Même UserId, LogTime et SerialNumber, provenant d'une source différente Ignorer la deuxième copie
Double scan Une personne passe son badge deux fois en quelques secondes OperationID différents, même personne, LogTime très rapprochés Traiter comme un seul pointage, en appliquant une règle d'écart minimal
Pointage mal étiqueté Une personne appuie sur entrée alors qu'elle voulait pointer la sortie Deux entrées consécutives sans sortie entre les deux Appliquer une règle d'appariement lors du calcul des heures

Doublons techniques et doublons humains

Les deux premiers types sont techniques : il s'agit du même scan vu deux fois par votre système, et ils doivent simplement être ignorés. Les deux derniers sont humains : ce sont de véritables scans distincts, et décider de leur signification relève d'une règle métier. Gardez ces deux types de traitement séparés. Votre récepteur ne doit supprimer que les doublons techniques. Votre logique de présence doit décider de ce que signifient les doublons humains.

Pourquoi les événements sont renvoyés

Un callback est un échange : la Gateway envoie un événement, et votre serveur répond par l'accusé de réception done. Si la réponse n'arrive jamais, parce que votre serveur était lent, a redémarré ou était brièvement injoignable, l'événement peut être envoyé à nouveau. Votre serveur a peut-être déjà enregistré la première copie. C'est pourquoi la règle est toujours la même : si vous avez déjà vu un OperationID, ne l'enregistrez pas une seconde fois, mais répondez avec done pour que la Gateway sache que l'événement est bien arrivé. Vérifiez le comportement exact de renvoi pour votre configuration dans la documentation de Cams Web API.

La réponse que votre récepteur envoie pour chaque événement, y compris les doublons

{ "status": "done" }

03 · L'ordre d'arrivée n'est pas l'ordre réel

Pourquoi les événements de pointage arrivent dans le désordre

Votre serveur reçoit les événements dans l'ordre d'arrivée. La présence doit être calculée dans l'ordre des scans. La plupart du temps, ces deux ordres coïncident. Parfois non.

Cause Ce qui se passe Exemple
Appareil ou site hors ligne Les appareils continuent d'enregistrer les scans localement, puis les envoient tous au retour de la connexion Une sortie de 13h01 arrive à 13h41, après un scan de 13h35 provenant d'un autre appareil
Délais réseau Les événements provenant de différents appareils empruntent des chemins différents et mettent des temps différents Deux scans séparés d'une seconde arrivent dans l'ordre inverse
Plusieurs appareils par personne Un employé pointe l'entrée à la porte principale et la sortie à une porte latérale Les événements de deux appareils s'entremêlent de façon imprévisible
Imports de réconciliation Les événements manquants sont complétés plus tard à partir des journaux des appareils Un événement du lundi est ajouté à votre système le mardi

La charge utile indique déjà la différence. LogTime correspond au moment où le scan a eu lieu. Time est l'horodatage du message lui-même, en GMT. Dans l'exemple de charge utile ci-dessus, le scan a eu lieu à 07h48 heure locale, mais le message a été envoyé à 04h19 GMT, soit 09h49 dans le même fuseau horaire, deux heures plus tard. Cet écart correspond exactement à une période hors ligne. Si vous triez selon l'arrivée, ce scan se retrouverait au mauvais endroit.

L'heure d'arrivée indique quand votre serveur a été informé. LogTime indique quand l'événement s'est réellement produit. La présence doit toujours suivre LogTime.

04 · Huit règles

Le guide des données de présence propres

Ces huit règles couvrent tous les cas décrits ci-dessus. Les quatre premières relèvent de votre récepteur de callback et de votre stockage. Les quatre dernières relèvent de la logique qui transforme les événements stockés en données de présence.

1

Stocker d'abord chaque événement brut

Enregistrez chaque charge utile exactement telle qu'elle a été reçue avant de faire quoi que ce soit d'autre. Si une règle s'avère incorrecte par la suite, vous pourrez retraiter les données à partir des données brutes.

2

Ignorer les OperationID répétés

Rendez OperationID unique dans votre stockage. Si le même OperationID arrive à nouveau, ne l'enregistrez pas et répondez quand même avec done.

3

Utiliser une clé naturelle pour les imports

Pour les événements importés lors d'une réconciliation, considérez la combinaison de UserId, LogTime et SerialNumber comme l'identité du scan, afin que le même scan ne soit jamais enregistré deux fois à partir de deux sources.

4

Trier par LogTime, jamais par arrivée

Analysez LogTime avec son décalage de fuseau horaire, et triez toujours selon ce champ lors du calcul de la présence.

5

Calculer en différé, pas à l'arrivée

Ne finalisez pas les heures d'une journée dès qu'une sortie arrive. Recalculez lorsque des événements tardifs arrivent, et ne verrouillez une journée qu'après une période de stabilisation, par exemple avant le lancement de la paie.

6

Fusionner les doubles scans avec un écart minimal

Traitez les scans de la même personne dans une courte fenêtre, par exemple deux minutes, comme un seul pointage. Choisissez une fenêtre adaptée à votre lieu de travail.

7

Apparier les pointages avec une règle claire

Décidez comment traiter les pointages mal étiquetés, par exemple en appariant les scans dans l'ordre chronologique, ou en utilisant le premier scan comme arrivée et le dernier comme départ. Appliquez la même règle partout.

8

Conserver une trace de chaque correction

Lorsqu'une règle fusionne, ignore ou réétiquette un scan, enregistrez ce qui s'est passé et pourquoi. Les RH et les auditeurs doivent pouvoir voir comment les scans bruts sont devenus des heures travaillées.

Gardez les horloges des appareils exactes

LogTime provient de l'horloge de l'appareil. Si l'heure d'un appareil est fausse, chaque scan effectué sur celui-ci est faux, et aucun tri ne pourra corriger cela. Assurez-vous que chaque appareil dispose de la bonne date, de la bonne heure et du bon fuseau horaire, et vérifiez-les après des coupures de courant ou des mises à jour du micrologiciel.

05 · Mettre les règles en pratique

Un exemple concret : un employé, une journée chargée

Voici une journée réaliste pour l'employé 2 sur le site de Burj Khalifa, présentée dans l'ordre dans lequel les événements ont atteint le serveur. Le site a perdu sa connexion pendant une partie de la journée.

Arrivé à OperationID Type LogTime Ce que font les règles
09:02 op-1001 CheckIn 08:58 Enregistré
09:03 op-1001 CheckIn 08:58 Même OperationID : ignoré, done envoyé
09:04 op-1002 CheckIn 08:59 À moins de deux minutes de 08:58 : fusionné comme double scan
13:40 op-1004 CheckIn 13:35 Enregistré
13:41 op-1003 CheckOut 13:01 Arrivé en retard après une période hors ligne : placé avant 13:35 selon LogTime
18:05 op-1005 CheckIn 18:04 Deuxième entrée d'affilée : appariée comme la sortie finale de la journée

Triée par LogTime et nettoyée, la journée se transforme en deux périodes de travail claires :

Période Début Fin Durée
Matin 08:58 13:01 4 heures 3 minutes
Après-midi 13:35 18:04 4 heures 29 minutes
Total travaillé 8 heures 32 minutes

Sans les règles, les mêmes événements bruts auraient pu produire trois entrées le matin, une sortie apparaissant après une entrée de l'après-midi, et aucune sortie en fin de journée. La paie aurait signalé des erreurs ou, pire, calculé les mauvaises heures sans que personne ne s'en aperçoive.

06 · Conçu pour des données propres

Comment Cams Gateway vous aide à garder des enregistrements propres

Des données de présence propres commencent par des événements qui contiennent les bonnes informations. Cams Biometrics Gateway est conçue pour que chaque événement reçu par votre système puisse être identifié, ordonné et tracé.

Fonctionnalité Cams Comment elle aide
OperationID sur chaque événement Donne à votre système un moyen fiable de reconnaître et d'ignorer les événements renvoyés
LogTime avec décalage du fuseau horaire Vous permet de placer les événements dans leur véritable ordre, où et quand ils arrivent
UserId, SerialNumber et LabelName Identifient la personne, l'appareil et le site, qui forment ensemble une clé naturelle pour les imports
Cache et file d'attente hors ligne Conservent les événements pendant les interruptions de connectivité et les livrent avec leurs horodatages d'origine
L'accusé de réception done Fournit un signal clair que chaque événement est bien arrivé, afin que la livraison puisse être confirmée
Opérations RESTful pour charger les journaux Vous permettent de récupérer les journaux des appareils à la demande pour réconcilier les données et combler les lacunes
Prompts du générateur de code IA Génèrent un récepteur de callback qui valide les jetons et enregistre chaque événement, prêt pour que vous y ajoutiez les règles de ce guide

Qui fait quoi

Cams Gateway livre chaque scan vérifié avec les informations nécessaires pour le nettoyer. La suppression des doublons techniques relève de votre récepteur de callback. La fusion des doubles scans, l'appariement des pointages et le calcul des heures relèvent de votre SIRH, de votre paie ou de votre logique de présence, là où vos règles métier sont déjà définies.

Questions fréquentes

Mon récepteur doit-il rejeter les événements en double avec une erreur ?

Non. Répondez avec done pour les doublons également. L'événement est bien arrivé en toute sécurité, et une réponse d'erreur pourrait entraîner un nouvel envoi. Il suffit de ne pas l'enregistrer.

Puis-je utiliser LogTime seul pour détecter les doublons ?

Pas à lui seul. Deux personnes différentes peuvent scanner à la même seconde. Utilisez OperationID pour les événements renvoyés, et la combinaison de UserId, LogTime et SerialNumber pour les imports.

Quelle doit être la durée de la fenêtre de double scan ?

Suffisamment longue pour détecter les appuis répétés accidentels, mais suffisamment courte pour ne pas fusionner de véritables pointages distincts. Une fenêtre d'une à deux minutes convient à la plupart des lieux de travail, mais choisissez-en une qui correspond à vos horaires et à l'agencement de votre site.

Quand la présence d'une journée doit-elle être verrouillée ?

Après une période de stabilisation permettant aux événements tardifs d'arriver, par exemple le lendemain matin ou juste avant le lancement de la paie. D'ici là, recalculez chaque fois que de nouveaux événements arrivent pour ce jour.

Cela s'applique-t-il aussi aux scans par visage, carte et code PIN ?

Oui. Chaque type d'entrée arrive dans le même format d'événement, avec les mêmes champs OperationID et LogTime, donc les mêmes règles s'appliquent quelle que soit la manière dont la personne a été vérifiée.

Conclusion : la confiance vient des règles, pas du hasard

Les événements de pointage en double et hors d'ordre ne sont pas des cas limites rares. Ils font partie du fonctionnement normal de la présence biométrique, avec de vrais appareils, de vrais réseaux et de vraies personnes. La différence entre des données de présence auxquelles les RH font confiance et des données qui provoquent des litiges ne tient pas au hasard. Elle tient à un petit ensemble de règles claires, appliquées de manière cohérente.

Ignorez les OperationID répétés. Triez tout par LogTime. Traitez les doublons humains comme des règles métier, et non comme des erreurs techniques. Calculez en différé, consignez chaque correction et gardez les horloges des appareils exactes. Une fois ces règles en place, chaque scan vérifié devient un enregistrement fiable.

Cams Biometrics Gateway vous fournit les données nécessaires pour que ces règles fonctionnent. Chaque événement de callback contient un OperationID, un LogTime avec son décalage de fuseau horaire, ainsi que les informations sur l'utilisateur, l'appareil et le site nécessaires pour identifier chaque scan, provenant d'appareils de plus de 15 marques. Le cache et la file d'attente hors ligne protègent les événements pendant les interruptions, et les opérations RESTful vous permettent de réconcilier les données avec les journaux des appareils chaque fois que vous en avez besoin. Découvrez la plateforme sur CamsBiometrics.com, consultez la documentation complète de Web API sur developer.camsbiometrics.com, et générez votre récepteur de callback avec les Prompts du générateur de code IA.

Was this article helpful?