---
icon: book-open
title: Recetas
description: Patrones prácticos de la API de Fuxam v4 — sincronizar usuarios, buscar cursos por código, actualizaciones seguras con ETag y creaciones idempotentes.
---

Estas recetas son patrones de extremo a extremo construidos solo con las convenciones documentadas de v4: Basic Auth, el sobre `{ data, meta }`, paginación por cursor, `Idempotency-Key` y `ETag` / `If-Match`. Úselas como plantillas en su middleware; cambie las rutas de recurso según necesite y confirme los nombres de campo en las páginas de referencia de endpoints generadas.

**URL base:** `https://fuxam.app/api/v4`

## Por qué ayudan las recetas

Las páginas de referencia muestran una operación a la vez. Las integraciones reales encadenan operaciones: listar → filtrar → obtener → patch, o crear → reintentar. Los patrones siguientes codifican esas secuencias para que los equipos de TI universitarios puedan desplegar trabajos de sincronización fiables sin redescubrir casos límite de concurrencia y paginación.

## Antes de empezar

- Complete [Primeros pasos](/docs/es/api/getting-started) para que las credenciales funcionen.
- Lea [Autenticación](/docs/es/api/authentication), [Paginación y filtrado](/docs/es/api/pagination-and-filtering) y [Errores e idempotencia](/docs/es/api/errors-and-idempotency).
- Mantenga `CLIENT_ID` y `CLIENT_SECRET` en el entorno; nunca los codifique en scripts que confirme.

```mermaid
flowchart LR
  Auth[Autenticar] --> List[Listar o filtrar]
  List --> Get[Obtener por id]
  Get --> Write[Crear o actualizar]
  Write --> Handle[Manejar errores y reintentos]
```

## Receta: Sincronizar todos los usuarios

**Objetivo:** Extraer todos los usuarios a un sistema externo usando paginación por cursor.

**Cuándo usarla:** Sincronización nocturna de identidades con [User Management](/docs/es/fuxam-web/base/user-management) como fuente de verdad de quién existe en Fuxam.

```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}&fields=id,email"
  else
    URL="${BASE}/users?limit=${LIMIT}&fields=id,email&cursor=${CURSOR}"
  fi

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

  # Inserte o actualice cada objeto en RESP.data en su espejo SIS / directorio.
  printf '%s\n' "$RESP" | jq -c '.data[]'

  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
```

Pseudocódigo:

```text
cursor = null
loop:
  response = GET /users?limit=100&fields=id,email[&cursor=cursor]
  upsert_all(response.data)
  if response.pagination.has_more is false: break
  cursor = response.pagination.next_cursor
```

:::tip
Los conjuntos de campos dispersos (`fields=id,email`) mantienen las cargas pequeñas. Añada campos solo cuando su espejo los necesite. Detalles del endpoint: [Users](/docs/es/api/users/users/list-users).
:::

## Receta: Buscar un curso por código y leer por id

**Objetivo:** Resolver un código de curso legible por humanos a un id estable y obtener el recurso completo.

**Cuándo usarla:** Migraciones desde v3 (donde el direccionamiento por código era más habitual), importaciones SIS que solo conocen códigos de curso o enlaces a cursos que el personal gestiona en [Courses Management](/docs/es/fuxam-web/cms/courses-management).

```bash
CODE="CS101"

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

COURSE_ID=$(printf '%s' "$LIST" | jq -r '.data[0].id // empty')

if [ -z "$COURSE_ID" ]; then
  echo "No course found for code ${CODE}" >&2
  exit 1
fi

curl -sS -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -H "Accept: application/json" \
  -D - \
  "https://fuxam.app/api/v4/courses/${COURSE_ID}"
```

Secuencia HTTP:

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

```http
GET /api/v4/courses/{id} HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Accept: application/json
```

:::note
En v4, los cursos se direccionan por **id**. Filtrar con `GET /courses?code=…` es la forma documentada de descubrir ese id. Consulte [Courses](/docs/es/api/courses/courses/list-courses).
:::

## Receta: Actualizar un recurso de forma segura con ETag

**Objetivo:** Cambiar un solo recurso sin sobrescribir la edición concurrente de otra persona.

**Cuándo usarla:** Cualquier `PATCH`, `PUT` o `DELETE` automatizado en un solo recurso que emite `ETag` en `GET`.

```bash
USER_ID="usr_123"

# 1) Leer versión actual
HEADERS=$(mktemp)
BODY=$(mktemp)

curl -sS -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -H "Accept: application/json" \
  -D "$HEADERS" \
  -o "$BODY" \
  "https://fuxam.app/api/v4/users/${USER_ID}"

ETAG=$(awk 'BEGIN{IGNORECASE=1} /^ETag:/{print $2}' "$HEADERS" | tr -d '\r')

# 2) Escribir con If-Match
HTTP_CODE=$(curl -sS -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -o /tmp/patch-response.json -w "%{http_code}" \
  -X PATCH \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "If-Match: ${ETAG}" \
  -d @patch-body.json \
  "https://fuxam.app/api/v4/users/${USER_ID}")

if [ "$HTTP_CODE" = "412" ]; then
  echo "precondition_failed — re-GET, merge, retry" >&2
  exit 1
fi
```

