Support Hub/API & Integrations/Cómo gestionar los eventos de fichaje duplicados y fuera de orden
Translated from the English article and reviewed by a person. Read the English original
Developer

Cómo gestionar los eventos de fichaje duplicados y fuera de orden

Cómo gestionar los eventos de fichaje duplicados y fuera de orden

 

El control de asistencia biométrico en tiempo real parece sencillo: alguien se registra, su sistema recibe un evento y lo guarda. En la práctica, los datos de asistencia son más complejos. El mismo evento puede llegar dos veces. Un empleado puede pasar la tarjeta o el dedo dos veces seguidas por el lector. Un dispositivo que perdió la conexión puede enviar por la tarde una salida de la mañana. Alguien puede pulsar el botón de entrada equivocado. Si su sistema guarda cada evento exactamente como llega, estos pequeños problemas se convierten en horas trabajadas incorrectas, disputas de nómina e informes en los que nadie confía. Esta guía explica los distintos tipos de eventos de fichaje duplicados y fuera de orden, por qué se producen y un conjunto claro de reglas, basadas en OperationID y LogTime, que mantienen limpios sus registros de asistencia.

01 · El problema

Por qué los datos de asistencia limpios son más difíciles de lo que parecen

Los eventos de asistencia proceden de dispositivos físicos, distribuidos en varias sedes, utilizados por personas reales y conectados a redes que a veces se caen. Cada uno de estos hechos introduce una forma en que los datos pueden llegar de manera imperfecta. Ninguno de ellos es un fallo del sistema biométrico. Simplemente es lo que ocurre cuando el mundo físico se encuentra con el software.

La buena noticia es que cada evento de fichaje de Cams Biometrics Gateway contiene la información necesaria para limpiarlo. Dos campos hacen la mayor parte del trabajo:

Campo Qué es Qué le permite hacer
OperationID Una referencia única para cada evento que envía el Gateway Reconocer el mismo evento exacto si llega más de una vez
LogTime La hora en que la persona realmente se registró, con el desfase horario del dispositivo Ordenar los eventos en el orden real en que ocurrieron, sin importar cuándo lleguen

Tres campos más ayudan en los casos más difíciles: UserId identifica a la persona, SerialNumber identifica el dispositivo y Type indica si la persona registró una entrada o una salida.

Un evento de fichaje de la 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 · No todos los duplicados son iguales

Cuatro tipos de eventos de fichaje duplicados

El error más habitual es tratar todos los duplicados de la misma manera. Hay cuatro tipos diferentes, y cada uno necesita una solución distinta. Algunos son técnicos y otros se deben a la forma en que las personas utilizan los dispositivos.

Tipo de duplicado Cómo se presenta Cómo reconocerlo Qué hacer
Evento reenviado El mismo evento exacto llega dos veces Mismo OperationID Ignore la segunda copia, pero responda igualmente con done
Importación solapada Un evento recibido por callback se vuelve a importar durante una conciliación Mismos UserId, LogTime y SerialNumber, procedentes de otra fuente Ignore la segunda copia
Doble registro Una persona pasa la tarjeta o el dedo dos veces en pocos segundos OperationID distintos, misma persona, LogTime muy próximos entre sí Tratar como un único fichaje, aplicando una regla de intervalo mínimo
Fichaje mal etiquetado Una persona pulsa entrada cuando quería registrar una salida Dos entradas seguidas sin ninguna salida entre ellas Aplique una regla de emparejamiento al calcular las horas

Duplicados técnicos frente a duplicados humanos

Los dos primeros tipos son técnicos: se trata del mismo registro visto dos veces por su sistema, y deben ignorarse sin más. Los dos últimos son humanos: son registros reales e independientes, y decidir qué significan es una regla de negocio. Mantenga separados los dos tipos de tratamiento. Su receptor solo debe eliminar los duplicados técnicos. La lógica de asistencia debe decidir qué significan los duplicados humanos.

Por qué se producen los reenvíos

Un callback es una conversación: el Gateway envía un evento y su servidor responde con la confirmación done. Si la respuesta nunca llega, porque su servidor fue lento, se reinició o estuvo brevemente inaccesible, el evento puede volver a enviarse. Es posible que su servidor ya haya guardado la primera copia. Por eso la regla es siempre la misma: si ya ha visto un OperationID, no lo guarde de nuevo, pero responda con done para que el Gateway sepa que el evento llegó. Confirme el comportamiento exacto de los reenvíos en su configuración en la documentación de la Cams Web API.

La respuesta que su receptor envía por cada evento, incluidos los duplicados

{ "status": "done" }

03 · El orden de llegada no es el orden real

Por qué los eventos de fichaje llegan fuera de orden

Su servidor recibe los eventos en el orden de llegada. La asistencia debe calcularse en el orden de los registros. La mayoría de las veces coinciden. Otras veces no.

