Engineering

Projetando uma API de Ponto Biométrico Que Desenvolvedores Realmente Querem Usar

A maioria das APIs biométricas são remendos sobre SDKs de hardware. Veja como projetamos a API REST do PunchConnect a partir de princípios fundamentais — com webhooks, idempotência e entrega em tempo real que desenvolvedores esperam de infraestrutura moderna.

PunchConnect Team·Mar 28, 2026·10 min read

Introduction

Você construiu um sistema de folha de pagamento. A folha depende dos dados de frequência. Agora você precisa capturar os eventos de ponto de 200 dispositivos biométricos no seu sistema — de forma confiável, em tempo real, sem perder um único registro. Esse é o problema de design de API de que ninguém fala até estar depurando batidas perdidas às 2 da manhã.

A maioria das "APIs" biométricas são SDKs de fabricante disfarçados de REST. Expõem registros brutos do dispositivo, exigem loops de polling e quebram quando um relógio de ponto se desconecta por 30 segundos. Não foram projetadas para aplicações cloud-native.

Quando construímos a API do PunchConnect, começamos do outro lado: o que um desenvolvedor construindo uma integração ERP esperaria? A resposta se parecia muito com Stripe, Twilio e GitHub — não com um manual de hardware.

Três Princípios de Design Emprestados dos Melhores

Estudamos as APIs que desenvolvedores realmente gostam de usar. Três padrões apareciam repetidamente:

1. Ser previsível. Cada endpoint segue a mesma convenção de nomenclatura. Cada resposta tem a mesma estrutura. Cada erro retorna um objeto estruturado com code legível por máquina e message legível por humanos. Sem surpresas.

2. Ser tempo real. Webhooks para eventos, não polling. Quando um funcionário bate o ponto na porta, sua aplicação sabe em segundos — não quando seu cron job executa.

3. Ser resiliente. Cada operação mutante aceita uma chave de idempotência. Cada entrega webhook é retentada com backoff exponencial. Cada dado pode ser reproduzido sem duplicatas.

O Pipeline de Entrega de Webhooks

A parte mais difícil de uma API de ponto biométrico não são os endpoints REST — é garantir a entrega dos eventos quando o mundo real é instável. Dispositivos se desconectam. Redes caem. Servidores reiniciam durante deploys.

PunchConnect garante entrega ao-menos-uma-vez para cada evento webhook:

1. O funcionário bate ponto no dispositivo biométrico (impressão digital, rosto, cartão)
2. O evento é persistido em uma fila durável — seguro mesmo se o sistema reiniciar
3. O worker de entrega envia um HTTP POST para sua URL de callback registrada
4. Seu servidor responde com 2xx → evento marcado como entregue
5. Se a entrega falha (5xx, timeout, erro de rede) → retries com backoff exponencial por 72 horas
6. Após esgotar retries → evento marcado como falhou, notificação email enviada

Payload do Webhook

Cada webhook entrega um objeto JSON limpo e normalizado:

json

{
  "event_id": "evt_a1b2c3d4e5f6",
  "event_type": "attendance.punch",
  "timestamp": "2026-03-28T08:01:23Z",
  "device": {
    "id": "dev_9x8y7z",
    "serial_number": "BKRK233600045",
    "name": "Entrada Principal",
    "site": "Matriz"
  },
  "employee": {
    "id": "emp_4k5l6m",
    "badge_number": "1042",
    "name": "Sarah Chen"
  },
  "punch": {
    "direction": "in",
    "method": "fingerprint",
    "confidence": 0.97,
    "local_time": "2026-03-28T09:01:23-03:00"
  },
  "metadata": {
    "deduplicated": false,
    "delivery_attempt": 1
  }
}

Receber Webhooks na Sua Aplicação

Python (Flask)

python

import hmac
import hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)
WEBHOOK_SECRET = "whsec_seu_segredo_de_assinatura"

def verify_signature(payload, signature):
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

@app.route("/webhooks/attendance", methods=["POST"])
def handle_attendance():
    signature = request.headers.get("X-PunchConnect-Signature")
    if not verify_signature(request.data, signature):
        return jsonify({"error": "Assinatura inválida"}), 401

    event = request.json
    if event["event_type"] == "attendance.punch":
        employee = event["employee"]["badge_number"]
        direction = event["punch"]["direction"]
        timestamp = event["timestamp"]
        print(f"Funcionário {employee} bateu ponto {direction} às {timestamp}")

    return jsonify({"received": True}), 200

Node.js (Express)

javascript

const express = require('express');
const crypto = require('crypto');
const app = express();

const WEBHOOK_SECRET = 'whsec_seu_segredo_de_assinatura';

app.post('/webhooks/attendance', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-punchconnect-signature'];
  const expected = `sha256=${crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex')}`;

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).json({ error: 'Assinatura inválida' });
  }

  const event = JSON.parse(req.body);
  if (event.event_type === 'attendance.punch') {
    const { badge_number } = event.employee;
    const { direction } = event.punch;
    console.log(`Funcionário ${badge_number} bateu ponto ${direction} às ${event.timestamp}`);
  }

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

