Controle de Ponto Biométrico para ERPNext: Guia Completo de Integração

Por Que o Controle de Ponto Biométrico no ERPNext Falha em Escala

Você tem leitores de impressão digital ZKTeco nos seus escritórios e o ERPNext gerenciando RH. A ferramenta oficial Frappe Biometric Attendance Sync Tool usa pyzk para consultar os dispositivos pela rede local. Um escritório, um dispositivo, uma rede — funciona.

Adicione uma segunda unidade e tudo desmorona.

pyzk requer um script Python rodando na mesma rede local de cada dispositivo. Se o ERPNext roda no Frappe Cloud, não dá para instalar pyzk nos servidores deles. Se você tem filiais, cada uma precisa da sua própria máquina de sincronização. Se um dispositivo muda de IP via DHCP, a conexão quebra silenciosamente — e você descobre quando a folha de pagamento roda com registros faltando.

PunchConnect elimina toda essa arquitetura. Os dispositivos enviam dados de ponto para uma API na nuvem. O ERPNext recebe via webhook em tempo real. Sem scripts locais. Sem dependência de rede. Sem cron jobs consultando dados desatualizados.

Este guia cobre a integração completa: configuração do dispositivo, receptor webhook, mapeamento de funcionários, ponto automático e hardening para produção. Cada bloco de código está pronto para copiar e colar.

Arquitetura: Como a Integração Funciona

A abordagem tradicional com pyzk e a abordagem PunchConnect resolvem o mesmo problema de formas diferentes:

Tradicional (pyzk):

- Rede compartilhada obrigatória
- Atraso de 10 a 30 minutos
- Não escala entre unidades

PunchConnect (webhook na nuvem):

- Funciona de qualquer rede
- Tempo real (1 a 3 segundos)
- Um único endpoint para todas as unidades

O dispositivo envia as marcações para a infraestrutura cloud do PunchConnect. O PunchConnect normaliza os dados entre versões de firmware e encaminha como um webhook JSON limpo para sua instância ERPNext. O ERPNext cria um registro Employee Checkin, e o módulo Auto Attendance integrado converte os checkins em registros de frequência automaticamente.

Sem servidor intermediário. Sem túneis VPN. Sem infraestrutura por unidade.

Dispositivo → [LAN] → script pyzk → [cron] → API ERPNext → Employee Checkin

Pré-requisitos

Antes de começar:

- ERPNext v14+ ou v15+ com o app HRMS instalado
- Um dispositivo ZKTeco com conectividade cloud (SpeedFace V5L, ProFace X, uFace 800, MB460, iClock 680, série K, ou similar)
- Uma conta PunchConnect — teste gratuito de 7 dias, sem cartão de crédito
- HTTPS na sua instância ERPNext — webhooks exigem certificado SSL válido

Passo 1: Criar sua Conta PunchConnect e Registrar um Dispositivo

Cadastre-se em punchconnect.com/signup. Após verificar o email, você acessa o painel.

Clique em Add Device e insira o número de série do seu dispositivo. O PunchConnect gera uma configuração cloud — aplique-a pelo painel do PunchConnect. O processo inteiro leva cerca de 5 minutos por dispositivo.

Após configurado, o dispositivo aparece como "Online" no painel em menos de 60 segundos.

Múltiplas unidades? Registre todos os dispositivos em uma única conta. O PunchConnect gerencia mais de 50 unidades e centenas de dispositivos a partir de um único painel. Cada dispositivo é identificado pelo número de série, organizável por localização.

Passo 2: Construir o Receptor Webhook no ERPNext

O PunchConnect envia uma requisição POST para sua instância ERPNext cada vez que alguém registra o ponto. Você precisa de um método API autorizado para recebê-la.

Opção A: Instalação Rápida com o App PunchConnect ERPNext

Instale o app oficial PunchConnect para ERPNext para configuração sem código:

Após a instalação:

1. Vá em PunchConnect Settings → insira sua chave API e segredo do webhook
2. Clique em Test Connection para verificar
3. No painel do PunchConnect, adicione a URL do webhook:

O app cuida de tudo: verificação de assinatura HMAC, detecção de duplicatas, mapeamento de funcionários, logs de sincronização e painel de monitoramento.

# Do diretório bench
bench get-app https://github.com/punchconnect/erpnext-punchconnect.git
bench --site seu-site.local install-app punchconnect
bench --site seu-site.local migrate

Opção B: Receptor Webhook Personalizado (Controle Total)

Se preferir criar seu próprio receptor, adicione um método API no seu app Frappe personalizado:

Adicione o segredo no site_config.json:

# seu_app/api.py
import frappe
import hmac
import hashlib
from frappe import _

WEBHOOK_SECRET = frappe.conf.get("punchconnect_webhook_secret", "")

