Saltar al contenido
Esc
↑↓navegar↵abrir⌘Jvista previa
En esta página

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 incluyen pagination.next_cursor, pagination.has_more y pagination.limit. Sin offsets.
  • Errores RFC 7807 (application/problem+json) con un code de 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 GET incluyen un ETag fuerte; envíelo de vuelta como If-Match en PATCH, PUT o DELETE.

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 code de nivel superior es la unión cerrada ApiErrorCode — legible por máquina y estable.
  • Cada entrada en errors[].code es un código de incidencia Zod (p. ej. invalid_string) con un pointer RFC-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ía If-Match pero 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.

Por dónde empezar

  1. Siga Primeros pasos para crear credenciales y llamar a GET /users.
  2. Lea Autenticación antes de almacenar secretos en producción.
  3. Use Paginación y filtrado cuando necesite recorrer colecciones grandes.
  4. Aplique Errores e idempotencia antes de cualquier automatización de creación o actualización.
  5. 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

Courses

Academics

Facilities

Registro de tiempo

Directory

¿Te ha resultado útil esta página?