Recetas
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 para que las credenciales funcionen.
- Lea Autenticación, Paginación y filtrado y Errores e idempotencia.
- Mantenga
CLIENT_IDyCLIENT_SECRETen el entorno; nunca los codifique en scripts que confirme.
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 como fuente de verdad de quién existe en Fuxam.
#!/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:
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
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.
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:
GET /api/v4/courses?code=CS101&limit=25 HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Accept: application/json
GET /api/v4/courses/{id} HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Accept: application/json
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.
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:
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
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.
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"
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 |
Receta: Manejar límites de tasa al paginar
Objetivo: Completar una sincronización grande sin fallar el trabajo al alcanzar 1000 solicitudes/min.
loop pages:
response = GET list
if status == 429:
sleep(Retry-After)
retry same request
process response.data
advance cursor
# 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.
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.requestIden 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).
- Tras codificar una receta, abra la tarjeta de referencia correspondiente en la sección de exploración de la descripción general 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.