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.
|
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. |
|
|
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. |
|
|
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. |
|
|
Ordene por LogTime, nunca por llegada Analice LogTime con su desfase horario y ordene siempre por este campo al calcular la asistencia. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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.