---
icon: list-filter
title: Paginación y filtrado
description: Paginación por cursor, conjuntos de campos dispersos y patrones de filtrado para endpoints de lista de la API de Fuxam v4 — limit, cursor, fields y filtros por código.
---

Los endpoints de lista en la API de Fuxam v4 devuelven páginas de resultados dentro del sobre compartido `{ data, pagination, meta }`. Se recorre una colección con **cursores** opacos, opcionalmente se reduce cada carga con **conjuntos de campos dispersos** y, en recursos compatibles, se acotan resultados con **filtros** como el `code` del curso.

## Por qué importa

Los directorios de instituciones son grandes. Obtener todos los usuarios o cursos en una respuesta no es fiable ni respetuoso con el presupuesto compartido de **1000 solicitudes/min**. La paginación por cursor ofrece páginas estables y eficientes; los conjuntos de campos dispersos reducen el ancho de banda; los filtros permiten resolver un curso conocido sin recorrer todo el catálogo.

## Cómo encaja

```mermaid
flowchart TD
  Start[Solicitud de lista] --> Page[Recibir data y pagination]
  Page --> More{hay mas}
  More -->|yes| Next[Solicitar con siguiente cursor]
  Next --> Page
  More -->|no| Done[Coleccion completa]
```

Esta página se apoya en las convenciones de la [descripción general](/docs/es/api/overview) y la llamada de primera página en [Primeros pasos](/docs/es/api/getting-started). El comportamiento de límite de tasa al paginar de forma agresiva se cubre en [Errores e idempotencia](/docs/es/api/errors-and-idempotency).

## Conceptos clave

| Término | Definición |
|---|---|
| **Cursor / keyset pagination** | Las páginas se identifican por un cursor opaco sobre `(sortField, id)`, no por offsets numéricos. |
| **limit** | Parámetro de consulta de tamaño de página: `1`–`100`. Se aplica el valor por defecto del servidor si se omite. |
| **cursor** | Token opaco de `pagination.next_cursor` de la página anterior. |
| **has_more** | Cuando es `false`, ha llegado a la última página. |
| **Sparse fieldset** | `?fields=` con los nombres de propiedad que desea devueltos. |
| **Filter** | Parámetros de consulta específicos del recurso (por ejemplo `code` en cursos). |

## Referencia de paginación por cursor

| Parámetro | Ubicación | Descripción |
|---|---|---|
| `limit` | Consulta | Tamaño de página (`1`–`100`) |
| `cursor` | Consulta | Cursor opaco del `pagination.next_cursor` de la página anterior |
| `pagination.next_cursor` | Respuesta | Páselo como `cursor` en la siguiente solicitud cuando existan más páginas |
| `pagination.has_more` | Respuesta | `true` si hay otra página disponible |
| `pagination.limit` | Respuesta | Tamaño de página efectivo de esta respuesta |

Ejemplo de respuesta de lista:

```json
{
  "data": [{ "id": "usr_123" }, { "id": "usr_456" }],
  "pagination": {
    "next_cursor": "eyJpZCI6MTIzfQ==",
    "has_more": true,
    "limit": 25
  },
  "meta": {
    "requestId": "req_1700000000000_abc123",
    "timestamp": "2026-01-15T10:30:00.000Z",
    "version": "v4"
  }
}
```

### Seguridad de cursores

Los cursores están **firmados con HMAC** y ligados a su institución e integración. Cursores manipulados, caducados en sentido o ajenos devuelven HTTP `400` con código `invalid_cursor`. Nunca comparta cursores entre integraciones ni edite su contenido.

:::info
La paginación de v4 **no** está basada en offset. No hay `page` / `pageSize` (pertenecían a v3). Use siempre `cursor` y `limit`.
:::

## Cómo recorrer todas las páginas

Pseudocódigo para una sincronización de colección completa:

```bash
#!/usr/bin/env bash
set -euo pipefail

BASE="https://fuxam.app/api/v4"
CURSOR=""
LIMIT=100

while true; do
  if [ -z "$CURSOR" ]; then
    URL="${BASE}/users?limit=${LIMIT}"
  else
    URL="${BASE}/users?limit=${LIMIT}&cursor=${CURSOR}"
  fi

  RESP=$(curl -sS -u "${CLIENT_ID}:${CLIENT_SECRET}" -H "Accept: application/json" "$URL")

  # Procese RESP.data en el lenguaje que elija, luego:
  HAS_MORE=$(printf '%s' "$RESP" | jq -r '.pagination.has_more')
  CURSOR=$(printf '%s' "$RESP" | jq -r '.pagination.next_cursor // empty')

  if [ "$HAS_MORE" != "true" ]; then
    break
  fi
done
```

