# Boas práticas do canal

## A consulta de selo tem granularidade de dia

`valid_until` muda por **dia** — consultar o mesmo documento mais de uma vez por dia não traz informação
nova. Guarde a resposta da [consulta de selo](/referencia/distribuidor#consultar-o-selo-de-um-fornecedor-pelo-documento)
junto com o `valid_until` e só consulte de novo quando essa data passar, ou quando algo mudar do seu lado
(fornecedor novo na tela, convite que você acabou de emitir).

## Avisos primeiro, varredura como rede de segurança

Com os [avisos](/webhooks/visao-geral), você recebe um `POST` assinado quando algo muda, em vez de
varrer. A varredura continua valendo como reserva: se o seu endereço ficar fora do ar por horas, uma
leitura da [lista de fornecedores](/referencia/distribuidor#listar-os-fornecedores-de-um-cliente-com-o-andamento-de-cada-um)
põe tudo em dia, porque ela devolve o estado atual de cada um. Uma varredura por hora dá conta: nada
aqui é imediato — tudo depende de uma pessoa do outro lado.

Os reenvios (primeiro acesso, convite e link de verificação) **não mudam estado** e por isso não geram
aviso.

## O limite de chamadas é por IP de origem

Existe proteção de volume na borda, e ela é **por IP de origem, compartilhada com o resto da API** — não
é uma cota exclusiva do canal. Chamadas de servidor saem de poucos IPs, então o volume inteiro do seu
sistema se concentra num punhado de origens. Na prática:

- **espace as chamadas** em vez de disparar rajadas — uma varredura sequencial, não dezenas de conexões
  em paralelo;
- **não** faça uma consulta de selo por linha de tela: agregue por depósito (a lista de fornecedores) e
  carimbe a tela com o resultado em memória;
- uma resposta fora do formato JSON da API — um **429**, ou um corpo que não é JSON — é a borda barrando
  volume, não erro de dados: espere e repita, com intervalo crescente.

## Escreva com `Idempotency-Key`

Mande `Idempotency-Key` em todo
[cadastro de depósito](/referencia/distribuidor#cadastrar-um-cliente-deposito-no-seu-canal), com um
valor estável do seu lado (o id do cliente no seu sistema serve). Repetir por causa de timeout é normal;
criar dois depósitos por causa de um timeout não. A repetição responde **200** com o depósito que já
existia e `idempotent: true` — sem reemitir o link de primeiro acesso.

O convite não precisa disso: emitir de novo para o mesmo documento devolve o convite vivo (`reused: true`)
em vez de criar outro.

## Guarde o `client_id` (e o `invite_id`)

O `client_id` é a chave de tudo depois do cadastro, e o `invite_id` é o que o reenvio do convite pede. O
`external_reference` volta nas respostas de escrita justamente para você amarrar os dois ao seu próprio
identificador já na primeira resposta, sem depender de busca por documento depois.

## Ramifique no `code`

`4xx` é chamada a corrigir; `5xx` é para repetir — no cadastro, **com a mesma `Idempotency-Key`**. Em
qualquer caso, decida pelo `code`, nunca pelo texto de `error`.