Projetando uma API de Ponto Biométrico

Princípios de design

Ao projetar a API do PunchConnect, estudamos as APIs que mais admiramos: Stripe pela consistência, Twilio pelos webhooks e GitHub pela experiência do desenvolvedor. Três princípios emergiram:

1. Seja previsível — nomenclatura consistente, formatos de resposta e códigos de erro em todos os endpoints

2. Seja em tempo real — webhooks para eventos, não polling. Desenvolvedores devem reagir a eventos, não verificá-los.

3. Seja resiliente — toda operação deve ser segura para retentativa. Chaves de idempotência, deduplicação e entrega at-least-once.

Garantias de entrega de webhooks

O PunchConnect garante entrega at-least-once para todos os eventos de webhook. Veja como funciona:

Quando um evento de ponto ocorre, ele é gravado em uma fila durável. Um worker de entrega o pega e envia o HTTP POST para sua URL de callback. Se o seu servidor responder com 2xx, o evento é marcado como entregue.

Se o seu servidor estiver fora do ar ou responder com 5xx, o evento é retentado com backoff exponencial: 1 min, 5 min, 30 min, 2 horas, 12 horas, 72 horas. Após todas as retentativas serem esgotadas, o evento é marcado como falho e você é notificado por e-mail.

Estratégia de rate limiting

Usamos um rate limiter de janela deslizante com padrões generosos: 1.000 chamadas de API por dispositivo por dia para endpoints REST, e ilimitado para webhooks de entrada (dispositivo → PunchConnect).

Os limites de taxa são comunicados via headers padrão: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Quando você atinge o limite, recebe uma resposta 429 com um header Retry-After.

Idempotência

Todos os endpoints mutáveis (POST, PUT, DELETE) aceitam um header Idempotency-Key. Se você enviar a mesma requisição com a mesma chave dentro de 24 horas, receberá a resposta em cache em vez de criar uma duplicata.

Isso é crítico para comandos de dispositivo. Se você enviar um comando "sincronizar funcionários" e sua rede cair antes de receber a resposta, você pode retentá-lo com segurança sem acidentalmente acionar uma sincronização dupla.

Lições aprendidas

A maior lição: dados biométricos do mundo real são bagunçados. Dispositivos enviam registros de ponto duplicados, timestamps fora de ordem e ocasionalmente dados corrompidos. Nossa API normaliza e deduplica antes que seu webhook receba, para que você obtenha dados limpos e confiáveis.