---
icon: house
title: API de Fuxam v4
sidebar:
  label: Introducción
  order: 0
description: 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](/docs/es/fuxam-web/base/user-management).
- **Leer y actualizar la estructura académica** — cursos, módulos, planes de estudios, programas de estudios y periodos — alineados con [FuxamCMS](/docs/es/fuxam-web/cms) y [FuxamLMS](/docs/es/fuxam-web/lms).
- **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.

```mermaid
flowchart LR
  External[Sistemas externos] --> API[Fuxam API v4]
  API --> Data[Usuarios cursos academicos instalaciones]
  Data --> Web[Fuxam Web]
```

| Área de recursos de la API | Temas relacionados del manual web |
|---|---|
| Usuarios, roles, grupos de usuarios | [User Management](/docs/es/fuxam-web/base/user-management), [Roles and permissions](/docs/es/fuxam-web/base/user-management/roles-and-permissions), [User groups](/docs/es/fuxam-web/base/user-management/user-groups) |
| Cursos, bloques de contenido, progreso | [Courses Management](/docs/es/fuxam-web/cms/courses-management), [LMS courses](/docs/es/fuxam-web/lms/courses), [Content](/docs/es/fuxam-web/lms/content) |
| Módulos, planes de estudios, programas de estudios, periodos | [Academic structure](/docs/es/fuxam-web/cms/academic-structure), [Study programs and cohorts](/docs/es/fuxam-web/cms/programs-and-planning/study-programs-cohorts) |
| Salas, citas | [Rooms](/docs/es/fuxam-web/cms/academic-structure/rooms), [Calendar](/docs/es/fuxam-web/base/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

```mermaid
sequenceDiagram
  participant Client
  participant API as Fuxam API v4
  Client->>API: GET con Basic Auth
  API-->>Client: 200 data meta y ETag
  Client->>API: PATCH con If-Match y cuerpo
  alt ETag coincide
    API-->>Client: 200 recurso actualizado
  else ETag obsoleto
    API-->>Client: 412 precondition failed
  end
```

## Autenticación

Todas las solicitudes usan **HTTP Basic Auth** con las credenciales de su integración (`clientId:clientSecret`, codificado en Base64):

```http
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](/docs/es/api/authentication).

## Sobre de respuesta

Recurso único:

```json
{
  "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):

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

Use `?fields=` para solicitar un conjunto de campos disperso en endpoints compatibles. Detalles y ejemplos de bucle en [Paginación y filtrado](/docs/es/api/pagination-and-filtering).

## 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`).

```json
{
  "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](/docs/es/api/errors-and-idempotency).

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

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

:::info
**Migración desde v3:** Ruta base `/api/v3` → `/api/v4`. Los cursos se direccionan por **id** (busque por código con `GET /courses?code=…`). Las listas usan `cursor`/`limit` en lugar de `page`/`pageSize`. Los cuerpos de lista son siempre `{ data: [...] }`. Los errores incluyen un `code` estable; los fallos de validación son `422`.
:::

## En esta sección

Empiece con las guías siguientes y use las tarjetas de recursos para la referencia de endpoints.

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

Cree una integración, autentíquese y haga su primera solicitud de lista.

**[Autenticación](/docs/es/api/authentication)**

Basic Auth, credenciales, rotación y práctica de seguridad.

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

Cursores, conjuntos de campos dispersos y patrones de filtrado.

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

Detalles de problemas, reintentos, ETags y límites de tasa.

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

Patrones de extremo a extremo para sincronización, búsqueda y escrituras seguras.

## Por dónde empezar

1. Siga [Primeros pasos](/docs/es/api/getting-started) para crear credenciales y llamar a `GET /users`.
2. Lea [Autenticación](/docs/es/api/authentication) antes de almacenar secretos en producción.
3. Use [Paginación y filtrado](/docs/es/api/pagination-and-filtering) cuando necesite recorrer colecciones grandes.
4. Aplique [Errores e idempotencia](/docs/es/api/errors-and-idempotency) antes de cualquier automatización de creación o actualización.
5. Copie un patrón de [Recetas](/docs/es/api/recipes) 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](/docs/es/api/users/users/list-users)**

Perfiles de usuario, pertenencia, ciclo de vida, datos de contacto

**[Roles](/docs/es/api/users/users-roles-access/list-roles)**

Roles de institución y asignaciones de rol de usuario

### Courses

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

Cursos (direccionados por id; filtrar por código)

**[Content Blocks](/docs/es/api/courses/courses-content-blocks/list-content-blocks)**

Bloques de contenido del curso

**[Workbenches](/docs/es/api/courses/courses-workbenches/list-workbenches)**

Workbenches del curso

**[User Progress](/docs/es/api/courses/courses-user-progress/get-user-progress)**

Progreso del usuario en bloques de contenido

**[Appointments](/docs/es/api/appointments/appointments/list-appointments)**

Citas y reservas de salas

### Academics

**[Course Modules](/docs/es/api/campus-management/campus-management-modules/list-modules)**

Módulos de curso, versiones y grupos

**[Curricula](/docs/es/api/campus-management/campus-management-curricula/list-curricula)**

Planes de estudios, versiones y estructura anidada

**[Study Programs](/docs/es/api/campus-management/campus-management-study-programs/list-study-programs)**

Programas de estudios, versiones, cohortes

**[Organization Terms](/docs/es/api/campus-management/campus-management-organization-terms/list-organization-terms)**

Cronología de periodos académicos

**[Cohortes](/docs/es/api/campus-management/campus-management-cohorts/list-cohorts)**

Cohortes dentro de programas de estudio

### Facilities

**[Rooms](/docs/es/api/room-management/room-management/list-rooms)**

Salas, configuraciones, ubicaciones, servicios

### Registro de tiempo

**[Registro de tiempo](/docs/es/api/time-tracking/time-tracking/list-time-tracking-logs)**

Sesiones, registros y plantillas de marcas de tiempo

### Directory

**[User Groups](/docs/es/api/users/users-user-groups/list-user-groups)**

Grupos de usuarios del directorio y pertenencias
