Support Hub/API & Integrations/Come gestire eventi di timbratura duplicati e fuori sequenza
Translated from the English article and reviewed by a person. Read the English original
Developer

Come gestire eventi di timbratura duplicati e fuori sequenza

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.

1

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.

2

Ignora gli OperationID ripetuti

Rendi OperationID univoco nell'archiviazione. Se lo stesso OperationID arriva di nuovo, non salvarlo e rispondi comunque con done.

3

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.

4

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.

5

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.

6

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.

7

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.

8

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.

Was this article helpful?