Idempotência
Como usar externalRef para evitar cobranças duplicadas. Janelas de 1 hora (com externalRef) e 60 segundos (sem externalRef).
Por que idempotência importa
Redes falham. Timeouts acontecem. Sem idempotência, um retry do seu sistema pode gerar dois relatórios cobrados para o mesmo motorista.
Usando externalRef
Envie um identificador único da sua aplicação no campo externalRef:
{
"cpf": "123.456.789-09",
"externalRef": "batch-2026-06-01-driver-42"
}Se um POST com o mesmo cpf + externalRef for enviado dentro de 1 hora,
o sistema retorna o relatório já existente sem criar um novo nem cobrar novamente.
Boas práticas para externalRef
Use um identificador estável e único na sua aplicação: o ID do motorista no seu sistema, o ID do lote de processamento, ou um UUID/ULID. Evite valores que mudam entre retries.
Janela sem externalRef (proteção de race condition)
Se você não enviar externalRef, o sistema aplica uma janela de 60 segundos com chave (organização, cpf).
Dois POSTs simultâneos para o mesmo CPF dentro de 60s retornam o mesmo relatório.
Prefira sempre externalRef
A janela de 60s protege contra race conditions, mas não substitui a idempotência explícita.
Sem externalRef, POSTs após 60s para o mesmo CPF criam relatórios distintos e cobram separadamente.
Resposta em caso de hit de idempotência
O código de resposta continua sendo 202, idêntico ao de um relatório novo.
O reportId retornado é o do relatório já existente, e o status reflete o estado atual
(pode ser DELIVERED se já processado).