Listado y Paginación

Todos los endpoints GET que devuelven colecciones (/v1/portal_users, /v1/dashboard_users, /v1/team_roles, etc.) usan paginación por número de página.

Parámetros

Se envían en la query string:

Parámetro	Tipo	Default	Descripción
page	entero ≥ 1	1	Página solicitada (empieza en 1).
per_page	entero 1–100	20	Cantidad de ítems por página. Máximo 100.
sort_by	string	varía por recurso	Campo usado para ordenar. Acepta los mismos nombres de la respuesta.
sort_order	asc o desc	desc	Dirección del orden.

Los valores fuera de rango se ajustan (ej.: per_page=999 pasa a 100; page=0 pasa a 1).

Respuesta

Todo listado sigue este sobre:

{
  "data": [
    { "id": "8b2f4c1e-6a3d-4f0b-9c7e-2d5a1b3c4d5e", "email": "joao@example.com", "status": "active", "tenant_id": "cliente-1042" }
  ],
  "meta": {
    "total": 142,
    "page": 1,
    "per_page": 20,
    "total_pages": 8
  }
}

Campo	Descripción
data	Array con los í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.per_page	Ítems por página efectivamente aplicados.
meta.total_pages	Número total de páginas (ceil(total / per_page)).

La última página puede tener menos de per_page ítems. Cuando page > total_pages, data viene vacío (no es un error).

Ejemplos

Primera página, por defecto

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

Página 3 con 50 ítems

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

Ordenado por created_at ascendente

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

Filtros + paginación

Los filtros específicos del recurso conviven con page/per_page:

curl -H "Authorization: Bearer $KOBANA_TOKEN" \
  'https://api.dashboards.sandbox.kobana.com.br/v1/portal_users?status=active&email=joao&page=2&per_page=25'

Recorriendo todas las páginas

Patrón recomendado en pseudocó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;
}

Buenas prácticas

• Para sincronización incremental, prefiere filtrar por updated_at_gte (o un filtro similar disponible en el endpoint) en lugar de recorrer todas las páginas.
• per_page=100 minimiza la cantidad de solicitudes y consume menos del límite de solicitudes.
• Haz cache de meta.total al renderizar paginadores; no lo recalcules en cada navegación.
• No asumas un orden estable sin sort_by explícito: el orden por defecto puede variar entre recursos.