API de Fuxam v4
API REST estándar del sector para integrarse con la plataforma Fuxam — autenticación, paginación, errores y referencia de endpoints.
La API de Fuxam v4 es una API REST versionada que permite a su institución conectar sistemas de información estudiantil, proveedores de identidad, herramientas de informes y middleware personalizado a los mismos datos que su personal gestiona en Fuxam Web. Cada endpoint comparte un conjunto de convenciones para autenticación, forma de respuesta, paginación, errores y concurrencia; una vez aprendidos los patrones en esta página, puede aplicarlos a usuarios, cursos, planes de estudios y el resto del catálogo de recursos.
URL base: https://fuxam.app/api/v4
Por qué integran las instituciones
Las universidades rara vez funcionan con un solo sistema. Las admisiones pueden estar en un producto, RR. HH. en otro y la plataforma de aprendizaje en un tercero. La API de Fuxam existe para que esos sistemas intercambien datos autoritativos sin entrada duplicada:
- Aprovisionar y sincronizar identidades con los mismos usuarios que sus administradores gestionan en User Management.
- Leer y actualizar la estructura académica — cursos, módulos, planes de estudios, programas de estudios y periodos — alineados con FuxamCMS y FuxamLMS.
- Automatizar flujos operativos como búsquedas de salas, datos de citas y lecturas de progreso que de otro modo requerirían exportación manual.
La integración tiene ámbito de institución: las credenciales que crea en Organization → API integrations autentican como integración de esa institución, no como un usuario del personal individual.
Cómo encaja en Fuxam
La API es la superficie programática de conceptos que ya conoce del manual web. Un usuario en la API es la misma identidad que en User Management; un id de curso apunta al mismo curso que el personal abre en Courses Management o el LMS.
| Área de recursos de la API | Temas relacionados del manual web |
|---|---|
| Usuarios, roles, grupos de usuarios | User Management, Roles and permissions, User groups |
| Cursos, bloques de contenido, progreso | Courses Management, LMS courses, Content |
| Módulos, planes de estudios, programas de estudios, periodos | Academic structure, Study programs and cohorts |
| Salas, citas | Rooms, Calendar |
Conceptos clave
| Concepto | Significado |
|---|---|
| Integration | Cliente API registrado en Organization → API integrations, con clientId y clientSecret. |
| Response envelope | Las respuestas exitosas envuelven la carga en { data, meta } (recurso único) o { data, pagination, meta } (listas). |
| Cursor pagination | Paginación por keyset con ?limit= y ?cursor= — nunca basada en offset/page. |
| Sparse fieldsets | ?fields= opcional para solicitar solo las propiedades necesarias. |
| Problem details | Los errores usan RFC 7807 application/problem+json con un code estable legible por máquina. |
| Idempotency | Las solicitudes de creación (POST) pueden enviar Idempotency-Key para evitar recursos duplicados al reintentar. |
| Optimistic concurrency | Las escrituras de un solo recurso usan ETag / If-Match para que las actualizaciones concurrentes no se sobrescriban en silencio. |
Convenciones de un vistazo
- Un sobre de respuesta en todas partes:
{ data, meta }para un recurso,{ data, pagination, meta }para listas. - Paginación por cursor:
?limit=&cursor=; las respuestas incluyenpagination.next_cursor,pagination.has_moreypagination.limit. Sin offsets. - Errores RFC 7807 (
application/problem+json) con uncodede nivel superior estable y legible por máquina. - Creaciones idempotentes mediante el encabezado
Idempotency-Key. - Conjuntos de campos dispersos con
?fields=id,email,…. - Concurrencia optimista en escrituras de un solo recurso: las respuestas
GETincluyen unETagfuerte; envíelo de vuelta comoIf-MatchenPATCH,PUToDELETE.
Cada respuesta incluye un objeto meta con requestId, timestamp y version ("v4").
Flujo de solicitud típico
Autenticación
Todas las solicitudes usan HTTP Basic Auth con las credenciales de su integración (clientId:clientSecret, codificado en Base64):
Authorization: Basic <base64(clientId:clientSecret)>
Cree una integración en Organization → API integrations para obtener su clientId y clientSecret. Los ámbitos de permisos de clave API no están implementados en v4 — Basic Auth es todo o nada para la integración.
Para un recorrido completo del manejo de credenciales y la práctica de seguridad, consulte Autenticación.
Sobre de respuesta
Recurso único:
{
"data": { "id": "usr_123", "email": "user@example.com" },
"meta": {
"requestId": "req_1700000000000_abc123",
"timestamp": "2026-01-15T10:30:00.000Z",
"version": "v4"
}
}
Lista (con paginación por cursor):
{
"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"
}
}
Use ?fields= para solicitar un conjunto de campos disperso en endpoints compatibles. Detalles y ejemplos de bucle en Paginación y filtrado.
Paginación por cursor
Los endpoints de lista aceptan parámetros de consulta ?limit= (1–100) y ?cursor=:
| Parámetro | Descripción |
|---|---|
limit |
Tamaño de página (1–100; se aplica el valor por defecto del servidor si se omite) |
cursor |
Cursor opaco del pagination.next_cursor de la página anterior |
Los cursores están firmados con HMAC y ligados a su institución e integración. Cursores manipulados o ajenos devuelven 400 con código invalid_cursor. La paginación usa cursores keyset sobre (sortField, id) — nunca paginación basada en offset.
Cuando pagination.has_more es false, ha llegado a la última página.
Modelo de errores (RFC 7807)
Todos los errores usan application/problem+json con type como URI https://fuxam.app/errors/{code}.
Hay dos espacios de nombres code distintos:
- El
codede nivel superior es la unión cerradaApiErrorCode— legible por máquina y estable. - Cada entrada en
errors[].codees un código de incidencia Zod (p. ej.invalid_string) con unpointerRFC-6901 (p. ej./email).
{
"type": "https://fuxam.app/errors/resource_not_found",
"title": "Not Found",
"status": 404,
"code": "resource_not_found"
}
v4 no emite 403. El acceso entre inquilinos devuelve el mismo 404 resource_not_found que un recurso realmente inexistente — nunca se filtra la existencia. Los fallos de validación devuelven HTTP 422.
Códigos de estado habituales: 200 lectura/actualización, 201 creado, 204 eliminado, 409 conflicto o bloqueo de idempotencia en curso, 412 desajuste de ETag, 428 falta If-Match requerido, 429 límite de tasa (respete Retry-After).
La cobertura profunda de manejo de errores, idempotencia, concurrencia y límites de tasa está en Errores e idempotencia.
Idempotencia
Las solicitudes POST que crean recursos aceptan un encabezado Idempotency-Key. Enviar la misma clave dos veces dentro de la ventana de idempotencia devuelve la respuesta en caché (incluido el 201 original) sin crear un duplicado. Claves en conflicto en curso pueden devolver 409.
Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Concurrencia optimista
Los GET de un solo recurso emiten un ETag fuerte. Envíelo de vuelta como If-Match en PATCH, PUT o DELETE:
- 412
precondition_failed— el recurso cambió desde que lo leyó. - 428
precondition_required— se requeríaIf-Matchpero faltaba.
Límites de tasa
Cada integración comparte un presupuesto de 1000 solicitudes/min (ventana deslizante, clave integración + institución). Las respuestas incluyen encabezados RateLimit-*; las respuestas 429 incluyen Retry-After.
En esta sección
Empiece con las guías siguientes y use las tarjetas de recursos para la referencia de endpoints.
Primeros pasos
Cree una integración, autentíquese y haga su primera solicitud de lista.
Autenticación
Basic Auth, credenciales, rotación y práctica de seguridad.
Paginación y filtrado
Cursores, conjuntos de campos dispersos y patrones de filtrado.
Errores e idempotencia
Detalles de problemas, reintentos, ETags y límites de tasa.
Recetas
Patrones de extremo a extremo para sincronización, búsqueda y escrituras seguras.
Por dónde empezar
- Siga Primeros pasos para crear credenciales y llamar a
GET /users. - Lea Autenticación antes de almacenar secretos en producción.
- Use Paginación y filtrado cuando necesite recorrer colecciones grandes.
- Aplique Errores e idempotencia antes de cualquier automatización de creación o actualización.
- Copie un patrón de Recetas y abra la referencia de endpoint correspondiente abajo.
Explorar por recurso
Las páginas de referencia de endpoints se agrupan por etiqueta de recurso, organizadas en las secciones siguientes. Estas rutas se generan desde la especificación OpenAPI.
Users
Users
Perfiles de usuario, pertenencia, ciclo de vida, datos de contacto
Roles
Roles de institución y asignaciones de rol de usuario
Courses
Courses
Cursos (direccionados por id; filtrar por código)
Content Blocks
Bloques de contenido del curso
Workbenches
Workbenches del curso
User Progress
Progreso del usuario en bloques de contenido
Appointments
Citas y reservas de salas
Academics
Course Modules
Módulos de curso, versiones y grupos
Curricula
Planes de estudios, versiones y estructura anidada
Study Programs
Programas de estudios, versiones, cohortes
Organization Terms
Cronología de periodos académicos
Cohortes
Cohortes dentro de programas de estudio