Deep-dive

Protocolo Push ZKTeco explicado: por que é essencial para o ponto eletrônico na nuvem

Os dispositivos ZKTeco suportam dois modos de conexão: pull (SDK) e push (nuvem). Saiba como o modo push elimina IPs estáticos, servidores locais e polling — e como receber dados de ponto em tempo real via API REST.

PunchConnect Team·Mar 27, 2026·10 min read

Introduction

Você comprou um dispositivo ZKTeco. Conectou à rede. Agora precisa dos dados de ponto na sua aplicação em nuvem. A pergunta é: o dispositivo envia os dados para você, ou você vai buscá-los no dispositivo?

Essa decisão arquitetural — push vs. pull — determina se sua integração funciona de forma confiável em escala ou quebra no momento em que você adiciona um segundo escritório. A maioria dos desenvolvedores começa pela abordagem pull (bibliotecas SDK), bate em um muro, e então descobre que o modo push existe. A essa altura, já perderam semanas.

Este artigo explica o que é o modo push, por que ele existe, como se compara à abordagem SDK, e como obter dados de ponto em tempo real sem tocar em protocolos brutos dos dispositivos.

Modo Pull: a abordagem SDK (e por que falha)

A forma tradicional de obter dados de um dispositivo ZKTeco é o modo pull. Seu servidor se conecta ao dispositivo na rede local, se autentica e solicita os registros. Bibliotecas como pyzk, node-zklib e zklib funcionam assim.

Parece simples no início. Escreve um script, conecta no IP do dispositivo, chama get_attendance(), pronto. Mas a simplicidade engana.

Veja o que dá errado em produção:

- Sua app roda na nuvem. AWS, Azure, Railway, DigitalOcean — nenhum desses consegue alcançar um dispositivo atrás de um roteador numa LAN corporativa. Você precisa de um servidor local rodando 24/7 como ponte.
- Os dispositivos mudam de IP. O TI reinicia o roteador, o lease DHCP expira, alguém desconecta o switch. Sua string de conexão agora está errada, e você não recebe dados até alguém notar.
- O polling não é tempo real. Você pergunta ao dispositivo "registros novos?" a cada 30 segundos. É banda desperdiçada em respostas vazias 95% do tempo.
- Não escala. Gerenciar conexões persistentes com 50+ dispositivos em múltiplos escritórios, cada um com sua configuração de rede? Isso é um trabalho de tempo integral.

O modo pull funciona para um dispositivo na LAN. No momento que você vai para multi-sites ou nuvem, você precisa do modo push.

Modo Push: o dispositivo se conecta a você

O modo push inverte a direção da conexão. O dispositivo inicia a conexão para um servidor na nuvem, não o contrário. O dispositivo não precisa de IP estático. Seu servidor não precisa estar na mesma rede. O dispositivo só precisa de acesso à internet.

No modo push, o dispositivo faz o trabalho pesado. Ele se conecta de saída para a nuvem, envia dados de ponto em tempo real, recebe comandos (sincronizar hora, cadastrar funcionários, reiniciar), e reporta seu status — tudo sem que seu servidor precise iniciar uma conexão.

Por que o modo Push vence

| Fator | Pull (SDK) | Push (Nuvem) |
|-------|-----------|--------------|
| Rede necessária | Mesma LAN | Apenas internet |
| IP do dispositivo | Estático obrigatório | Qualquer (DHCP OK) |
| Latência | 30s–5min de polling | Tempo real (<1s) |
| Apps na nuvem | ❌ Ponte local necessária | ✅ Nativo |
| Multi-sites | ❌ VPN por site | ✅ Tudo converge para um ponto |
| Escalabilidade | 1 thread por dispositivo | Baseado em eventos, sem polling |
| Firewall | Portas de entrada abertas | Apenas saída |

A parte difícil: construir um servidor de protocolo push

Aqui é onde a maioria das equipes empaca. O modo push é melhor, mas implementar o servidor que recebe os dados push é complexo. O dispositivo fala um protocolo proprietário. Você precisa:

- Analisar corretamente o handshake de conexão do dispositivo
- Gerenciar autenticação e registro de dispositivos
- Processar registros de ponto do formato bruto
- Enfileirar e entregar comandos aos dispositivos
- Gerenciar o estado de conexão de dezenas de dispositivos simultaneamente
- Lidar com reconexões, timeouts e deduplicação de dados

Isso não é um projeto de fim de semana. Construir um servidor de protocolo push para produção levou meses de trabalho da nossa equipe e milhares de horas de testes com 80+ dispositivos em campo.

A abordagem middleware: protocolo na entrada, API REST na saída

PunchConnect fica entre seus dispositivos e sua aplicação. Os dispositivos enviam dados para o motor de protocolo do PunchConnect. Você consome endpoints REST API e webhooks limpos. Você nunca toca no protocolo bruto.

Obtendo dados de ponto em tempo real (exemplos de código)

Uma vez que seu dispositivo está configurado no painel do PunchConnect (leva cerca de 5 minutos), você interage exclusivamente com a API REST:

Buscar registros de ponto

bash

# Obter os eventos de ponto de hoje
curl -X GET "https://api.punchconnect.com/v1/attendance?from=2026-03-27T00:00:00Z" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "Content-Type: application/json"

Python — Buscar e processar ponto

python

import requests
from datetime import datetime, timezone

API_KEY = "SUA_CHAVE_API"
BASE_URL = "https://api.punchconnect.com/v1"

