Integration

Ponto biométrico em tempo real no seu ERP: Webhooks, middleware e 20 linhas de código

Envie registros de ponto biométrico para Odoo, SAP, ERPNext ou seu HRMS próprio em tempo real. Sem polling, sem imports CSV. Um webhook, uma função serverless e 20 linhas de código.

PunchConnect Team·Mar 28, 2026·9 min read

Introduction

Seus dispositivos biométricos coletam registros de ponto. Seu ERP calcula a folha de pagamento. Entre esses dois sistemas existe uma lacuna que custa às empresas horas de digitação manual toda semana. Algumas equipes de TI exportam CSV à meia-noite. Outras rodam crons que consultam os relógios de ponto a cada 5 minutos. Algumas desistiram e contrataram alguém para digitar os registros de ponto manualmente.

Nada disso é necessário. Com um webhook e uma função middleware de 20 linhas, cada batida chega no seu ERP no momento em que o dedo toca o leitor.

Este guia mostra exatamente como — com código pronto para produção para Odoo, SAP, ERPNext e sistemas HRMS próprios.

Por que imports batch estão prejudicando a precisão da sua folha

A abordagem tradicional: exportar dados de ponto do software do dispositivo, salvar como CSV, fazer upload no ERP, torcer para que o mapeamento não tenha quebrado nada. Equipes fazem isso diariamente, às vezes duas vezes por dia.

Os problemas se acumulam rápido:

- Atraso nos dados. Uma batida às 8:47 pode não chegar ao ERP até o batch da meia-noite. Cálculos de hora extra estão sempre um dia atrasados.
- Registros perdidos. Dispositivo fica offline durante a janela de exportação? Essas batidas desaparecem. Você descobre a falha quando a folha já foi processada.
- Erros manuais. Alguém mapeia o ID do funcionário 1042 para o registro errado no Odoo. Um mapeamento errado cascateia em contracheques incorretos.
- Sem trilha de auditoria. Quando aquela batida realmente chegou no ERP? Ninguém sabe.

A integração em tempo real elimina os quatro problemas. Cada batida chega no ERP em segundos, com um carimbo temporal verificável e uma trilha de auditoria limpa.

A arquitetura: Dispositivo → PunchConnect → Middleware → ERP

O padrão de integração é o mesmo independente do ERP:

1. O dispositivo biométrico registra uma batida (impressão digital, face, RFID)
2. PunchConnect recebe o evento e envia como webhook para seu endpoint
3. Seu middleware (função serverless ou servidor leve) recebe o webhook
4. O middleware mapeia e grava o registro de ponto na API do seu ERP

O middleware é onde a mágica acontece. Tipicamente são 20-50 linhas de código — um handler HTTP simples que transforma o payload do webhook PunchConnect no formato de ponto do seu ERP.

O payload webhook que você vai receber

Cada evento de ponto chega como JSON POST na sua URL webhook configurada:

O event_id é sua chave de idempotência — use-o para deduplicar em caso de retentativas.

json

{
  "event": "attendance.punch",
  "device_serial": "CZKE2241600045",
  "employee_id": "1042",
  "timestamp": "2026-03-28T08:47:12-03:00",
  "direction": "in",
  "method": "fingerprint",
  "event_id": "evt_a8f3k2x9m1"
}

Integração #1: Odoo (JSON-RPC)

Odoo usa JSON-RPC para sua API. Aqui está um middleware completo — muito usado por integradores no Brasil e em Portugal:

Faça deploy no Railway, DigitalOcean ou qualquer plataforma serverless. Nossos clientes no Brasil colocaram isso pra funcionar em menos de uma hora.

> Dica: Mapeie employee_id do PunchConnect para o campo barcode de hr.employee no Odoo. É o mapeamento mais limpo — sem campos customizados.

python

# odoo_middleware.py — PunchConnect → Odoo ponto
import xmlrpc.client
from flask import Flask, request, jsonify

app = Flask(__name__)

ODOO_URL = "https://seu-odoo.com"
ODOO_DB = "sua-base"
ODOO_USER = "admin"
ODOO_PASS = "sua-api-key"

models = xmlrpc.client.ServerProxy(f"{ODOO_URL}/xmlrpc/2/object")
uid = xmlrpc.client.ServerProxy(f"{ODOO_URL}/xmlrpc/2/common").authenticate(
    ODOO_DB, ODOO_USER, ODOO_PASS, {}
)

