Listado y paginación

Todos los endpoints GET que devuelven colecciones usan paginación por cursor.

Parámetros

Enviados vía query string:

Parámetro	Tipo	Default	Descripción
limit	entero 1–100	25	Cantidad de ítems por página. Máximo 100.
cursor	string	—	Cursor opaco devuelto en meta.next_cursor de la página anterior.

Respuesta

Todo listado sigue este envoltorio:

{
  "data": [
    { "id": "00000000-0000-0000-0000-000000000001", "name": "Conta Corrente" }
  ],
  "meta": {
    "next_cursor": "eyJpZCI6Mn0"
  }
}

Campo	Descripción
data	Array con los ítems de la página actual.
meta.next_cursor	Cursor para la próxima página. null cuando no hay más ítems.

Ejemplos

Primera página

curl -H "Authorization: Bearer $KOBANA_TOKEN" \
  -H 'User-Agent: Mi Sistema (contacto@example.com)' \
  'https://api.finance.kobana.com.br/v1/accounts?limit=25'

Próxima página

curl -H "Authorization: Bearer $KOBANA_TOKEN" \
  -H 'User-Agent: Mi Sistema (contacto@example.com)' \
  'https://api.finance.kobana.com.br/v1/accounts?limit=25&cursor=eyJpZCI6Mn0'

Iterando todas las páginas

Patrón recomendado en pseudocódigo:

async function fetchAll(url, token) {
  const out = [];
  let cursor = null;
  while (true) {
    const params = cursor ? `?limit=100&cursor=${cursor}` : '?limit=100';
    const res = await fetch(`${url}${params}`, {
      headers: { Authorization: `Bearer ${token}` },
    });
    const { data, meta } = await res.json();
    out.push(...data);
    if (!meta.next_cursor) break;
    cursor = meta.next_cursor;
  }
  return out;
}

Buenas prácticas

• limit=100 minimiza el número de solicitudes y consume menos del límite de solicitudes.
• Aplica filtros (ej.: ?company_id=<uuid>, ?occurred_at[gte]=2026-01-01) para reducir el volumen antes de paginar.

aviso

El cursor es opaco — no intentes decodificarlo ni construirlo manualmente. Guárdalo exactamente como vino en meta.next_cursor y devuélvelo en ?cursor=.