Come gestire eventi di timbratura duplicati e fuori sequenza
La rilevazione biometrica delle presenze in tempo reale sembra semplice: una persona timbra, il sistema riceve un evento e lo salva. In pratica, i dati di presenza sono più disordinati. Lo stesso evento può arrivare due volte. Un dipendente può passare il badge sul lettore due volte di seguito. Un dispositivo che ha perso la connessione può inviare in ritardo, nel pomeriggio, un'uscita del mattino. Qualcuno può premere il pulsante di entrata sbagliato. Se il tuo sistema salva ogni evento esattamente come arriva, questi piccoli problemi si trasformano in ore lavorate errate, contestazioni sulle buste paga e report di cui nessuno si fida. Questa guida spiega i diversi tipi di eventi di timbratura duplicati e fuori sequenza, perché si verificano e un insieme chiaro di regole, basate su OperationID e LogTime, che mantiene puliti i registri di presenza.
01 · Il problema
Perché i dati di presenza puliti sono più difficili di quanto sembri
Gli eventi di presenza provengono da dispositivi fisici, distribuiti su più sedi, usati da persone reali e collegati tramite reti che a volte cadono. Ciascuno di questi fattori introduce un modo in cui i dati possono arrivare in modo imperfetto. Nessuno di essi è un guasto del sistema biometrico. Sono semplicemente ciò che accade quando il mondo fisico incontra il software.
La buona notizia è che ogni evento di timbratura proveniente da Cams Biometrics Gateway contiene le informazioni necessarie per ripulirlo. Due campi svolgono gran parte del lavoro:
| Campo | Cos'è | Cosa consente di fare |
|---|---|---|
| OperationID | Un riferimento univoco per ogni evento inviato dal Gateway | Riconoscere esattamente lo stesso evento se arriva più di una volta |
| LogTime | L'ora in cui la persona ha effettivamente timbrato, con lo scostamento del fuso orario del dispositivo | Ordinare gli eventi nella sequenza reale in cui sono avvenuti, indipendentemente da quando arrivano |
Altri tre campi aiutano nei casi più complessi: UserId identifica la persona, SerialNumber identifica il dispositivo e Type indica se la persona ha premuto entrata o uscita.
|
Un evento di timbratura dalla Callback API {
"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 · Non tutti i duplicati sono uguali
Quattro tipi di eventi di timbratura duplicati
L'errore più comune è trattare ogni duplicato allo stesso modo. Esistono quattro tipi diversi, e ciascuno richiede una soluzione diversa. Alcuni sono tecnici, altri derivano dal modo in cui le persone usano i dispositivi.
| Tipo di duplicato | Come si presenta | Come riconoscerlo | Cosa fare |
|---|---|---|---|
| Evento inviato di nuovo | Lo stesso identico evento arriva due volte | Stesso OperationID | Ignorare la seconda copia, ma rispondere comunque con done |
| Importazione sovrapposta | Un evento ricevuto tramite callback viene importato di nuovo durante una riconciliazione | Stessi UserId, LogTime e SerialNumber, ma da una fonte diversa | Ignorare la seconda copia |
| Doppia timbratura | Una persona passa il badge sul lettore due volte nel giro di pochi secondi | OperationID diversi, stessa persona, LogTime molto ravvicinati | Trattare come un'unica timbratura, usando una regola di intervallo minimo |
| Timbratura con tipo errato | Una persona preme entrata quando intendeva premere uscita | Due entrate consecutive senza un'uscita tra le due | Applicare una regola di abbinamento nel calcolo delle ore |
|
Duplicati tecnici contro duplicati umani I primi due tipi sono tecnici: si tratta della stessa timbratura vista due volte dal sistema e devono semplicemente essere ignorati. Gli ultimi due sono umani: sono timbrature reali e distinte, e decidere cosa significano è una regola di business. Mantieni separati i due tipi di gestione. Il tuo ricevitore dovrebbe rimuovere solo i duplicati tecnici. La logica di presenza dovrebbe decidere cosa significano i duplicati umani. |
Perché avviene il reinvio
Un callback è una conversazione: il Gateway invia un evento e il tuo server risponde con la conferma done. Se la risposta non arriva, perché il server era lento, si è riavviato o è stato brevemente irraggiungibile, l'evento potrebbe essere inviato di nuovo. Il tuo server potrebbe aver già salvato la prima copia. Per questo la regola è sempre la stessa: se hai già visto un OperationID, non salvarlo di nuovo, ma rispondi con done in modo che il Gateway sappia che l'evento è arrivato. Verifica il comportamento esatto di reinvio per la tua configurazione nella documentazione della Cams Web API.
|
La risposta che il tuo ricevitore invia per ogni evento, inclusi i duplicati { "status": "done" }
|
03 · L'ordine di arrivo non è l'ordine reale
Perché gli eventi di timbratura arrivano fuori sequenza
Il tuo server riceve gli eventi nell'ordine di arrivo. La presenza deve essere calcolata nell'ordine di timbratura. Nella maggior parte dei casi i due ordini coincidono. A volte no.
| Causa | Cosa succede | Esempio |
|---|---|---|
| Dispositivo o sede offline | I dispositivi continuano a registrare le timbrature in locale, poi le inviano tutte insieme quando la connessione torna | Un'uscita delle 13:01 arriva alle 13:41, dopo una timbratura delle 13:35 da un altro dispositivo |
| Ritardi di rete | Gli eventi di dispositivi diversi seguono percorsi diversi e impiegano tempi diversi | Due timbrature a un secondo di distanza arrivano in ordine inverso |
| Più dispositivi per persona | Un dipendente timbra l'entrata al cancello principale e l'uscita da una porta laterale | Gli eventi di due dispositivi si alternano in modo imprevedibile |
| Importazioni di riconciliazione | Gli eventi mancanti vengono recuperati successivamente dai log dei dispositivi | Un evento di lunedì viene aggiunto al tuo sistema martedì |
Il payload indica già la differenza. LogTime è il momento in cui è avvenuta la timbratura. Time è il timestamp del messaggio stesso, in GMT. Nel payload di esempio sopra, la timbratura è avvenuta alle 07:48 ora locale, ma il messaggio è stato inviato alle 04:19 GMT, che corrispondono alle 09:49 nello stesso fuso orario, due ore dopo. Questo scarto è esattamente ciò che appare durante un periodo offline. Se ordinassi per ora di arrivo, quella timbratura finirebbe nel posto sbagliato.
|
L'ora di arrivo indica quando il tuo server ne è venuto a conoscenza. LogTime indica quando è avvenuto l'evento. La presenza deve sempre seguire LogTime. |
04 · Otto regole
Il manuale per dati di presenza puliti
Queste otto regole gestiscono tutti i casi descritti sopra. Le prime quattro appartengono al tuo ricevitore di callback e all'archiviazione. Le ultime quattro appartengono alla logica che trasforma gli eventi memorizzati in presenze.
|
Salva prima ogni evento grezzo Salva ogni payload esattamente come ricevuto, prima di fare qualsiasi altra operazione. Se una regola si rivela errata in seguito, puoi rielaborare i dati dal grezzo. |
|
|
Ignora gli OperationID ripetuti Rendi OperationID univoco nell'archiviazione. Se lo stesso OperationID arriva di nuovo, non salvarlo e rispondi comunque con done. |
|
|
Usa una chiave naturale per le importazioni Per gli eventi importati durante la riconciliazione, considera la combinazione di UserId, LogTime e SerialNumber come identità della timbratura, in modo che la stessa timbratura non venga mai memorizzata due volte da due fonti diverse. |
|
|
Ordina per LogTime, mai per ora di arrivo Interpreta LogTime con il suo scostamento di fuso orario e ordina sempre per questo campo quando calcoli la presenza. |
|
|
Calcola in differita, non all'arrivo Non chiudere le ore di una giornata nel momento in cui arriva un'uscita. Ricalcola quando arrivano eventi in ritardo e blocca una giornata solo dopo una finestra di consolidamento, ad esempio prima dell'elaborazione delle buste paga. |
|
|
Unisci le doppie timbrature con un intervallo minimo Tratta le timbrature della stessa persona entro una breve finestra, ad esempio due minuti, come un'unica timbratura. Scegli una finestra adatta al tuo luogo di lavoro. |
|
|
Abbina le timbrature con una regola chiara Decidi come gestire le timbrature con tipo errato, ad esempio abbinando le timbrature in ordine temporale, oppure usando la prima timbratura come entrata e l'ultima come uscita. Applica la stessa regola ovunque. |
|
|
Conserva una registrazione di ogni correzione Quando una regola unisce, ignora o rietichetta una timbratura, registra cosa è successo e perché. HR e revisori devono poter vedere come le timbrature grezze sono diventate ore lavorate. |
|
Mantieni accurati gli orologi dei dispositivi LogTime deriva dall'orologio del dispositivo. Se l'ora di un dispositivo è sbagliata, ogni timbratura su quel dispositivo è sbagliata, e nessun ordinamento potrà correggerla. Assicurati che ogni dispositivo abbia data, ora e fuso orario corretti, e verificali dopo interruzioni di corrente o aggiornamenti del firmware. |
05 · Mettere insieme le regole
Un esempio pratico: un dipendente, una giornata disordinata
Ecco una giornata realistica per il dipendente 2 nella sede Burj Khalifa, mostrata nell'ordine in cui gli eventi sono arrivati al server. La sede ha perso la connessione per parte della giornata.
| Arrivato | OperationID | Type | LogTime | Cosa fanno le regole |
|---|---|---|---|---|
| 09:02 | op-1001 | CheckIn | 08:58 | Salvato |
| 09:03 | op-1001 | CheckIn | 08:58 | Stesso OperationID: ignorato, inviato done |
| 09:04 | op-1002 | CheckIn | 08:59 | Entro due minuti dalle 08:58: unito come doppia timbratura |
| 13:40 | op-1004 | CheckIn | 13:35 | Salvato |
| 13:41 | op-1003 | CheckOut | 13:01 | Arrivato in ritardo dal periodo offline: collocato prima delle 13:35 in base a LogTime |
| 18:05 | op-1005 | CheckIn | 18:04 | Seconda entrata consecutiva: abbinata come l'uscita finale della giornata |
Ordinata per LogTime e ripulita, la giornata diventa due chiari periodi di lavoro:
| Periodo | Inizio | Fine | Durata |
|---|---|---|---|
| Mattina | 08:58 | 13:01 | 4 ore e 3 minuti |
| Pomeriggio | 13:35 | 18:04 | 4 ore e 29 minuti |
| Totale lavorato | 8 ore e 32 minuti |
Senza le regole, gli stessi eventi grezzi avrebbero potuto produrre tre entrate al mattino, un'uscita comparsa dopo un'entrata del pomeriggio e nessuna uscita alla fine della giornata. La busta paga avrebbe segnalato errori oppure, peggio, avrebbe calcolato ore sbagliate senza che nessuno se ne accorgesse.
06 · Progettato per dati puliti
Come Cams Gateway ti aiuta a mantenere registri puliti
I dati di presenza puliti iniziano da eventi che contengono le informazioni giuste. Cams Biometrics Gateway è progettato affinché ogni evento ricevuto dal tuo sistema possa essere identificato, ordinato e tracciato.
| Funzionalità di Cams | Come aiuta |
|---|---|
| OperationID su ogni evento | Offre al tuo sistema un modo affidabile per riconoscere e ignorare gli eventi inviati di nuovo |
| LogTime con scostamento del fuso orario | Consente di collocare gli eventi nel loro ordine reale, ovunque e in qualsiasi momento arrivino |
| UserId, SerialNumber e LabelName | Identificano persona, dispositivo e sede, che insieme formano una chiave naturale per le importazioni |
| Cache offline e coda | Trattiene gli eventi durante le interruzioni di connettività e li consegna con i loro timestamp originali |
| La conferma done | Fornisce un segnale chiaro che ogni evento è arrivato, così la consegna può essere confermata |
| Operazioni RESTful per caricare i log | Consentono di recuperare on demand i log dei dispositivi per riconciliare e colmare eventuali lacune |
| Prompt per il generatore di codice AI | Genera un ricevitore di callback che valida i token e registra ogni evento, pronto per l'aggiunta delle regole di questa guida |
|
Chi fa cosa Cams Gateway consegna ogni timbratura verificata con le informazioni necessarie per ripulirla. La rimozione dei duplicati tecnici spetta al tuo ricevitore di callback. L'unione delle doppie timbrature, l'abbinamento delle timbrature e il calcolo delle ore spettano al tuo HRMS, alla logica di payroll o di presenza, dove già risiedono le tue regole di business. |
Domande frequenti
|
Il mio ricevitore dovrebbe rifiutare gli eventi duplicati con un errore? No. Rispondi con done anche per i duplicati. L'evento è arrivato correttamente e una risposta di errore potrebbe causarne un nuovo invio. Semplicemente, non salvarlo. |
|
Posso usare solo LogTime per rilevare i duplicati? Non da solo. Due persone diverse possono timbrare nello stesso secondo. Usa OperationID per gli eventi inviati di nuovo e la combinazione di UserId, LogTime e SerialNumber per le importazioni. |
|
Quanto deve durare la finestra per la doppia timbratura? Abbastanza lunga da intercettare i tocchi ripetuti accidentali, abbastanza corta da non unire timbrature reali e separate. Una finestra da uno a due minuti va bene per la maggior parte dei luoghi di lavoro, ma scegli ciò che si adatta ai tuoi turni e alla disposizione della sede. |
|
Quando va bloccata la presenza di una giornata? Dopo una finestra di consolidamento che permetta l'arrivo degli eventi in ritardo, ad esempio la mattina successiva o poco prima dell'elaborazione delle buste paga. Fino ad allora, ricalcola ogni volta che arrivano nuovi eventi per quel giorno. |
|
Questo vale anche per le timbrature con volto, card e PIN? Sì. Ogni tipo di input arriva nello stesso formato di evento, con gli stessi campi OperationID e LogTime, quindi le stesse regole si applicano indipendentemente da come la persona è stata verificata. |
Conclusione: la fiducia nasce dalle regole, non dalla fortuna
Gli eventi di timbratura duplicati e fuori sequenza non sono casi limite rari. Sono una parte normale della gestione delle presenze biometriche su dispositivi reali, reti reali e con persone reali. La differenza tra dati di presenza di cui l'HR si fida e dati che causano contestazioni non sta nella fortuna. Sta in un piccolo insieme di regole chiare, applicate in modo coerente.
Ignora gli OperationID ripetuti. Ordina tutto per LogTime. Tratta i duplicati umani come regole di business, non come errori tecnici. Calcola in differita, registra ogni correzione e mantieni accurati gli orologi dei dispositivi. Con queste regole in vigore, ogni timbratura verificata diventa un registro affidabile.
Cams Biometrics Gateway ti fornisce i dati per far funzionare queste regole. Ogni evento di callback contiene un OperationID, un LogTime con lo scostamento del fuso orario e i dettagli di utente, dispositivo e sede necessari per identificare ogni timbratura, da dispositivi di oltre 15 marchi. La cache offline e la coda proteggono gli eventi durante le interruzioni, e le operazioni RESTful ti permettono di riconciliare con i log dei dispositivi ogni volta che serve. Esplora la piattaforma su CamsBiometrics.com, leggi la documentazione completa della Web API su developer.camsbiometrics.com e genera il tuo ricevitore di callback con i Prompt per il generatore di codice AI.