Pseudocódigo:

```text
resource, etag = GET /users/{id}          # capture ETag header
try:
  PATCH /users/{id} with If-Match: etag
catch 412 precondition_failed:
  resource, etag = GET /users/{id} again
  merge_changes(resource)
  retry PATCH with new etag
catch 428 precondition_required:
  ensure If-Match is sent
```

:::warning[No reintente 412 a ciegas]
Un `412` significa que el recurso cambió. Vuelva a leer y concilie antes de enviar otra escritura.
:::

## Receta: Crear con idempotencia

**Objetivo:** Crear un recurso una vez, aunque el cliente HTTP reintente tras un tiempo de espera.

**Cuándo usarla:** Trabajos de aprovisionamiento, consumidores de webhook que pueden entregar dos veces, cualquier creación que no deba duplicarse.

```bash
IDEMPOTENCY_KEY="$(uuidgen)"

curl -sS \
  -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
  -d @create-body.json \
  "https://fuxam.app/api/v4/users"
```

```http
POST /api/v4/users HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Content-Type: application/json
Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Accept: application/json

# Body: JSON create payload from the endpoint reference
```

Comportamiento esperado:

| Situación | Resultado |
|---|---|
| Primera creación exitosa | `201` con el nuevo recurso en `data` |
| Reintento con la **misma** clave y creación equivalente | Respuesta original en caché (incluido `201`) — sin duplicado |
| Clave en conflicto en curso | Puede devolver `409` — espere y reintente con la misma clave, o revise el manejo de conflictos en su trabajo |

:::tip
Almacene la clave de idempotencia junto al id de su trabajo saliente para que cada reintento de ese trabajo reutilice la clave.
:::

## Receta: Manejar límites de tasa al paginar

**Objetivo:** Completar una sincronización grande sin fallar el trabajo al alcanzar 1000 solicitudes/min.

```text
loop pages:
  response = GET list
  if status == 429:
    sleep(Retry-After)
    retry same request
  process response.data
  advance cursor
```

```bash
# Fragmento ilustrativo — respete Retry-After de los encabezados de respuesta
RETRY_AFTER=60
sleep "$RETRY_AFTER"
```

Combínelo con valores `limit` mayores para necesitar menos solicitudes por recorrido completo. Detalles: [Errores e idempotencia](/docs/es/api/errors-and-idempotency).

## Elegir un patrón

| Necesidad | Receta |
|---|---|
| Reflejar el directorio | Sincronizar todos los usuarios |
| El SIS solo conoce códigos de curso | Buscar por código, luego por id |
| Actualizar sin pisar ediciones en la interfaz | Actualizar de forma segura con ETag |
| Aprovisionar sin duplicados | Crear con idempotencia |
| Sincronización grande bajo carga | Paginación consciente del límite de tasa |

## Buenas prácticas en todas las recetas

- Registre `meta.requestId` en cada respuesta.
- Prefiera trabajos del lado del servidor frente a llamadas desde el navegador con secretos de larga duración.
- Separe integraciones por carga de trabajo para que límites de tasa y rotaciones permanezcan aislados ([Autenticación](/docs/es/api/authentication)).
- Tras codificar una receta, abra la tarjeta de referencia correspondiente en la sección de exploración de la [descripción general](/docs/es/api/overview) para confirmar esquemas de solicitud/respuesta.

## Errores frecuentes

| Error | Mejor enfoque |
|---|---|
| Sincronizar con `limit=1` | Use hasta `100` para trabajos masivos |
| Crear sin Idempotency-Key | Establezca siempre un UUID por creación lógica |
| Patch sin If-Match | GET primero; envíe ETag |
| Asumir que el código es la clave primaria de cursos | Resuelva código → id, luego use id |

## Preguntas frecuentes

**¿Puedo adaptar estas recetas a planes de estudios o salas?**

Sí — el sobre, la paginación, la autenticación, la idempotencia y las reglas ETag son compartidas. Sustituya rutas por el recurso que necesite desde las tarjetas de exploración de la descripción general (por ejemplo planes de estudios o salas) y confirme filtros en la página de referencia de ese endpoint.

**¿Las recetas sustituyen la referencia OpenAPI?**

No. Las recetas enseñan secuencias y convenciones. Los esquemas a nivel de campo están en las páginas de endpoints generadas como [Users](/docs/es/api/users/users/list-users) y [Courses](/docs/es/api/courses/courses/list-courses).

## Páginas relacionadas

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

Credenciales y primer GET.

**[Paginación y filtrado](/docs/es/api/pagination-and-filtering)**

Cursores, campos y filtros por código.

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

Reglas de 412, 429 e Idempotency-Key.

**[Descripción general de la API](/docs/es/api/overview)**

Explorar todos los grupos de referencia de recursos.