@app.route("/webhook", methods=["POST"])
def handle_punch():
    data = request.json

    employee = models.execute_kw(
        ODOO_DB, uid, ODOO_PASS,
        "hr.employee", "search_read",
        [[["barcode", "=", data["employee_id"]]]],
        {"fields": ["id"], "limit": 1}
    )

    if not employee:
        return jsonify({"error": "funcionário não encontrado"}), 404

    if data["direction"] == "in":
        models.execute_kw(
            ODOO_DB, uid, ODOO_PASS,
            "hr.attendance", "create",
            [{"employee_id": employee[0]["id"],
              "check_in": data["timestamp"]}]
        )
    else:
        open_att = models.execute_kw(
            ODOO_DB, uid, ODOO_PASS,
            "hr.attendance", "search",
            [[["employee_id", "=", employee[0]["id"]],
              ["check_out", "=", False]]],
            {"limit": 1}
        )
        if open_att:
            models.execute_kw(
                ODOO_DB, uid, ODOO_PASS,
                "hr.attendance", "write",
                [open_att, {"check_out": data["timestamp"]}]
            )

    return jsonify({"status": "ok"}), 200

Integração #2: SAP (OData / RFC)

Integrações SAP seguem o mesmo padrão mas usam a API OData ou chamadas RFC do SAP:

Para SAP on-premise: Use SAP Cloud Integration (CPI) como camada middleware. CPI pode receber webhooks PunchConnect via HTTPS e rotear para seu SAP on-premise via Cloud Connector.

> Conformidade Portaria 671 e CLT: A Portaria 671 do MTP regulamenta o REP-P (Registrador Eletrônico de Ponto por Programa). Com PunchConnect, cada batida fica registrada com carimbo temporal exato, método de verificação e dispositivo — documentação pronta para fiscalização do MTE. A CLT (Art. 74, §2º) exige controle de jornada para empresas com mais de 20 funcionários. A LGPD (Art. 11) classifica dados biométricos como sensíveis — PunchConnect envia apenas ID do funcionário e timestamp, nunca templates biométricos.

python

# sap_middleware.py — PunchConnect → SAP SuccessFactors
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

SAP_BASE = "https://api.successfactors.com"
SAP_COMPANY = "seuCompanyId"
SAP_USER = "api-user"
SAP_PASS = "api-password"

@app.route("/webhook", methods=["POST"])
def handle_punch():
    data = request.json

    payload = {
        "userId": data["employee_id"],
        "eventDate": data["timestamp"][:10],
        "eventTime": data["timestamp"][11:19].replace(":", ""),
        "eventType": "P10" if data["direction"] == "in" else "P20",
        "terminalId": data["device_serial"]
    }

    response = requests.post(
        f"{SAP_BASE}/odata/v2/EmployeeTime",
        json=payload,
        auth=(f"{SAP_USER}@{SAP_COMPANY}", SAP_PASS),
        headers={"Content-Type": "application/json"}
    )

    if response.status_code in (200, 201):
        return jsonify({"status": "ok"}), 200
    return jsonify({"error": response.text}), 500

Integração #3: ERPNext (REST API)

ERPNext tem uma API REST limpa que torna esta integração direta:

> Dica ERPNext: Use o doctype Employee Checkin — ele tem auto-frequência integrada que calcula registros de Attendance a partir dos checkins. Não escreva diretamente em Attendance.

javascript

// erpnext_middleware.js — PunchConnect → ERPNext
const express = require("express");
const axios = require("axios");
const app = express();

app.use(express.json());

const ERPNEXT_URL = "https://seu-site.erpnext.com";
const API_KEY = "sua-api-key";
const API_SECRET = "seu-api-secret";

const erpnext = axios.create({
  baseURL: ERPNEXT_URL,
  headers: {
    Authorization: `token ${API_KEY}:${API_SECRET}`,
    "Content-Type": "application/json",
  },
});

app.post("/webhook", async (req, res) => {
  const { employee_id, timestamp, direction, event_id } = req.body;

  try {
    const { data: empList } = await erpnext.get(
      `/api/resource/Employee?filters=[["attendance_device_id","=","${employee_id}"]]&fields=["name"]`
    );

    if (!empList.data.length) {
      return res.status(404).json({ error: "funcionário não encontrado" });
    }

    const employeeName = empList.data[0].name;

    await erpnext.post("/api/resource/Employee Checkin", {
      employee: employeeName,
      time: timestamp,
      device_id: event_id,
      log_type: direction === "in" ? "IN" : "OUT",
    });

    res.json({ status: "ok" });
  } catch (err) {
    console.error("Erro ERPNext:", err.response?.data || err.message);
    res.status(500).json({ error: "falha gravação ERP" });
  }
});

app.listen(3000);

Integração #4: HRMS próprio (banco de dados direto)

Se você desenvolveu seu próprio HRMS, a integração é ainda mais simples:

