Skip to main content
A API Pontua não oferece webhooks customer-facing hoje. Para reagir a novos eventos (uma batida foi registrada, um colaborador foi cadastrado, um relatório ficou pronto), use polling periódico sobre os endpoints REST disponíveis.

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:
async function syncIncremental({ token, recurso, ultimoSync }) {
  let pagina = 0
  const limite = 100
  let novoCursor = ultimoSync

  while (true) {
    const params = new URLSearchParams({
      pagina: String(pagina),
      limite: String(limite),
      // O nome do filtro de período varia por endpoint —
      // confira na Referência da API o nome correto.
      // Exemplos comuns: dataInicio, atualizadoDe, criadoDe.
      atualizadoDe: ultimoSync,
    })

    const resp = await fetch(
      `https://api.pontua.com.br/${recurso}?${params}`,
      { headers: { Authorization: `Bearer ${token}` } },
    )
    const { resultados, totalRegistros } = await resp.json()

    for (const item of resultados) {
      await processar(item)
      // Atualiza cursor para o item mais recente processado
      if (item.atualizadoEm && item.atualizadoEm > novoCursor) {
        novoCursor = item.atualizadoEm
      }
    }

    if ((pagina + 1) * limite >= totalRegistros) break
    pagina++
  }

  return novoCursor
}
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:
RecursoIntervalo razoável
Batidas / registros recentes1–5 minutos
Colaboradores (mudanças cadastrais)30 minutos – 1 hora
Estrutura organizacional (departamentos, cargos, turnos)1–6 horas
Status de relatório que você gerouPolling do relatorioId específico (não da lista geral)
Não faça polling mais agressivo que 1 req/min por recurso sem um caso extraordinário discutido com sua gerência.

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 id do recurso como chave de deduplicação no seu lado
  • Se já processou, ignora (loga e segue)
→ Mais detalhes em Idempotência.

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 para tecnologia@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)
Esse feedback ajuda a priorizar webhooks no roadmap.