Paginação e filtros

Todo endpoint de listagem (GET /api/v1/charges, /people, /agreements...) usa paginação por número de página.

Parâmetros

Enviados via query string:

Parâmetro	Tipo	Padrão	Descrição
page	inteiro ≥ 1	1	Página solicitada (começa em 1).
per_page	inteiro 1–100	20	Itens por página. Máximo 100.
sort_by	string	varia por recurso	Campo de ordenação.
sort_order	asc | desc	varia por recurso	Direção da ordenação.

Os nomes legados (limit, sortField, sortDirection) continuam aceitos por compatibilidade; quando os dois aparecem na mesma requisição, o legado vence.

Envelope de resposta

{
  "data": [
    { "id": "cmd8k2p4x0001ab3f", "status": "overdue", "amount": "1500.00", ... }
  ],
  "meta": {
    "total": 142,
    "page": 1,
    "limit": 20,
    "totalPages": 8
  }
}

Campo	Descrição
data	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.limit	Itens por página efetivamente aplicado.
meta.totalPages	Total de páginas (ceil(total / limit)).

A última página pode vir com menos itens que per_page; page além do fim devolve data vazio (não é erro).

Filtros

Filtros específicos de cada recurso usam snake_case na query string (due_date_from, person_id, document_number, status...) — a lista completa está em cada endpoint da referência. Filtros convivem com paginação e ordenação na mesma requisição.

Exemplos

Primeira página, padrão:

curl -H "Authorization: Bearer $DUNNING_TOKEN" \
  'https://api.dunning.kobana.com.br/api/v1/charges'

Página 3 com 50 itens, vencidas primeiro:

curl -H "Authorization: Bearer $DUNNING_TOKEN" \
  'https://api.dunning.kobana.com.br/api/v1/charges?page=3&per_page=50&sort_by=due_date&sort_order=asc'

Filtro + paginação:

curl -H "Authorization: Bearer $DUNNING_TOKEN" \
  'https://api.dunning.kobana.com.br/api/v1/charges?status=overdue&due_date_from=2026-07-01&per_page=100'

Iterando todas as páginas

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.totalPages) break;
    page += 1;
  }
  return out;
}

Boas práticas

• per_page=100 minimiza o número de requisições e poupa o seu rate limit.
• Para sincronização contínua, prefira filtros incrementais (datas) ou webhooks a varrer tudo repetidamente.
• Não assuma ordem estável sem sort_by explícito.
• Trate meta.total como fotografia do momento — itens podem entrar/sair entre uma página e outra durante a iteração.