Forma HTTP para páginas posteriores:

```http
GET /api/v4/users?limit=100&cursor=eyJpZCI6MTIzfQ== HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Accept: application/json
```

:::tip
Persista el último cursor exitoso solo si reanuda un **único** recorrido interrumpido con la **misma** integración. En sincronizaciones nocturnas, empiece desde la primera página en cada ejecución salvo que tenga un diseño incremental deliberado.
:::

## Conjuntos de campos dispersos

En endpoints compatibles, solicite solo los campos que necesita:

```http
GET /api/v4/users?fields=id,email&limit=50 HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Accept: application/json
```

```bash
curl -sS \
  -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -H "Accept: application/json" \
  "https://fuxam.app/api/v4/users?fields=id,email&limit=50"
```

Beneficios:

- Cargas más pequeñas al sincronizar directorios grandes
- Contratos más claros en clientes tipados (documenta los campos de los que depende)
- Menos acoplamiento accidental a propiedades que no usa

:::note
Los nombres de campo deben coincidir con lo que documenta el endpoint. Si omite `fields`, el endpoint devuelve su representación por defecto.
:::

## Filtrado

Los filtros son específicos del recurso. Un ejemplo documentado y habitual es buscar cursos por **code** y luego direccionarlos por **id** en llamadas posteriores (importante si migra desde v3).

```http
GET /api/v4/courses?code=CS101&limit=25 HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Accept: application/json
```

```bash
curl -sS \
  -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -H "Accept: application/json" \
  "https://fuxam.app/api/v4/courses?code=CS101&limit=25"
```

Seguimiento típico: tome `data[0].id` de la lista filtrada, luego `GET /courses/{id}` para el sobre completo de un solo recurso (y `ETag` si va a actualizarlo). Consulte [Recetas](/docs/es/api/recipes) para el patrón de extremo a extremo y [Courses](/docs/es/api/courses/courses/list-courses) para la referencia de la operación de lista.

Los cursos en el manual web son las mismas entidades que el personal explora en [Courses Management](/docs/es/fuxam-web/cms/courses-management) y abre en el [LMS](/docs/es/fuxam-web/lms/courses).

## Buenas prácticas

- Prefiera `limit=100` para trabajos de sincronización masiva; use límites menores al explorar de forma interactiva.
- Deténgase estrictamente en `has_more === false` — no asuma que un array `data` vacío por sí solo termina el recorrido sin comprobar la paginación.
- Combine `fields` con paginación cuando solo necesite ids para una tabla de unión.
- Respete los límites de tasa al recorrer muchas páginas; honre `Retry-After` en `429`.
- Trate los cursores como secretos opacos de su integración — no los registre en canales públicos.

## Errores frecuentes

| Error | Resultado | Remedio |
|---|---|---|
| Usar `page` / `pageSize` de v3 | Errores inesperados o parámetros ignorados | Cambie a `cursor` / `limit` |
| Reutilizar el cursor de otra integración | `400` `invalid_cursor` | Inicie una lista nueva con sus propias credenciales |
| Asumir estabilidad de offset | Filas duplicadas o faltantes con escrituras concurrentes | Los cursores keyset ya reducen esto; diseñe sincronizaciones para consistencia eventual |
| Obtener objetos completos cuando solo necesita ids | Sincronizaciones lentas, mayor uso de tasa | Use `?fields=id` (y otras claves necesarias) |

## Preguntas frecuentes

**¿Cuál es el tamaño máximo de página?**

`limit` acepta `1`–`100`. Los valores fuera de ese rango deben tratarse como errores del cliente — manténgase en el rango documentado.

**¿Puedo saltar a la página 10?**

No. La paginación por cursor no admite números de página arbitrarios. Avance desde el inicio o conserve un cursor almacenado de una ejecución anterior del mismo recorrido.

**¿Todos los endpoints de lista admiten los mismos filtros?**

No. Los filtros son por recurso. Use `code` en cursos según la documentación; consulte la página de referencia de cada endpoint para otros parámetros de consulta.

## Páginas relacionadas

**[Primeros pasos](/docs/es/api/getting-started)**

Primera llamada de lista y primer cursor.

**[Recetas](/docs/es/api/recipes)**

Patrones de sincronizar todos los usuarios y buscar por código.

**[Errores e idempotencia](/docs/es/api/errors-and-idempotency)**

Límites de tasa al paginar, invalid_cursor.

**[Referencia de Courses](/docs/es/api/courses/courses/list-courses)**

Listar cursos y filtrar por código.
