Listas y paginación
Todas las listas se leen igual. Páginas estables, filtros que se combinan y registros en orden.
Listas de recursos
Pagos, cobros, clientes, beneficiarios y demás se devuelven del más nuevo al más antiguo, en páginas:
{
"data": [ { "id": "pout_01m3sgb0..." }, { "id": "pout_01m3sga9..." } ],
"has_more": true,
"next_cursor": "pout_01m3sga9..."
}| Parámetro | Qué hace |
|---|---|
limit | Cuántos por página: de 1 a 100. Por defecto 25. |
starting_after | El next_cursor de la página anterior. |
Sigue pidiendo mientras has_more sea true:
let cursor;
do {
const url = new URL("https://api-sandbox.caibopay.app/v1/payouts");
url.searchParams.set("limit", "100");
if (cursor) url.searchParams.set("starting_after", cursor);
const page = await fetch(url, { headers: { Authorization: `Bearer ${key}` } }).then((r) => r.json());
for (const payout of page.data) handle(payout);
cursor = page.has_more ? page.next_cursor : undefined;
} while (cursor);Un recorrido devuelve exactamente una vez cada elemento que existía al empezar, aunque se creen otros mientras paginas.
Filtros
| Filtro | Ejemplo |
|---|---|
status | ?status=completed |
created_after (incluido) | ?created_after=2026-10-01T00:00:00Z |
created_before (excluido) | ?created_before=2026-11-01T00:00:00Z |
| Relaciones | ?beneficiary_id=ben_…, ?customer_id=cus_…, ?funding_account_id=fa_… |
- Los filtros se combinan con Y.
- Las fechas van en RFC 3339. Codifica el
+de una zona horaria como%2B. - Un valor que el filtro no admite responde
400conparamigual al nombre del filtro. - Un id con buena forma que no es tuyo devuelve una lista vacía.
Registros: eventos y movimientos
GET /v1/events y GET /v1/balances/{currency}/entries se paginan con after, y nunca saltan ni repiten. Los eventos se leen del más antiguo al más nuevo; los movimientos del saldo, del más nuevo al más antiguo.
| Parámetro | Qué hace |
|---|---|
limit | De 1 a 100. Por defecto 50. |
after | El next_cursor de tu última lectura. |
En los eventos, next_cursor viene siempre, también en una página vacía. Guárdalo y vuelve a consultar desde ahí: así nunca te saltas un evento. Ver Eventos.