Idempotencia y paginación
Idempotencia #
No hay cabecera de idempotencia: la clave es el id en la ruta. txid, idEnvio y el id de la subcuenta son suyos, de 26 a 35 caracteres alfanuméricos; el id de la devolución también, de 1 a 35. Genere un ULID antes de llamar y guárdelo.
| Situación | Respuesta |
|---|---|
| Id nuevo | 201 y el recurso creado. |
| Mismo id, mismo cuerpo | 200, el mismo recurso y la cabecera x-replayed: true. |
| Mismo id, cuerpo diferente | 409 (txid_duplicado, id_envio_duplicado, id_duplicado) cuando cambia un campo que identifica la solicitud: en el cobro, valor, deudor, ex.subconta y ex.splitConfig; en el retiro, valor, tipo, documento del beneficiario, subconta, exigirAprovacao y la presencia de validadeSegundos; en la devolución y en la subcuenta, cualquier campo. Otro campo diferente devuelve 200 con el recurso ya registrado, sin modificación. |
Después de un timeout o 5xx, consulte el recurso por el id. Si existe, sígalo. Si responde 404, repita la llamada con el mismo id. Nunca genere un id nuevo sin conocer el desenlace del anterior: un retiro repetido con otro idEnvio paga dos veces.
Paginación #
Los listados paginados (cobros, devoluciones, retiros, transacciones, el extracto del día y las entregas de webhook) usan un cursor opaco.
{
"cobrancas": [],
"cursor": { "proximo": "MTc4OTcyMzIyMzc2NzE1NH5DT0Iw...", "temMais": true }
}
| Campo | Descripción |
|---|---|
cursor.temMais |
true mientras haya otra página. Confíe en él, no en el tamaño de la lista. |
cursor.proximo |
Páselo en ?cursor= para la página siguiente. Vacío al final. En el feed de eventos, páselo en ?apos=: allí nunca viene vacío, y el de la última página es la posición a guardar para continuar después. Con ordem=recentes, el feed viene del más reciente al más antiguo, y el cursor va en ?antes=. |
limite |
Elementos por página, de 1 a 200. Por defecto, 50. Fuera de eso, 400 limite_invalido. |
Los listados vienen del más reciente al más antiguo; el feed de eventos, del más antiguo al más reciente.
Las subcuentas y los socios de split vienen completos en una respuesta, sin cursor. Las disputas también, a menos que usted pase limite o cursor: entonces vienen por página.
Las rutas del estándar del Banco Central (GET /v2/cob, GET /v2/pix) usan inicio, fim y paginacao.paginaAtual, como en el estándar.
Correlación #
Envíe x-correlation-id con 8 a 64 caracteres ASCII sin espacios. Toda respuesta lo devuelve, incluso la de la solicitud de token, el error lo repite en correlationId y el evento registrado lleva el mismo valor. Sin él, generamos uno.