Estratégia: polling com cursor
Para minimizar custo e latência, salve um cursor de timestamp no seu lado e use filtros de período disponíveis nos endpoints (quando existirem) para pegar só os novos:Atenção: o nome dos filtros de período (
atualizadoDe, criadoDe,
dataInicio, etc.) varia por endpoint. Cheque a Referência da API
para o nome correto em cada recurso antes de implementar.Frequência sugerida de polling
Volumes típicos sem rate limiting agressivo:| Recurso | Intervalo razoável |
|---|---|
| Batidas / registros recentes | 1–5 minutos |
| Colaboradores (mudanças cadastrais) | 30 minutos – 1 hora |
| Estrutura organizacional (departamentos, cargos, turnos) | 1–6 horas |
| Status de relatório que você gerou | Polling do relatorioId específico (não da lista geral) |
Deduplicação no cliente
Polling com cursor pode trazer o mesmo item 2x em janelas de borda (timestamp= cursor). Trate de forma idempotente:
- Use o
iddo recurso como chave de deduplicação no seu lado - Se já processou, ignora (loga e segue)
Quando webhooks bloqueiam sua integração
Se polling não atende seu caso (latência crítica abaixo de 1 minuto, volume grande de eventos para escalonar consumo), escreva paratecnologia@pontua.com.br descrevendo:
- Quais eventos você precisaria
- Volume estimado (eventos/hora)
- Latência aceitável (segundos vs minutos)
- Tolerância a duplicatas (at-least-once vs exactly-once)