Protocolo Push da ZKTeco Explicado
Um mergulho profundo em como os dispositivos ZKTeco se comunicam usando o protocolo push — estrutura de pacotes, fluxo de handshake e por que a maioria das bibliotecas open-source erra.
O que é o protocolo push?
O protocolo push da ZKTeco (às vezes chamado de PUSH SDK ou protocolo iclock) é um mecanismo onde o dispositivo biométrico inicia a conexão com um servidor, em vez do servidor consultar o dispositivo. Isso é fundamentalmente diferente da abordagem baseada em pull do SDK.
No modo push, o dispositivo envia requisições HTTP para um endereço de servidor configurado em intervalos regulares, carregando registros de ponto, status do dispositivo e respondendo a comandos. Isso o torna ideal para implantações na nuvem.
Estrutura de pacotes
Cada requisição push do dispositivo contém um padrão de URL específico e dados codificados em formulário. O handshake começa com uma requisição GET para /iclock/cdata, à qual o servidor responde com parâmetros de configuração do dispositivo.
As requisições subsequentes incluem dados de ponto (POST para /iclock/cdata), informações do dispositivo (GET para /iclock/getrequest) e resultados de comandos (POST para /iclock/devicecmd).
O fluxo de handshake
1. O dispositivo inicializa e envia GET /iclock/cdata?SN=XXXX para o servidor
2. O servidor responde com a configuração: Stamp, OpStamp, ErrorDelay, Delay, TransTimes, TransInterval, TransFlag e Realtime
3. O dispositivo começa a enviar dados de ponto no intervalo configurado
4. Entre os envios de dados, o dispositivo consulta GET /iclock/getrequest para comandos pendentes
5. O dispositivo executa os comandos e reporta os resultados via POST /iclock/devicecmd
Por que as bibliotecas open-source falham
A maioria das bibliotecas open-source para ZKTeco implementa o protocolo UDP baseado em pull, não o protocolo push. As poucas que tentam suportar o protocolo push geralmente têm problemas com: implementação incompleta do handshake, falta de enfileiramento de comandos, ausência de lógica de retentativa para entregas falhas e incapacidade de lidar com múltiplos dispositivos simultaneamente.
O motor de protocolo do PunchConnect lida com tudo isso — testado em batalha com mais de 80 dispositivos enviando dados simultaneamente em produção.
Conclusão
Entender o protocolo push é fundamental para construir integrações biométricas confiáveis. O PunchConnect abstrai toda essa complexidade por trás de uma API REST limpa e um sistema de webhooks, para que você nunca precise lidar com pacotes brutos de protocolo.