Idempotência e paginação
Idempotência #
Não há cabeçalho de idempotência: a chave é o id no caminho. txid, idEnvio e o id da sub-conta são seus, com 26 a 35 caracteres alfanuméricos; o id da devolução também, com 1 a 35. Gere um ULID antes de chamar e guarde-o.
| Situação | Resposta |
|---|---|
| Id novo | 201 e o recurso criado. |
| Mesmo id, mesmo corpo | 200, o mesmo recurso e o cabeçalho x-replayed: true. |
| Mesmo id, corpo diferente | 409 (txid_duplicado, id_envio_duplicado, id_duplicado). |
Depois de um timeout ou 5xx, consulte o recurso pelo id. Se ele existe, siga-o. Se responder 404, repita a chamada com o mesmo id. Nunca gere um id novo sem saber o desfecho do anterior: um saque repetido com outro idEnvio paga duas vezes.
Paginação #
As listagens sob /v2/ex/ usam cursor opaco.
{
"cobrancas": [],
"cursor": { "proximo": "MTc4OTcyMzIyMzc2NzE1NH5DT0Iw...", "temMais": true }
}
| Campo | Descrição |
|---|---|
cursor.temMais |
true enquanto houver outra página. Confie nele, não no tamanho da lista. |
cursor.proximo |
Passe em ?cursor= para a próxima página. Vazio no fim. |
limite |
Itens por página. Padrão 50, até 200. |
As listagens vêm da mais recente para a mais antiga; o feed de eventos, da mais antiga para a mais recente.
As rotas do padrão do Banco Central (GET /v2/cob, GET /v2/pix) usam inicio, fim e paginacao.paginaAtual, como no padrão.
Correlação #
Envie x-correlation-id com 8 a 64 caracteres ASCII sem espaço. Toda resposta o devolve, o erro o repete em correlationId e o evento gravado carrega o mesmo valor. Sem ele, geramos um.