@frappe.whitelist(allow_guest=True)
def punchconnect_webhook():
    """Recebe eventos de ponto do PunchConnect."""

    # 1. Verificar assinatura HMAC
    payload = frappe.request.data
    signature = frappe.request.headers.get("X-PunchConnect-Signature", "")
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        frappe.throw(_("Assinatura webhook inválida"), frappe.AuthenticationError)

    # 2. Parsear o evento
    data = frappe.parse_json(payload)
    event_type = data.get("event")

    if event_type != "attendance":
        return {"status": "ok", "message": f"Evento {event_type} registrado"}

    # 3. Encontrar o funcionário pelo ID do dispositivo
    device_user_id = str(data.get("user_id"))
    employee = frappe.db.get_value(
        "Employee",
        {"attendance_device_id": device_user_id, "status": "Active"},
        ["name", "employee_name", "company"],
        as_dict=True
    )

    if not employee:
        frappe.log_error(
            f"Nenhum funcionário encontrado para ID do dispositivo: {device_user_id}",
            "PunchConnect Webhook"
        )
        return {"status": "error", "message": "Funcionário não encontrado"}

    # 4. Verificar duplicatas
    timestamp = data.get("timestamp")
    existing = frappe.db.exists("Employee Checkin", {
        "employee": employee.name,
        "time": timestamp
    })

    if existing:
        return {"status": "ok", "message": "Duplicata, ignorada"}

    # 5. Criar Employee Checkin
    checkin = frappe.get_doc({
        "doctype": "Employee Checkin",
        "employee": employee.name,
        "employee_name": employee.employee_name,
        "time": timestamp,
        "device_id": data.get("device_serial"),
        "log_type": map_punch_direction(data.get("punch_direction"))
    })
    checkin.insert(ignore_permissions=True)
    frappe.db.commit()

    return {
        "status": "ok",
        "checkin": checkin.name,
        "employee": employee.employee_name
    }


def map_punch_direction(direction):
    """Converter direção PunchConnect para tipo de log ERPNext."""
    mapping = {
        "IN": "IN",
        "OUT": "OUT",
        "0": "IN",
        "1": "OUT",
    }
    return mapping.get(str(direction).upper(), "")

Passo 3: Mapear Funcionários aos IDs dos Dispositivos

Cada funcionário que usa um dispositivo biométrico precisa ter o attendance_device_id configurado. Este campo vincula o ID de usuário no dispositivo ao registro Employee no ERPNext.

Mapeamento Manual

1. Abra o doctype Employee
2. Vá em Attendance and Leave Details
3. Configure Attendance Device ID com o ID de usuário no dispositivo

Mapeamento em Massa via Importação de Dados

Para organizações com centenas de funcionários:

Faça upload em Configurações → Importação de dados → Employee (atualizar registros existentes).

name,attendance_device_id
HR-EMP-00001,101
HR-EMP-00002,102
HR-EMP-00003,103

Mapeamento por API

Automatize o mapeamento com um script que busca usuários no PunchConnect:

import requests
import frappe

API_KEY = "sua_chave_api_punchconnect"