python

# custom_middleware.py — PunchConnect → HRMS próprio
from flask import Flask, request, jsonify
import psycopg2
import os

app = Flask(__name__)

conn = psycopg2.connect(os.environ["DATABASE_URL"])

@app.route("/webhook", methods=["POST"])
def handle_punch():
    data = request.json

    with conn.cursor() as cur:
        cur.execute(
            "SELECT 1 FROM attendance_events WHERE event_id = %s",
            (data["event_id"],)
        )
        if cur.fetchone():
            return jsonify({"status": "duplicado"}), 200

        cur.execute(
            """INSERT INTO attendance_events
               (event_id, employee_id, punch_time, direction, device_serial, method)
               VALUES (%s, %s, %s, %s, %s, %s)""",
            (data["event_id"], data["employee_id"],
             data["timestamp"], data["direction"],
             data["device_serial"], data["method"])
        )
        conn.commit()

    return jsonify({"status": "ok"}), 200

Tratamento de casos extremos

Dispositivos offline: Quando um dispositivo fica offline, ele armazena as batidas localmente. Uma vez reconectado, PunchConnect entrega os eventos em ordem. Os carimbos temporais são da batida original, não da entrega.

Batidas duplas: Funcionários às vezes batem ponto duas vezes por acidente. Seu ERP deve tratar isso na lógica de negócio — por exemplo, ignorar um segundo check-in dentro de 60 segundos do primeiro.

Diferenças de fuso horário: PunchConnect entrega carimbos temporais em UTC. Converta para seu fuso local no middleware antes de gravar no ERP. No Brasil, atenção especial com os fusos (BRT -3, AMT -4, ACT -5).

Direção faltante: Alguns dispositivos antigos não informam a direção da batida. PunchConnect marca esses como direction: "unknown". Seu middleware deve inferir a direção do contexto.

FAQ

Quão rápido as batidas chegam no meu ERP?

Sub-segundo a partir do momento que PunchConnect recebe o evento. A latência total do dedo no leitor ao registro no ERP é tipicamente menos de 3 segundos.

O que acontece se meu middleware estiver fora do ar?

PunchConnect retenta com backoff exponencial por 72 horas. Quando seu middleware volta a ficar online, recebe todos os eventos em buffer na ordem. Nenhum dado é perdido.

Preciso de IP fixo para o endpoint webhook?

Não. PunchConnect entrega webhooks para qualquer URL HTTPS — funções serverless, plataformas cloud ou túneis como ngrok para desenvolvimento. Veja nosso guia sobre ponto biométrico sem IP fixo.

Posso integrar com múltiplos ERPs simultaneamente?

Sim. Registre múltiplas URLs webhook no PunchConnect e cada uma receberá cada evento independentemente.

Como gerencio 50+ dispositivos em múltiplas filiais?

O middleware não se importa com quantos dispositivos você tem — cada batida segue o mesmo caminho webhook → middleware → ERP. Veja nosso guia de gestão multi-filial.

---

Pronto para conectar seus dispositivos biométricos ao seu ERP? PunchConnect te dá uma API REST e webhooks prontos para usar. Comece seu teste gratuito de 7 dias — sem cartão de crédito. A maioria das equipes tem sua primeira integração funcionando em menos de uma hora.

*Já usa PunchConnect? Confira nosso guia de configuração webhook para configuração avançada, ou veja como a AgriWise integrou 24.000+ funcionários em 50+ filiais.*

Ponto biométrico em tempo real no seu ERP: Webhooks, middleware e 20 linhas de código

Introduction

Por que imports batch estão prejudicando a precisão da sua folha

A arquitetura: Dispositivo → PunchConnect → Middleware → ERP

O payload webhook que você vai receber

Integração #1: Odoo (JSON-RPC)

Integração #2: SAP (OData / RFC)

Integração #3: ERPNext (REST API)

Integração #4: HRMS próprio (banco de dados direto)

Tratamento de casos extremos

FAQ

Quão rápido as batidas chegam no meu ERP?

O que acontece se meu middleware estiver fora do ar?

Preciso de IP fixo para o endpoint webhook?

Posso integrar com múltiplos ERPs simultaneamente?

Como gerencio 50+ dispositivos em múltiplas filiais?

Artigos relacionados

Como Conectar ZKTeco ao Odoo: Integração via API Cloud (Sem VPN, Sem Software Local)

Controle de Ponto Biométrico Sem IP Fixo: Como a API na Nuvem Resolve o Maior Problema das Empresas Brasileiras

Alternativa CAMS Biometria com API Callback: Webhook em Tempo Real para Controle de Ponto