Reloj biométrico ZKTeco con Odoo: ponches, recesos y nómina
Cómo conectar un reloj ZKTeco a Odoo 17 (ADMS o TCP 4370), qué trae Odoo de fábrica y cómo resolvimos salidas olvidadas, recesos y altas en el reloj.
Odoo 17 no se conecta solo a un reloj biométrico ZKTeco. Su app Asistencias lleva el control de asistencia desde la pantalla de Odoo o desde un kiosco con gafete, RFID o PIN, pero no trae conector para relojes ponchadores de huella o rostro. Hace falta un módulo, con dos formas de conectarlo: que el reloj envíe las marcas (ADMS, modo push) o que el sistema las vaya a buscar (TCP por el puerto 4370, modo pull).
En Cover IT escribimos ese conector para Odoo 17. Abajo, las dos conexiones y cómo resolvimos salidas olvidadas, recesos y altas en el reloj.
Push o pull: las dos formas de conectar un ZKTeco
| El reloj envía (ADMS, push) | El sistema consulta (TCP 4370, pull) | |
|---|---|---|
| Quién abre la conexión | El reloj llama al servidor por HTTP o HTTPS | El servidor se conecta a la IP del reloj |
| Red | Basta con que el reloj salga a Internet; no se abren puertos en la oficina | El servidor tiene que llegar al reloj: misma red, puerto redirigido o VPN |
| Dónde se configura | En el reloj: COMM → Cloud Server Setting | En el sistema: IP, puerto (4370 de fábrica) y clave de comunicación |
| Cuándo llegan las marcas | Cuando el reloj las sube | Cuando el sistema consulta (en nuestro conector, cada 5 minutos) |
| Altas y bajas de empleados | El reloj recoge los comandos cuando pregunta | El sistema las manda en cada consulta |
Modo push (ADMS)
ZKTeco lo llama protocolo PUSH: va sobre HTTP y es el equipo el que sube los datos al servidor. El mismo canal sirve para agregar, modificar o borrar usuarios en el reloj. Se configura en Menú → COMM → Cloud Server Setting, que el manual de ZKTeco describe como la conexión con el servidor ADMS: dirección, puerto, nombre de dominio y proxy.
El reloj sube las marcas línea por línea (código, fecha y hora local, estado y modo de verificación) y pregunta si hay comandos pendientes:
POST /iclock/cdata?SN=<serie>&table=ATTLOG
1024 2026-10-05 08:01:23 0 1
GET /iclock/getrequest?SN=<serie>
C:7:DATA UPDATE USERINFO PIN=1024 Name=Jose Nunez Perez Pri=0
Como el reloj abre la conexión, funciona detrás del router de cualquier oficina; es el modo que preferimos. Los programas de asistencia de ZKTeco (BioTime, BioTime Pro, ZKBio Time) también reciben los relojes así. En el manual que revisamos hay un solo campo de servidor: el reloj le reporta a un solo destino.
Modo pull (TCP 4370)
El reloj escucha en su «TCP COMM. Port», 4370 de fábrica, y el sistema se conecta a leer las marcas (nosotros, con la librería no oficial pyzk). El manual pide equipo y PC en el mismo segmento de red: con un Odoo en la nube toca redirigir un puerto en el router o montar una VPN. La clave de comunicación (Comm Key) es de 1 a 6 dígitos y viene en 0: no la tomes como protección suficiente para dejar ese puerto abierto a Internet. Y mientras lee, pyzk desactiva el reloj para que nadie ponche a mitad de la lectura.
¿Qué modelos traen ADMS?
En la web de ZKTeco, las fichas del SpeedFace-V5L, el SpeedFace-V5L[TD], el MB10-VL y el MB560-VL ponen ADMS entre sus funciones estándar, y todos traen TCP/IP. La prueba rápida: si el menú COMM tiene «Cloud Server Setting» o «ADMS», tiene push. Los SpeedFace-V5L también traen control de acceso; nuestro conector solo se ocupa de la asistencia, no de las puertas.
Qué hace Odoo 17 de fábrica
- Ponche desde la propia pantalla de Odoo, con un botón en la barra superior (activo por defecto).
- Modo kiosco: el empleado escanea su gafete (con lector o con la cámara) o su llavero RFID, o se busca en una lista. Se puede pedir un PIN.
- Horas extra, con tolerancias a favor de la empresa y del empleado.
- En Enterprise, una vista gantt por día, semana, mes o año.
Lo que no trae es conexión con relojes biométricos: en el código de Odoo 17, Community y Enterprise, no hay nada de ZKTeco, y la documentación del kiosco solo habla de gafetes, RFID, selección manual y PIN. Y una regla que todo conector debe respetar: Odoo no admite dos asistencias abiertas (sin salida) del mismo empleado ni que se solapen.
Cómo lo resolvimos en Cover IT
Un adaptador por marca traduce su protocolo a «código, hora, estado y verificación», y un núcleo que no sabe de marcas arma las asistencias. Hoy el adaptador es ZKTeco, push y pull; otra marca entra sin tocar el núcleo.
Marcas crudas que no se editan
Cada marca se guarda tal como llegó, con el texto original, y es única por reloj, código y hora: si el reloj reenvía un lote, no se duplica. Las correcciones se hacen en la asistencia, que guarda su historial y queda marcada «corregida a mano». La hora llega local y sin zona; la pasamos a UTC, pero el «día» se mira en hora local: a las 9 de la noche en Santo Domingo ya es el día siguiente en UTC.
Emparejar entrada y salida
Las marcas de cada empleado alternan entrada y salida; quien poncha el almuerzo queda con dos tramos en el día. No depende de que el empleado apriete bien la tecla de entrada o salida: ese estado se guarda, pero no decide. Los casos difíciles:
| Caso | Qué hace el conector |
|---|---|
| Puso el dedo dos veces | Una marca a menos de 3 minutos de la anterior es repetida y no cuenta. Se ajusta por reloj. |
| Turno de noche | La entrada se cierra con la marca siguiente si es del mismo día o si no han pasado más de 12 horas. |
| Olvidó ponchar la salida | Esa entrada se cierra en cero horas y queda marcada «Falta la salida», para corregirla a mano; la marca siguiente abre otra. Así se cumple la regla de una sola asistencia abierta. |
| Marca que llega tarde (otro reloj, un reenvío) | Queda «fuera de orden». «Re-emparejar» rearma en orden las asistencias del reloj desde ese día y respeta las corregidas a mano. |
| Código que nadie tiene | Queda «sin empleado». Al asignarla guardas el código en la ficha y se arreglan todas sus marcas, o solo las elegidas si alguien ponchó con el usuario de otro. |
Recesos y quién se pasa
El empleado poncha la salida para ir al receso y la entrada al volver; el receso es ese hueco. Hasta 180 minutos (el tope, ajustable) se mide; más largo es turno partido y no se mide, para no dar falsos avisos.
El tiempo permitido sale, en este orden, del acuerdo particular en la ficha del empleado, de la ventana de almuerzo de su horario o del valor de la compañía (60 minutos por defecto). Quien sale a las 12:00 y vuelve a las 13:30 con 60 permitidos tiene 30 minutos de exceso, marcados en su asistencia de la tarde y en el reporte «Recesos excedidos».
Altas y bajas en el reloj desde Odoo
Cada empleado tiene su «Código en el reloj», distinto del PIN del kiosco y único en la compañía. Al crearlo, renombrarlo, cambiarle el código o archivarlo, Odoo deja en cola el alta o la baja para los relojes de su compañía. Un comando sin respuesta en 30 minutos se reintenta, hasta 5 veces. El nombre va sin acentos y cortado a 24 caracteres, lo que admite el reloj: «José Núñez Pérez» llega como «Jose Nunez Perez». Las huellas se registran en el propio reloj; Odoo no copia plantillas biométricas.
Vista por quincena
Al gantt de Asistencias le agregamos «Quincena»: del 1 al 15 y del 16 al último día del mes. Las flechas saltan por el borde de la quincena en vez de sumar 15 días, que en febrero o en meses de 31 días cae en la quincena equivocada. La barra de cada empleado compara horas trabajadas con esperadas.
Tropiezos que salieron al conectar relojes
- El primer contacto trae todo el historial. Por eso cada reloj tiene «Ignorar marcas anteriores a».
- Un reloj nuevo no cuenta hasta que alguien lo aprueba. La primera versión descartaba sus marcas mientras tanto, y se perdían: el reloj no reenvía lo que ya le contestamos «OK». Ahora quedan retenidas.
- Algunos relojes mandan las marcas como formulario web. El servidor consumía el cuerpo al interpretarlo y llegaban cero marcas. Ahora lo rearmamos.
- Un reloj no sigue redirecciones. Si el firmware no trae HTTPS y habla por el puerto 80, hay que contestarle ahí sin mandarlo a HTTPS. Si lo permite, usamos HTTPS en el 443.
De la asistencia a la nómina
Odoo Enterprise puede generar las entradas de trabajo de la nómina desde las asistencias cuando el contrato las usa como origen; el conector hace que esa base llegue sin salidas olvidadas escondidas. Las retenciones y los aportes están en IR-3, retenciones a asalariados y TSS, y si aún eliges sistema, en nuestra guía de qué es un ERP.
Con una sola oficina y pocos empleados, el kiosco de Odoo con gafete o PIN puede bastarte. Si ya tienes relojes ZKTeco, varias sucursales o quieres medir recesos y revisar la quincena antes de la nómina, lo montamos sobre Odoo como parte de tu ERP: Escríbenos.
Fuentes
- Odoo, Attendances y Kiosks (documentación 17.0).
- ZKTeco, fichas del SpeedFace-V5L, SpeedFace-V5L[TD], MB10-VL y MB560-VL.
- ZKTeco, ZKBio Time.
- ZKTeco, User Manual, 5/7-inch Linux Visible Light Product (2019, copia de distribuidor): Cloud Server Setting, puerto 4370 y Comm Key.
- ZKTeco, General Introduction of PUSH SDK (copia de distribuidor).
- ZKTeco Europe, ficha de BioTime 8.0 (copia de distribuidor).
- Tecnosinergia, introducción al protocolo PUSH (documento de distribuidor).
- pyzk, librería no oficial para el puerto 4370.
Preguntas Frecuentes
No de fábrica. La app Asistencias registra desde la pantalla de Odoo o desde un kiosco con gafete, RFID o PIN; para recibir los ponches de un reloj ZKTeco hace falta un módulo.
En ADMS (push) el reloj llama al servidor por HTTP o HTTPS y no hay que abrir puertos en la oficina. En TCP 4370 (pull) el servidor se conecta al reloj, que tiene que estar en la misma red o alcanzable por un puerto redirigido o una VPN.
Si en el menú COMM aparece «Cloud Server Setting» o «ADMS», tiene push. En la web de ZKTeco, las fichas del SpeedFace-V5L, el SpeedFace-V5L[TD], el MB10-VL y el MB560-VL ponen ADMS entre sus funciones estándar.
En nuestro conector, esa entrada se cierra en cero horas y queda marcada «Falta la salida» para corregirla a mano, y la marca siguiente abre una asistencia nueva. Así se cumple la regla de Odoo de una sola asistencia abierta por empleado.
El receso es el hueco entre la salida y la entrada siguiente: hasta 180 minutos se mide y más largo se toma como turno partido. El tiempo permitido sale del acuerdo del empleado, de la ventana de almuerzo de su horario o del valor de la compañía (60 minutos por defecto).
Agenda 30 minutos
Comenzar AhoraArtículos Relacionados

Conciliación bancaria: qué es y cómo hacerla en Odoo (RD)
Qué es la conciliación bancaria, un ejemplo en RD$ que cuadra, por qué el Excel se queda corto y cómo conciliar en Odoo 17 los extractos de bancos de RD.

IR-3: retención de ISR a asalariados, TSS y nómina 2026
Qué es el IR-3, cuándo vence, cómo calcular la retención del ISR con la escala 2026, qué aporta cada quien a la TSS y qué cambia en 2027.

Qué es un ERP y cuándo lo necesita tu empresa en RD
Qué es un ERP, qué módulos usan de verdad 10 empresas dominicanas que operamos, qué cambia en RD (e-CF, 606, TSS) y cuándo no lo necesitas.