app.listen(3000, () => console.log('Listener webhook ativo na :3000'));

cURL — Registrar Seu Webhook

bash

curl -X POST https://api.punchconnect.com/v1/webhooks \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seu-app.com/webhooks/attendance",
    "events": ["attendance.punch", "device.status"],
    "secret": "whsec_seu_segredo_de_assinatura"
  }'

Idempotência: Cada Comando É Seguro para Retentar

Falhas de rede acontecem. Sua requisição expira. O dispositivo recebeu o comando ou não? Sem idempotência, você está adivinhando.

PunchConnect aceita um header Idempotency-Key em cada endpoint mutante:

Isso é crítico para comandos de dispositivo — sincronização de listas de funcionários, atualização de regras de acesso. Sem idempotência, um simples retry poderia cadastrar funcionários duas vezes.

bash

curl -X POST https://api.punchconnect.com/v1/devices/dev_9x8y7z/commands \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "Idempotency-Key: sync-funcionarios-2026-03-28-001" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "sync_employees",
    "payload": {
      "employees": [
        {"badge_number": "1042", "name": "Sarah Chen"},
        {"badge_number": "1043", "name": "James Okoro"}
      ]
    }
  }'

Rate Limiting Transparente

Cada resposta inclui headers de rate limit:

Quando você atinge o limite, recebe um 429 Too Many Requests com header Retry-After. Limites por padrão: 1.000 chamadas REST por dispositivo por dia. Webhooks entrantes (dispositivo → PunchConnect) são ilimitados.

Conformidade LGPD: Todos os dados transitam em HTTPS. Os webhooks suportam verificação HMAC-SHA256. Os dados de ponto podem ser excluídos via API conforme o direito à eliminação da LGPD (Lei 13.709/2018). PunchConnect é compatível com a Portaria 671 do MTP para registro eletrônico de ponto (REP-P) e com os requisitos de registro de jornada da CLT. Funciona com qualquer provedor de nuvem brasileiro ou internacional.

text

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1711584000

Normalização dos Dados

Dados de dispositivos biométricos são bagunçados: batidas duplicadas, timestamps desalinhados, registros corrompidos. PunchConnect normaliza tudo:

- Detecção de duplicatas — Mesmo funcionário, mesmo dispositivo em janela configurável (padrão: 60 seg) → filtrado
- Normalização de timestamps — Reconciliação relógio dispositivo/servidor, entrega em UTC
- Inferência de direção — Regras configuráveis (primeira batida = entrada, última = saída, ou alternância)
- Filtro de dados inválidos — Registros malformados, timestamps zero, crachás não cadastrados → capturados e logados

O Que 24.000+ Funcionários Nos Ensinaram

Rodar PunchConnect em 50+ sites para os 24.000+ funcionários da AgriWise nos ensinou coisas que nenhuma teoria de design de API poderia:

Drift de relógio é real. Dispositivos em fusos horários e redes instáveis desalinham. Normalização UTC não é opcional.

Buffering offline é obrigatório. Sites agrícolas rurais perdem internet por horas. Os relógios de ponto armazenam batidas localmente. Quando a conectividade volta, tudo é processado em ordem.

Operações batch importam. Sincronizar 5.000 funcionários em 50 dispositivos exige endpoints batch com acompanhamento de progresso e tratamento de falhas parciais.

Perguntas Frequentes

Qual a velocidade de entrega dos webhooks?
Geralmente menos de 2 segundos entre a batida de ponto e a recepção no seu webhook. O gargalo costuma ser o intervalo de push do dispositivo, não o processamento do PunchConnect.

O que acontece se meu endpoint ficar fora do ar por horas?
Os eventos se acumulam e são retentados com backoff exponencial por 72 horas. Quando seu servidor volta, você recebe todos os eventos perdidos em ordem.

Posso reproduzir eventos webhook históricos?
Sim. A API de gerenciamento de webhooks permite reproduzir eventos para um intervalo de tempo.

Preciso tratar entregas webhook duplicadas?
Com entrega ao-menos-uma-vez, é possível receber o mesmo evento duas vezes. Use o campo event_id para deduplicação — é único por evento e estável entre retries.

Como testar webhooks durante o desenvolvimento?
Registre uma URL de webhook apontando para ngrok ou webhook.site. PunchConnect entregará eventos reais dos seus dispositivos de teste para sua máquina local.

---

Construindo uma integração biométrica? PunchConnect dá a você a API que você projetaria — se tivesse seis meses e 24.000 funcionários para testar. Inicie um teste gratuito de 7 dias e receba seu primeiro webhook em menos de 5 minutos. Sem cartão de crédito. Sem IP fixo. Apenas dados limpos, entregues de forma confiável.