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