Reloj biométrico ZKTeco conectado a Odoo 17: puerto TCP 4370, marcas repetidas a menos de 3 minutos, turnos de hasta 12 horas, receso de 60 minutos con tope de 180 y nombres de 24 caracteres en el reloj
Volver al blog
Automatización de Procesos

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.

8 min de lectura
1,628 palabras

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ónEl reloj llama al servidor por HTTP o HTTPSEl servidor se conecta a la IP del reloj
RedBasta con que el reloj salga a Internet; no se abren puertos en la oficinaEl servidor tiene que llegar al reloj: misma red, puerto redirigido o VPN
Dónde se configuraEn el reloj: COMM → Cloud Server SettingEn el sistema: IP, puerto (4370 de fábrica) y clave de comunicación
Cuándo llegan las marcasCuando el reloj las subeCuando el sistema consulta (en nuestro conector, cada 5 minutos)
Altas y bajas de empleadosEl reloj recoge los comandos cuando preguntaEl 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:

CasoQué hace el conector
Puso el dedo dos vecesUna marca a menos de 3 minutos de la anterior es repetida y no cuenta. Se ajusta por reloj.
Turno de nocheLa 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 salidaEsa 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 tieneQueda «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

FAQ

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 Ahora

Artículos Relacionados

¿Listo para transformar tu negocio?

Agenda una consulta gratuita con nuestro equipo de expertos.

Agenda una llamada

Sin compromiso · Te respondemos en menos de 24 h

¿Aún lo estás evaluando?

Déjanos tus datos y un especialista te contacta en menos de 24 h. Sin compromiso.

O escríbenos por WhatsApp
Reloj biométrico ZKTeco con Odoo: ponches, recesos y nómina | Cover IT