Listagem e Paginação

Todos os endpoints GET que retornam coleções usam paginação por cursor.

Parâmetros

Enviados via query string:

Parâmetro	Tipo	Default	Descrição
limit	inteiro 1–100	25	Quantidade de itens por página. Máximo 100.
cursor	string	—	Cursor opaco retornado em meta.next_cursor da página anterior.

Resposta

Toda listagem segue este envelope:

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

Campo	Descrição
data	Array com os itens da página atual.
meta.next_cursor	Cursor para a próxima página. null quando não há mais itens.

Exemplos

Primeira página

curl -H "Authorization: Bearer $KOBANA_TOKEN" \
  -H 'User-Agent: Meu Sistema (contato@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: Meu Sistema (contato@example.com)' \
  'https://api.finance.kobana.com.br/v1/accounts?limit=25&cursor=eyJpZCI6Mn0'

Iterando todas as páginas

Padrão recomendado em pseudo-có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;
}

Boas práticas

• limit=100 minimiza o número de requisições e consome menos do limite de requisições.
• O cursor é opaco — não tente decodificá-lo nem construí-lo manualmente.
• Aplique filtros (ex.: ?company_id=<uuid>, ?occurred_at[gte]=2026-01-01) para reduzir o volume antes de paginar.