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) quando muda um campo que identifica o pedido: na cobrança, valor, devedor, ex.subconta e ex.splitConfig; no saque, valor, tipo, documento do favorecido, subconta, exigirAprovacao e a presença de validadeSegundos; na devolução e na sub-conta, qualquer campo. Outro campo diferente devolve 200 com o recurso já gravado, sem alteração. |
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 paginadas (cobranças, devoluções, saques, transações, o extrato do dia e as entregas de webhook) 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. No feed de eventos, passe em ?apos=: ali ele nunca vem vazio, e o da última página é a posição a guardar para continuar depois. Com ordem=recentes, o feed vem do mais recente para o mais antigo, e o cursor vai em ?antes=. |
limite |
Itens por página, de 1 a 200. Padrão 50. Fora disso, 400 limite_invalido. |
As listagens vêm da mais recente para a mais antiga; o feed de eventos, da mais antiga para a mais recente.
Sub-contas e parceiros de split vêm inteiros numa resposta, sem cursor. As contestações também, a não ser que você passe limite ou cursor: aí vêm por página.
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, inclusive a do pedido de token, o erro o repete em correlationId e o evento gravado carrega o mesmo valor. Sem ele, geramos um.