Paginación y filtros

Todo endpoint de listado (GET /api/v1/charges, /people, /agreements...) usa paginación por número de página.

Parámetros

Enviados vía query string:

Parámetro	Tipo	Por defecto	Descripción
page	entero ≥ 1	1	Página solicitada (empieza en 1).
per_page	entero 1–100	20	Ítems por página. Máximo 100.
sort_by	string	varía por recurso	Campo de ordenamiento.
sort_order	asc | desc	varía por recurso	Dirección del ordenamiento.

Los nombres legados (limit, sortField, sortDirection) siguen aceptados por compatibilidad; cuando ambos aparecen en la misma request, el legado gana.

Envelope de respuesta

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

Campo	Descripción
data	Ítems de la página actual.
meta.total	Total de ítems que cumplen los filtros (no solo los devueltos).
meta.page	Página actual.
meta.limit	Ítems por página efectivamente aplicado.
meta.totalPages	Total de páginas (ceil(total / limit)).

La última página puede traer menos ítems que per_page; un page más allá del final devuelve data vacío (no es error).

Filtros

Los filtros específicos de cada recurso usan snake_case en la query string (due_date_from, person_id, document_number, status...) — la lista completa está en cada endpoint de la referencia. Los filtros conviven con paginación y ordenamiento en la misma request.

Ejemplos

Primera página, por defecto:

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

Página 3 con 50 ítems, vencidos primero:

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 + paginación:

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 las 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;
}

Buenas prácticas

• per_page=100 minimiza el número de requests y cuida tu rate limit.
• Para sincronización continua, prefiere filtros incrementales (fechas) o webhooks antes que barrer todo repetidamente.
• No asumas orden estable sin un sort_by explícito.
• Trata meta.total como una fotografía del momento — pueden entrar/salir ítems entre una página y otra durante la iteración.