Como Tratar Eventos de Marcação Duplicados e Fora de Ordem
O registro de presença biométrica em tempo real parece simples: alguém passa pelo leitor, seu sistema recebe um evento e você o salva. Na prática, os dados de presença são mais confusos. O mesmo evento pode chegar duas vezes. Um funcionário pode encostar no leitor duas vezes seguidas. Um dispositivo que perdeu a conexão pode enviar uma saída da manhã à tarde. Alguém pode pressionar o botão de entrada errado. Se o seu sistema salvar cada evento exatamente como chega, esses pequenos problemas se transformam em horas trabalhadas incorretas, disputas na folha de pagamento e relatórios em que ninguém confia. Este guia explica os diferentes tipos de eventos de marcação duplicados e fora de ordem, por que acontecem e um conjunto claro de regras, baseadas em OperationID e LogTime, que mantém seus registros de presença limpos.
01 · O Problema
Por que Dados de Presença Limpos São Mais Difíceis do que Parecem
Os eventos de presença vêm de dispositivos físicos, espalhados por diferentes locais, usados por pessoas reais e conectados a redes que às vezes caem. Cada um desses fatores introduz uma forma de os dados chegarem de maneira imperfeita. Nenhum deles é uma falha do sistema biométrico. Eles simplesmente acontecem quando o mundo físico encontra o software.
A boa notícia é que cada evento de marcação do Cams Biometrics Gateway contém as informações necessárias para limpá-lo. Dois campos fazem a maior parte do trabalho:
| Campo | O que é | O que permite fazer |
|---|---|---|
| OperationID | Uma referência única para cada evento enviado pelo Gateway | Reconhecer exatamente o mesmo evento caso ele chegue mais de uma vez |
| LogTime | O horário em que a pessoa realmente passou no leitor, com o deslocamento de fuso horário do dispositivo | Colocar os eventos na ordem real em que aconteceram, independentemente de quando chegam |
Três outros campos ajudam nos casos mais difíceis: UserId identifica a pessoa, SerialNumber identifica o dispositivo e Type indica se a pessoa registrou entrada ou saída.
|
Um evento de marcação da 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 · Nem Todas as Duplicatas São Iguais
Quatro Tipos de Eventos de Marcação Duplicados
O erro mais comum é tratar todas as duplicatas da mesma forma. Existem quatro tipos diferentes, e cada um precisa de uma correção diferente. Alguns são técnicos, e outros vêm da forma como as pessoas usam os dispositivos.
| Tipo de duplicata | Como se apresenta | Como identificar | O que fazer |
|---|---|---|---|
| Evento reenviado | O mesmo evento exato chega duas vezes | Mesmo OperationID | Ignorar a segunda cópia, mas ainda responder com done |
| Importação sobreposta | Um evento recebido por callback é importado novamente durante uma reconciliação | Mesmos UserId, LogTime e SerialNumber, vindos de uma origem diferente | Ignorar a segunda cópia |
| Dupla leitura | Uma pessoa encosta duas vezes no leitor em poucos segundos | OperationIDs diferentes, mesma pessoa, LogTimes muito próximos | Tratar como uma única marcação, usando uma regra de intervalo mínimo |
| Marcação com tipo errado | Uma pessoa pressiona entrada quando queria registrar saída | Duas entradas seguidas, sem saída entre elas | Aplicar uma regra de pareamento ao calcular as horas |
|
Duplicatas técnicas versus duplicatas humanas Os dois primeiros tipos são técnicos: é a mesma leitura vista duas vezes pelo seu sistema, e devem simplesmente ser ignorados. Os dois últimos são humanos: são leituras reais e separadas, e definir o que significam é uma regra de negócio. Mantenha os dois tipos de tratamento separados. O seu receptor deve remover apenas as duplicatas técnicas. A lógica de presença deve decidir o que as duplicatas humanas significam. |
Por que ocorre o reenvio
Um callback é uma conversa: o Gateway envia um evento, e o seu servidor responde com a confirmação done. Se a resposta nunca chegar, porque o seu servidor estava lento, foi reiniciado ou ficou brevemente inacessível, o evento pode ser enviado novamente. O seu servidor pode já ter salvo a primeira cópia. Por isso, a regra é sempre a mesma: se você já viu um OperationID, não o salve novamente, mas responda com done para que o Gateway saiba que o evento foi recebido. Confirme o comportamento exato de reenvio para a sua configuração na documentação da Web API da Cams.
|
A resposta que o seu receptor envia para cada evento, inclusive duplicatas { "status": "done" }
|
03 · A Ordem de Chegada Não É a Ordem Real
Por que os Eventos de Marcação Chegam Fora de Ordem
O seu servidor recebe os eventos na ordem de chegada. A presença deve ser calculada na ordem em que as leituras aconteceram. Na maioria das vezes, essas ordens são iguais. Às vezes, não são.
| Causa | O que acontece | Exemplo |
|---|---|---|
| Dispositivo ou local fica offline | Os dispositivos continuam registrando leituras localmente e, quando a conexão retorna, enviam todas de uma vez | Uma saída das 13:01 chega às 13:41, depois de uma leitura das 13:35 em outro dispositivo |
| Atrasos na rede | Eventos de dispositivos diferentes percorrem rotas diferentes e levam tempos diferentes | Duas leituras com um segundo de diferença chegam em ordem invertida |
| Vários dispositivos por pessoa | Um funcionário registra entrada no portão principal e saída em uma porta lateral | Eventos de dois dispositivos se intercalam de forma imprevisível |
| Importações de reconciliação | Eventos ausentes são preenchidos depois, a partir dos registros do dispositivo | Um evento de segunda-feira é adicionado ao seu sistema na terça-feira |
O payload já mostra a diferença. LogTime é quando a leitura aconteceu. Time é o carimbo de data e hora da própria mensagem, em GMT. No payload de exemplo acima, a leitura aconteceu às 07:48 no horário local, mas a mensagem foi enviada às 04:19 GMT, o que equivale às 09:49 no mesmo fuso horário, duas horas depois. Essa diferença é exatamente o que um período offline parece. Se você ordenasse pela chegada, essa leitura ficaria no lugar errado.
|
O horário de chegada indica quando o seu servidor tomou conhecimento do evento. O LogTime indica quando ele aconteceu. A presença deve sempre seguir o LogTime. |
04 · Oito Regras
O Manual de Dados de Presença Limpos
Estas oito regras tratam todos os casos descritos acima. As quatro primeiras pertencem ao seu receptor de callback e ao armazenamento. As quatro últimas pertencem à lógica que transforma os eventos armazenados em presença.
|
Armazene primeiro cada evento bruto Salve cada payload exatamente como recebido, antes de fazer qualquer outra coisa com ele. Se uma regra se mostrar incorreta depois, você poderá reprocessar a partir dos dados brutos. |
|
|
Ignore OperationIDs repetidos Torne o OperationID único no seu armazenamento. Se o mesmo OperationID chegar novamente, não o salve e ainda assim responda com done. |
|
|
Use uma chave natural para importações Para eventos importados durante a reconciliação, trate a combinação de UserId, LogTime e SerialNumber como a identidade da leitura, de modo que a mesma leitura nunca seja armazenada duas vezes a partir de duas origens. |
|
|
Ordene por LogTime, nunca pela chegada Interprete o LogTime com o deslocamento de fuso horário e sempre ordene por ele ao calcular a presença. |
|
|
Calcule com atraso, não na chegada Não finalize as horas do dia no momento em que uma saída chega. Recalcule quando eventos atrasados chegarem e só bloqueie um dia após um período de estabilização, como antes da execução da folha de pagamento. |
|
|
Una duplas leituras com um intervalo mínimo Trate leituras da mesma pessoa dentro de um intervalo curto, por exemplo dois minutos, como uma única marcação. Escolha um intervalo adequado ao seu ambiente de trabalho. |
|
|
Faça o pareamento das marcações com uma regra clara Defina como tratar marcações com tipo errado, como parear leituras na ordem cronológica ou usar a primeira leitura como entrada e a última como saída. Aplique a mesma regra em todos os lugares. |
|
|
Mantenha um registro de cada correção Quando uma regra mescla, ignora ou reclassifica uma leitura, registre o que aconteceu e o motivo. RH e auditores precisam ver como as leituras brutas se tornaram horas trabalhadas. |
|
Mantenha os relógios dos dispositivos precisos O LogTime vem do relógio do dispositivo. Se o horário de um dispositivo estiver errado, todas as leituras nele estarão erradas, e nenhuma quantidade de ordenação corrigirá isso. Garanta que cada dispositivo tenha a data, a hora e o fuso horário corretos, e verifique-os após quedas de energia ou atualizações de firmware. |
05 · Colocando as Regras em Prática
Um Exemplo Prático: Um Funcionário, Um Dia Confuso
Veja um dia realista do funcionário 2 no local Burj Khalifa, mostrado na ordem em que os eventos chegaram ao servidor. O local perdeu a conexão durante parte do dia.
| Chegou | OperationID | Type | LogTime | O que as regras fazem |
|---|---|---|---|---|
| 09:02 | op-1001 | CheckIn | 08:58 | Salvo |
| 09:03 | op-1001 | CheckIn | 08:58 | Mesmo OperationID: ignorado, done enviado |
| 09:04 | op-1002 | CheckIn | 08:59 | Dentro de dois minutos de 08:58: mesclado como dupla leitura |
| 13:40 | op-1004 | CheckIn | 13:35 | Salvo |
| 13:41 | op-1003 | CheckOut | 13:01 | Chegou com atraso do período offline: posicionado antes das 13:35 pelo LogTime |
| 18:05 | op-1005 | CheckIn | 18:04 | Segunda entrada seguida: pareada como a saída final do dia |
Ordenados pelo LogTime e limpos, os eventos do dia formam dois períodos de trabalho claros:
| Período | Início | Fim | Duração |
|---|---|---|---|
| Manhã | 08:58 | 13:01 | 4 horas e 3 minutos |
| Tarde | 13:35 | 18:04 | 4 horas e 29 minutos |
| Total trabalhado | 8 horas e 32 minutos |
Sem as regras, os mesmos eventos brutos poderiam ter produzido três entradas pela manhã, uma saída aparecendo depois de uma entrada à tarde e nenhuma saída no fim do dia. A folha de pagamento teria apontado erros ou, pior, calculado as horas erradas sem que ninguém percebesse.
06 · Criado para Dados Limpos
Como o Cams Gateway Ajuda a Manter os Registros Limpos
Dados de presença limpos começam com eventos que trazem a informação certa. O Cams Biometrics Gateway foi projetado para que cada evento recebido pelo seu sistema possa ser identificado, ordenado e rastreado.
| Recurso do Cams | Como ajuda |
|---|---|
| OperationID em cada evento | Oferece ao seu sistema uma forma confiável de reconhecer e ignorar eventos reenviados |
| LogTime com deslocamento de fuso horário | Permite colocar os eventos na ordem real, onde e quando chegarem |
| UserId, SerialNumber e LabelName | Identificam a pessoa, o dispositivo e o local, que juntos formam uma chave natural para importações |
| Cache e fila offline | Mantém os eventos durante interrupções de conectividade e os entrega com seus carimbos de data e hora originais |
| A confirmação done | Fornece um sinal claro de que cada evento foi recebido, para que a entrega possa ser confirmada |
| Operações RESTful para carregar registros | Permitem buscar registros dos dispositivos sob demanda para reconciliar e preencher quaisquer lacunas |
| AI Code Generator Prompts | Gera um receptor de callback que valida tokens e registra cada evento, pronto para você adicionar as regras deste guia |
|
Quem faz o quê O Cams Gateway entrega cada leitura verificada com as informações necessárias para limpá-la. A remoção de duplicatas técnicas pertence ao seu receptor de callback. A mesclagem de duplas leituras, o pareamento de marcações e o cálculo das horas pertencem ao seu HRMS, à folha de pagamento ou à lógica de presença, onde as suas regras de negócio já estão definidas. |
Perguntas Frequentes
|
Meu receptor deve rejeitar eventos duplicados com um erro? Não. Responda com done também para duplicatas. O evento chegou com segurança, e uma resposta de erro pode fazer com que ele seja enviado novamente. Basta não salvá-lo. |
|
Posso usar apenas o LogTime para detectar duplicatas? Não isoladamente. Duas pessoas diferentes podem registrar leituras no mesmo segundo. Use o OperationID para eventos reenviados e a combinação de UserId, LogTime e SerialNumber para importações. |
|
Qual deve ser a duração da janela de dupla leitura? Longa o suficiente para capturar toques repetidos acidentais, e curta o suficiente para não mesclar marcações genuinamente separadas. Uma janela de um a dois minutos atende à maioria dos ambientes de trabalho, mas escolha o que se adapta aos seus turnos e ao layout do local. |
|
Quando a presença de um dia deve ser bloqueada? Após um período de estabilização que permita a chegada de eventos atrasados, por exemplo na manhã seguinte ou logo antes da execução da folha de pagamento. Até lá, recalcule sempre que novos eventos chegarem para aquele dia. |
|
Isso também se aplica a leituras de rosto, cartão e PIN? Sim. Todo tipo de entrada chega no mesmo formato de evento, com os mesmos campos OperationID e LogTime, portanto as mesmas regras se aplicam independentemente de como a pessoa foi verificada. |
Conclusão: A Confiança Vem das Regras, Não da Sorte
Eventos de marcação duplicados e fora de ordem não são casos raros. Eles fazem parte normal da operação de presença biométrica com dispositivos reais, redes reais e pessoas reais. A diferença entre dados de presença em que o RH confia e dados que geram disputas não está na sorte. Está em um pequeno conjunto de regras claras, aplicadas de forma consistente.
Ignore OperationIDs repetidos. Ordene tudo pelo LogTime. Trate duplicatas humanas como regras de negócio, não como erros técnicos. Calcule com atraso, registre cada correção e mantenha os relógios dos dispositivos precisos. Com essas regras em vigor, cada leitura verificada se torna um registro confiável.
O Cams Biometrics Gateway oferece os dados para fazer essas regras funcionarem. Cada evento de Callback traz um OperationID, um LogTime com o deslocamento de fuso horário e os detalhes de usuário, dispositivo e local necessários para identificar cada leitura, a partir de dispositivos de mais de 15 marcas. O cache e a fila offline protegem os eventos durante interrupções, e as operações RESTful permitem reconciliar com os registros dos dispositivos sempre que você precisar. Conheça a plataforma em CamsBiometrics.com, leia a documentação completa da Web API em developer.camsbiometrics.com e gere o seu receptor de callback com o AI Code Generator Prompts.