> ## Documentation Index
> Fetch the complete documentation index at: https://developers.pontua.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Webhooks customer-facing não estão disponíveis hoje. Use polling sobre os endpoints REST com filtros de período.

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**:

```javascript theme={null}
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
}
```

<Note>
  **Atenção:** o nome dos filtros de período (`atualizadoDe`, `criadoDe`,
  `dataInicio`, etc.) varia por endpoint. Cheque a [Referência da API](/api-reference)
  para o nome correto em cada recurso antes de implementar.
</Note>

## 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) |

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](/conceitos/idempotencia).

## 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.