def sync_employee_ids():
    """Busca usuários do dispositivo no PunchConnect e mapeia para funcionários ERPNext."""
    response = requests.get(
        "https://api.punchconnect.com/v1/users",
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    device_users = response.json()["data"]

    for user in device_users:
        employee = frappe.db.get_value(
            "Employee",
            {"employee_name": user["name"], "status": "Active"},
            "name"
        )
        if employee:
            frappe.db.set_value(
                "Employee", employee,
                "attendance_device_id", str(user["user_id"])
            )

    frappe.db.commit()
    print(f"{len(device_users)} usuários mapeados para funcionários")

Passo 4: Configurar a Frequência Automática

O ERPNext v14+ inclui Auto Attendance — converte automaticamente os registros Employee Checkin em registros de Frequência.

Ativar Auto Attendance

1. Vá em HR Settings → ative Auto Attendance
2. Navegue até Shift Type → crie ou edite um tipo de turno
3. Configure os horários:

4. Atribua turnos aos funcionários: vá em Shift Assignment → crie as atribuições

Nome do turno: Turno Manhã
Hora de início: 08:00
Hora de fim: 17:00
Enable Auto Attendance: ✓
Determine Check-in and Check-out: Alternating
Working Hours Threshold for Half Day: 4
Working Hours Threshold for Absent: 2

O Pipeline Completo em Ação

# 08:02 → O dispositivo captura a impressão digital (User ID: 101)
# 08:02 → PunchConnect recebe a marcação
# 08:03 → O webhook dispara para o ERPNext (1-3 segundos)
# 08:03 → Employee Checkin criado (HR-EMP-00001, IN, 08:02)
# ...
# 17:05 → O mesmo funcionário registra saída
# 17:05 → Employee Checkin criado (HR-EMP-00001, OUT, 17:05)
# ...
# Auto Attendance executa → Registro de frequência: Presente, 9h03 trabalhadas

Passo 5: Monitorar e Solucionar Problemas

Problemas Comuns e Soluções

Employee Checkin não foi criado?
- Verifique se o attendance_device_id do funcionário corresponde ao ID do dispositivo
- Confira os PunchConnect Sync Logs para a mensagem de erro
- Ative "Log Raw Payloads" nas configurações do PunchConnect

Webhook retornando 401 ou 403?
- Confirme que o segredo do webhook é idêntico no PunchConnect e no ERPNext
- Verifique se o método API tem allow_guest=True
- Confira se o certificado SSL é válido

Auto Attendance não está criando registros?
- Confirme que Auto Attendance está ativado em HR Settings
- Verifique se os funcionários têm Shift Assignments para o período correto
- Confira o Scheduled Job Type para process_auto_attendance

Modelos de Implantação

Frappe Cloud

Não é possível instalar pyzk nos servidores do Frappe Cloud. Os webhooks do PunchConnect são a única via viável para integração biométrica.

Auto-hospedado / Docker

Você poderia usar pyzk, mas o PunchConnect é mais rápido de implantar e mais confiável. Sem cron jobs, sem rastreamento de IPs, sem problemas de compatibilidade de firmware.

Organizações Multi-Unidade

É aqui que o PunchConnect entrega mais valor. 100 dispositivos em 20 escritórios? Uma única conta PunchConnect, um único endpoint webhook, uma única instância ERPNext. Sem infraestrutura por unidade.

Atualmente em produção com 24.000+ funcionários ativos em mais de 50 unidades. Leia o caso de sucesso AgriWise.

Segurança e Conformidade com a LGPD

Dispositivo → PunchConnect: conexão criptografada com TLS. Os dispositivos se autenticam com seu número de série registrado.

PunchConnect → ERPNext: HTTPS com verificação de assinatura HMAC-SHA256. Cada webhook inclui um cabeçalho X-PunchConnect-Signature.

Dados em repouso: O PunchConnect processa os eventos em tempo real e os encaminha. Não armazena templates biométricos (impressões digitais, dados faciais). Apenas metadados — ID do usuário, timestamp, número de série — transitam pela API.

Conformidade com a LGPD (Lei Geral de Proteção de Dados): O PunchConnect minimiza os dados pessoais que transitam pela nuvem. Dados biométricos brutos nunca saem do dispositivo — apenas identificadores numéricos são transmitidos. Isso facilita a adequação à LGPD para empresas brasileiras que precisam de controle de ponto biométrico. Recomendamos documentar essa integração no seu Relatório de Impacto à Proteção de Dados Pessoais (RIPD).

Para mais detalhes sobre segurança de dados biométricos, leia nosso guia sobre proteção de dados biométricos em trânsito.

Preços

US$ 200 por dispositivo — licença única. Sem mensalidades. Sem cobrança por funcionário.

Compare com o custo oculto da infraestrutura pyzk: servidor de sincronização por unidade, configuração VPN, tempo de desenvolvedor para depurar firmware, e manutenção contínua.

Conformidade com a CLT: O controle de ponto eletrônico é obrigatório para empresas com mais de 20 funcionários no Brasil (Portaria 671). O PunchConnect gera registros auditáveis que atendem às exigências da legislação trabalhista.

Inicie seu teste gratuito de 7 dias — sem cartão de crédito.

Perguntas Frequentes

O controle de ponto biométrico para ERPNext funciona com Frappe Cloud?
Sim. O PunchConnect envia dados via webhook para um endpoint API Frappe padrão. Nenhuma instalação nos servidores do Frappe Cloud é necessária.

Quais dispositivos ZKTeco são compatíveis?
Qualquer modelo com conectividade cloud: SpeedFace V5L, ProFace X, uFace 800, MB460, iClock 680, série K, e mais. Entre em contato para verificar seu modelo.

Qual a velocidade de transmissão dos dados para o ERPNext?
1 a 3 segundos via webhook. Compare com 10 a 30 minutos do polling com cron do pyzk.

Posso usar o PunchConnect junto com a ferramenta de sincronização Frappe existente?
Sim. Ambos criam documentos Employee Checkin. Execute ambos em paralelo durante a migração, depois desative o script cron.

O que acontece se o ERPNext estiver temporariamente fora do ar?
O PunchConnect retenta as entregas de webhook com backoff exponencial. Nenhum dado de ponto é perdido.

Preciso de IP fixo no meu servidor ERPNext?
Não. Você precisa de um nome de domínio com certificado SSL válido. O PunchConnect envia webhooks para sua URL — o DNS cuida do resto.

O PunchConnect atende à Portaria 671 para controle de ponto eletrônico?
O PunchConnect gera registros de Employee Checkin com timestamp preciso e identificação do dispositivo, criando uma trilha de auditoria completa. Combinado com o módulo de Attendance do ERPNext, você tem os registros necessários para conformidade com a legislação trabalhista brasileira.

---

Pronto para conectar seus dispositivos biométricos ao ERPNext? Inicie seu teste gratuito de 7 dias — registre seu primeiro dispositivo, configure o webhook, e veja Employee Checkins em tempo real no ERPNext em 30 minutos.

Dúvidas? Entre em contato — temos experiência com todos os modelos de implantação ERPNext e todas as variantes de firmware ZKTeco.