Causa Qué ocurre Ejemplo
El dispositivo o la sede se desconecta Los dispositivos siguen registrando los fichajes localmente y los envían todos cuando vuelve la conexión Una salida de las 13:01 llega a las 13:41, después de un registro de las 13:35 desde otro dispositivo
Retrasos de red Los eventos de distintos dispositivos siguen rutas diferentes y tardan tiempos distintos Dos registros separados por un segundo llegan en orden inverso
Varios dispositivos por persona Un empleado registra la entrada en la puerta principal y la salida en una puerta lateral Los eventos de dos dispositivos se intercalan de forma impredecible
Importaciones de conciliación Los eventos que faltan se completan después a partir de los registros de los dispositivos Un evento del lunes se añade a su sistema el martes

El propio mensaje ya indica la diferencia. LogTime es el momento en que se produjo el registro. Time es la marca de tiempo del propio mensaje, en GMT. En el ejemplo de mensaje anterior, el registro se produjo a las 07:48 hora local, pero el mensaje se envió a las 04:19 GMT, que equivale a las 09:49 en la misma zona horaria, dos horas después. Esa diferencia es exactamente lo que provoca un periodo sin conexión. Si ordenara los eventos por hora de llegada, ese registro quedaría en el lugar equivocado.

La hora de llegada indica cuándo se enteró su servidor. LogTime indica cuándo ocurrió el hecho. La asistencia debe seguir siempre a LogTime.

04 · Ocho reglas

El manual de datos de asistencia limpios

Estas ocho reglas cubren todos los casos anteriores. Las cuatro primeras corresponden a su receptor de callbacks y al almacenamiento. Las cuatro últimas corresponden a la lógica que convierte los eventos almacenados en asistencia.

1

Guarde primero todos los eventos sin procesar

Guarde cada carga útil exactamente como la recibe antes de hacer cualquier otra cosa con ella. Si más adelante una regla resulta incorrecta, puede volver a procesar los datos originales.

2

Ignore los OperationID repetidos

Haga que OperationID sea único en su almacenamiento. Si el mismo OperationID vuelve a llegar, omita su guardado y responda igualmente con done.

3

Use una clave natural para las importaciones

En los eventos importados durante la conciliación, considere la combinación de UserId, LogTime y SerialNumber como la identidad del registro, de modo que un mismo registro nunca se guarde dos veces desde dos fuentes.

4

Ordene por LogTime, nunca por llegada

Analice LogTime con su desfase horario y ordene siempre por este campo al calcular la asistencia.

5

Calcule con retraso, no en el momento de la llegada

No cierre las horas de un día en el momento en que llega una salida. Recalcule cuando lleguen eventos tardíos y bloquee un día solo después de un periodo de estabilización, por ejemplo antes de ejecutar la nómina.

6

Combine los dobles registros con un intervalo mínimo

Trate los registros de la misma persona dentro de un intervalo corto, por ejemplo dos minutos, como un único fichaje. Elija un intervalo adecuado para su centro de trabajo.

7

Empareje los fichajes con una regla clara

Defina cómo tratar los fichajes mal etiquetados, por ejemplo emparejando los registros en orden temporal, o usando el primer registro como entrada y el último como salida. Aplique la misma regla en todas partes.

8

Conserve un registro de cada corrección

Cuando una regla combine, ignore o reetiquete un registro, anote qué ocurrió y por qué. RRHH y los auditores necesitan ver cómo los registros originales se convirtieron en horas trabajadas.

Mantenga precisos los relojes de los dispositivos

LogTime procede del reloj del dispositivo. Si la hora de un dispositivo es incorrecta, todos los registros que haya hecho serán incorrectos, y ninguna ordenación podrá corregirlo. Asegúrese de que cada dispositivo tenga la fecha, la hora y la zona horaria correctas, y revíselas después de un corte de luz o de una actualización de firmware.

05 · Aplicar las reglas en conjunto

Un ejemplo práctico: un empleado, un día complicado

Este es un día realista del empleado 2 en la sede Burj Khalifa, mostrado en el orden en que los eventos llegaron al servidor. La sede perdió la conexión durante parte del día.

Llegada OperationID Type LogTime Qué hacen las reglas
09:02 op-1001 CheckIn 08:58 Guardado
09:03 op-1001 CheckIn 08:58 Mismo OperationID: ignorado, done enviado
09:04 op-1002 CheckIn 08:59 Dentro de dos minutos de las 08:58: combinado como doble registro
13:40 op-1004 CheckIn 13:35 Guardado
13:41 op-1003 CheckOut 13:01 Llegada tardía desde el periodo sin conexión: colocada antes de las 13:35 según LogTime
18:05 op-1005 CheckIn 18:04 Segunda entrada seguida: emparejada como la salida final del día

Ordenado por LogTime y depurado, el día se convierte en dos periodos de trabajo claros:

