El Protocolo Push de ZKTeco Explicado
Un análisis profundo de cómo los dispositivos ZKTeco se comunican mediante el protocolo push — estructura de paquetes, flujo de handshake y por qué la mayoría de las bibliotecas open-source lo implementan mal.
¿Qué es el protocolo push?
El protocolo push de ZKTeco (también llamado PUSH SDK o protocolo iclock) es un mecanismo en el que el dispositivo biométrico inicia la conexión con un servidor, en lugar de que el servidor consulte al dispositivo. Esto es fundamentalmente diferente del enfoque basado en pull del SDK.
En modo push, el dispositivo envía solicitudes HTTP a una dirección de servidor configurada a intervalos regulares, transportando registros de asistencia, estado del dispositivo y respondiendo a comandos. Esto lo hace ideal para despliegues en la nube.
Estructura de paquetes
Cada solicitud push del dispositivo contiene un patrón de URL específico y datos codificados como formulario. El handshake comienza con una solicitud GET a /iclock/cdata, a la cual el servidor responde con parámetros de configuración del dispositivo.
Las solicitudes posteriores incluyen datos de asistencia (POST a /iclock/cdata), información del dispositivo (GET a /iclock/getrequest) y resultados de comandos (POST a /iclock/devicecmd).
El flujo del handshake
1. El dispositivo arranca y envía GET /iclock/cdata?SN=XXXX al servidor
2. El servidor responde con la configuración: Stamp, OpStamp, ErrorDelay, Delay, TransTimes, TransInterval, TransFlag y Realtime
3. El dispositivo comienza a enviar datos de asistencia en el intervalo configurado
4. Entre envíos de datos, el dispositivo consulta GET /iclock/getrequest para comandos pendientes
5. El dispositivo ejecuta los comandos y reporta los resultados vía POST /iclock/devicecmd
Por qué fallan las bibliotecas open-source
La mayoría de las bibliotecas open-source de ZKTeco implementan el protocolo pull basado en UDP, no el protocolo push. Las pocas que intentan soportar el protocolo push típicamente tienen problemas con: implementación incompleta del handshake, falta de cola de comandos, sin lógica de reintentos para entregas fallidas e incapacidad para manejar múltiples dispositivos simultáneamente.
El motor de protocolo de PunchConnect gestiona todo esto — probado en batalla con más de 80 dispositivos enviando datos concurrentemente en producción.
Conclusión
Comprender el protocolo push es clave para construir integraciones biométricas confiables. PunchConnect abstrae toda esta complejidad detrás de una API REST limpia y un sistema de webhooks, para que nunca tengas que lidiar con paquetes de protocolo sin procesar.