Listagem e Paginação

Todos os endpoints GET que retornam coleções (/v1/customers, /v1/subscriptions, /v1/invoices, etc.) usam paginação por número de página.

Parâmetros

Enviados via query string:

Parâmetro	Tipo	Default	Descrição
page	inteiro ≥ 1	1	Página solicitada (começa em 1).
per_page	inteiro 1–100	20	Quantidade de itens por página. Máximo 100.
sort_by	string	varia por recurso	Campo usado para ordenar. Aceita os mesmos nomes da resposta.
sort_order	asc ou desc	desc	Direção da ordenação.

Valores fora dos limites são clampados (ex.: per_page=999 vira 100; page=0 vira 1).

Resposta

Toda listagem segue este envelope:

{
  "data": [
    { "id": "per_01HPER", "name": "João Silva", "email": "joao@example.com" }
  ],
  "meta": {
    "total": 142,
    "page": 1,
    "per_page": 20,
    "total_pages": 8
  }
}

Campo	Descrição
data	Array com os itens da página atual.
meta.total	Total de itens que atendem aos filtros (não só os retornados).
meta.page	Página atual.
meta.per_page	Itens por página efetivamente aplicado.
meta.total_pages	Número total de páginas (ceil(total / per_page)).

A última página pode conter menos que per_page itens. Quando page > total_pages, data vem vazio (não é erro).

Exemplos

Primeira página, padrão

curl -H "Authorization: Bearer $KOBANA_TOKEN" \
  'https://api.billing.sandbox.kobana.com.br/v1/customers'

Página 3 com 50 itens

curl -H "Authorization: Bearer $KOBANA_TOKEN" \
  'https://api.billing.sandbox.kobana.com.br/v1/customers?page=3&per_page=50'

Ordenado por name ascendente

curl -H "Authorization: Bearer $KOBANA_TOKEN" \
  'https://api.billing.sandbox.kobana.com.br/v1/customers?sort_by=name&sort_order=asc'

Filtros + paginação

Filtros específicos do recurso convivem com page/per_page:

curl -H "Authorization: Bearer $KOBANA_TOKEN" \
  'https://api.billing.sandbox.kobana.com.br/v1/customers?search=joao&page=2&per_page=25'

Iterando todas as páginas

Padrão recomendado em pseudo-código:

async function fetchAll(url, token) {
  const out = [];
  let page = 1;
  while (true) {
    const res = await fetch(`${url}?page=${page}&per_page=100`, {
      headers: { Authorization: `Bearer ${token}` },
    });
    const { data, meta } = await res.json();
    out.push(...data);
    if (page >= meta.total_pages) break;
    page += 1;
  }
  return out;
}

Boas práticas

• Para sincronização incremental, prefira filtrar por updated_at_gte (ou similar disponível no endpoint) ao invés de varrer todas as páginas.
• per_page=100 minimiza o número de requisições e consome menos do limite de requisições.
• Faça cache de meta.total quando estiver renderizando paginadores; não recalcule a cada navegação.
• Evite assumir ordem estável sem sort_by explícito — a ordem padrão pode mudar entre recursos.