Periodo Inicio Fin Duración
Mañana 08:58 13:01 4 horas 3 minutos
Tarde 13:35 18:04 4 horas 29 minutos
Total trabajado 8 horas 32 minutos

Sin las reglas, los mismos eventos originales podrían haber producido tres entradas por la mañana, una salida que aparece después de una entrada de la tarde y ninguna salida al final del día. La nómina habría marcado errores o, peor aún, habría calculado mal las horas sin que nadie lo notara.

06 · Diseñado para datos limpios

Cómo Cams Gateway le ayuda a mantener registros limpios

Unos datos de asistencia limpios empiezan con eventos que contienen la información correcta. Cams Biometrics Gateway está diseñado para que cada evento que recibe su sistema pueda identificarse, ordenarse y rastrearse.

Función de Cams Cómo ayuda
OperationID en cada evento Ofrece a su sistema una forma fiable de reconocer e ignorar los eventos reenviados
LogTime con desfase horario Le permite colocar los eventos en su orden real, independientemente de dónde y cuándo lleguen
UserId, SerialNumber y LabelName Identifican a la persona, el dispositivo y la sede, que juntos forman una clave natural para las importaciones
Caché y cola sin conexión Retiene los eventos durante las interrupciones de conexión y los entrega con sus marcas de tiempo originales
La confirmación done Ofrece una señal clara de que cada evento llegó, de modo que la entrega puede confirmarse
Operaciones RESTful para cargar registros Le permiten obtener los registros de los dispositivos bajo demanda para conciliar y completar cualquier hueco
Prompts para generar código con IA Genera un receptor de callbacks que valida los tokens y registra cada evento, listo para que añada las reglas de esta guía

Quién hace qué

Cams Gateway entrega cada registro verificado con la información necesaria para depurarlo. Eliminar los duplicados técnicos corresponde a su receptor de callbacks. Combinar los dobles registros, emparejar los fichajes y calcular las horas corresponde a su HRMS, a su sistema de nómina o a su lógica de asistencia, donde ya residen sus reglas de negocio.

Preguntas frecuentes

¿Debe mi receptor rechazar los eventos duplicados con un error?

No. Responda también con done a los duplicados. El evento sí llegó correctamente, y una respuesta de error podría provocar que se vuelva a enviar. Simplemente omita su guardado.

¿Puedo usar solo LogTime para detectar duplicados?

No por sí solo. Dos personas diferentes pueden fichar en el mismo segundo. Use OperationID para los eventos reenviados y la combinación de UserId, LogTime y SerialNumber para las importaciones.

¿Cuánto debe durar el intervalo de doble registro?

Lo suficiente para captar los toques repetidos accidentales, pero lo bastante corto para no combinar fichajes separados genuinos. Un intervalo de uno a dos minutos se adapta a la mayoría de los centros de trabajo, aunque debe elegir el que se ajuste a sus turnos y a la distribución de sus instalaciones.

¿Cuándo debe bloquearse la asistencia de un día?

Después de un periodo de estabilización que permita la llegada de los eventos retrasados, por ejemplo a la mañana siguiente o justo antes de ejecutar la nómina. Hasta entonces, recalcule cada vez que lleguen nuevos eventos de ese día.

¿Esto también se aplica a los registros por rostro, tarjeta y PIN?

Sí. Todos los tipos de entrada llegan en el mismo formato de evento, con los mismos campos OperationID y LogTime, por lo que se aplican las mismas reglas independientemente de cómo se verificó la persona.

Conclusión: la confianza viene de las reglas, no de la suerte

Los eventos de fichaje duplicados y fuera de orden no son casos excepcionales. Forman parte normal del funcionamiento de un control de asistencia biométrico con dispositivos reales, redes reales y personas reales. La diferencia entre unos datos de asistencia en los que RRHH confía y unos datos que provocan disputas no es cuestión de suerte. Es un conjunto pequeño de reglas claras, aplicadas de forma coherente.

Ignore los OperationID repetidos. Ordene todo por LogTime. Trate los duplicados humanos como reglas de negocio, no como errores técnicos. Calcule con retraso, registre cada corrección y mantenga precisos los relojes de los dispositivos. Con estas reglas implantadas, cada registro verificado se convierte en un registro fiable.

Cams Biometrics Gateway le proporciona los datos necesarios para que estas reglas funcionen. Cada evento de Callback incluye un OperationID, un LogTime con su desfase horario y los datos de usuario, dispositivo y sede necesarios para identificar cada registro, en dispositivos de más de 15 marcas. La caché y la cola sin conexión protegen los eventos durante las interrupciones, y las operaciones RESTful le permiten conciliar con los registros de los dispositivos siempre que lo necesite. Explore la plataforma en CamsBiometrics.com, lea la documentación completa de la Web API en developer.camsbiometrics.com, y genere su receptor de callbacks con los Prompts de generación de código con IA.

Was this article helpful?