def get_attendance(from_date: str = None):
    """Busca registros de ponto do PunchConnect."""
    params = {}
    if from_date:
        params["from"] = from_date

    response = requests.get(
        f"{BASE_URL}/attendance",
        headers={"Authorization": f"Bearer {API_KEY}"},
        params=params,
    )
    response.raise_for_status()
    return response.json()["data"]


def sincronizar_com_seu_sistema(records):
    """Envia os registros de ponto para seu sistema de RH."""
    for record in records:
        print(
            f"[{record['punch_time']}] "
            f"{record['employee_id']} — "
            f"{record['punch_type']} "
            f"({record['verify_mode']})"
        )


if __name__ == "__main__":
    today = datetime.now(timezone.utc).strftime("%Y-%m-%dT00:00:00Z")
    records = get_attendance(from_date=today)
    print(f"{len(records)} registros obtidos")
    sincronizar_com_seu_sistema(records)

JavaScript — Ouvir webhooks em tempo real

javascript

import express from "express";

const app = express();
app.use(express.json());

app.post("/webhook/attendance", (req, res) => {
  const event = req.body;

  console.log(`Novo ponto: ${event.employee_id} às ${event.punch_time}`);
  console.log(`  Tipo: ${event.punch_type} | Método: ${event.verify_mode}`);
  console.log(`  Dispositivo: ${event.device_serial}`);

  res.status(200).json({ received: true });
});

app.listen(3000, () => {
  console.log("Listener de webhook ouvindo na porta 3000");
});

Quais dispositivos ZKTeco suportam o modo push?

A maioria dos dispositivos ZKTeco modernos suportam o modo push. Qualquer dispositivo com firmware ZMM (a maioria dos fabricados após 2015) tem essa capacidade:

- Reconhecimento facial: SpeedFace V5L, SpeedFace-H5, ProFace X
- Impressão digital: UA860, K40, IN01-A, X7
- Multi-modal: SpeedFace V4L, MultiBio 800
- Controle de acesso: inBio 160/260, C3-100/200/400

Como verificar: Procure a configuração "Cloud Server" ou "ADMS Server" no menu de configuração de rede do seu dispositivo. Se estiver lá, seu dispositivo suporta modo push.

Modo push no Brasil: conformidade LGPD e CLT

Para implantações no Brasil, o modo push oferece vantagens importantes de conformidade:

- LGPD (Lei Geral de Proteção de Dados) — os dados biométricos transitam diretamente do dispositivo para a nuvem, sem servidor intermediário local que adicionaria um ponto de armazenamento extra sujeito às exigências da LGPD e da ANPD.
- Portaria 671 — o registro eletrônico de ponto precisa ser confiável e inviolável. O modo push em tempo real com PunchConnect fornece registros imediatos com timestamp do dispositivo, atendendo aos requisitos de integridade.
- CLT (Consolidação das Leis do Trabalho) — o controle de jornada é obrigatório para empresas com mais de 20 funcionários. O modo push garante que nenhum registro se perca, mesmo em caso de queda de internet.

Os modelos mais comuns no Brasil: ZKTeco K40 (relógio de ponto biométrico), SpeedFace V5L (facial), UA860 (digital + cartão). Todos suportam modo push.

Perguntas frequentes sobre o modo push

Preciso abrir portas no firewall para o modo push?

Não. O modo push usa conexões de saída do dispositivo, como um navegador web. Se seu dispositivo pode acessar a internet, ele pode enviar dados. Sem portas de entrada, sem IP estático, sem redirecionamento de portas.

Qual a latência real do modo push?

Menos de um segundo. Quando um funcionário bate o ponto no dispositivo, o evento chega ao PunchConnect e ativa seu webhook em menos de um segundo. Comparado com o polling SDK (30 segundos a 5 minutos), o modo push é praticamente instantâneo.

O que acontece se a internet cair?

O dispositivo armazena localmente. Os dispositivos ZKTeco guardam registros na memória interna (geralmente 50.000 a 100.000 registros). Quando a conectividade retorna, o dispositivo envia automaticamente todos os registros em buffer. O PunchConnect faz a deduplicação para que você nunca receba registros duplicados.

É possível enviar comandos para o dispositivo no modo push?

Sim. O PunchConnect enfileira os comandos (cadastrar funcionários, sincronizar hora, reiniciar, atualizar configurações) e os entrega ao dispositivo no próximo ciclo push. Você envia comandos pela API REST, o PunchConnect cuida da entrega.

O modo push é compatível com todos os modelos ZKTeco?

O modo push funciona com qualquer dispositivo ZKTeco que tenha a configuração "Cloud Server" ou "ADMS Server" — a grande maioria dos dispositivos fabricados após 2015. Dispositivos mais antigos (pré-2015) suportam apenas o modo pull, mas estão cada vez mais raros em implantações ativas.

Para começar

Se você está construindo uma integração biométrica e decidindo entre push e pull:

1. Comece com o modo push. É a arquitetura certa para qualquer aplicação na nuvem.
2. Não construa o servidor de protocolo sozinho — a menos que tenha meses de sobra e experiência profunda com protocolos ZKTeco.
3. Teste o PunchConnect grátis por 7 dias — cadastre seu dispositivo, obtenha sua chave API, e receba seu primeiro webhook de ponto em menos de 15 minutos. Sem cartão de crédito.

Se você já usa uma biblioteca SDK e está com problemas de escalabilidade, leia nossa comparação: Por que bibliotecas open-source ZKTeco não escalam. E se seu maior bloqueio é o IP estático, veja Ponto biométrico sem IP estático.

---

*PunchConnect é um middleware comprovado em produção que conecta dispositivos biométricos ZKTeco a qualquer sistema de software. Atualmente gerencia o ponto de 24.000+ funcionários em 50+ locais.*