---
icon: rocket
title: Primeros pasos
description: Cree una integración de la API de Fuxam v4, configure Basic Auth, llame a GET /users, lea el sobre de respuesta y pagine su primera lista.
---

Esta guía le lleva de cero a una solicitud autenticada que funciona contra la API de Fuxam v4. Al final habrá creado una integración, construido un encabezado `Authorization`, llamado a `GET /users`, interpretado el sobre `{ data, meta }` y obtenido una segunda página con un cursor.

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

## Por qué importa

Una primera llamada exitosa demuestra tres cosas a la vez: sus credenciales funcionan, su ruta de red a `fuxam.app` está abierta y su cliente interpreta correctamente la forma de respuesta compartida. Acertar esos fundamentos pronto evita horas de depuración cuando más adelante añada escrituras, reintentos y trabajos de sincronización multipágina.

## Antes de empezar

Necesita:

- Acceso a los ajustes de organización de Fuxam Web de su institución para crear una integración de API.
- Una terminal con `curl` (o cualquier cliente HTTP que pueda enviar Basic Auth).
- Un lugar seguro para almacenar el `clientSecret` — trátelo como una contraseña.

Lectura relacionada: [Autenticación](/docs/es/api/authentication) para seguridad de credenciales, [Descripción general](/docs/es/api/overview) para el resumen completo de convenciones y [User Management](/docs/es/fuxam-web/base/user-management) para cómo aparecen los usuarios en la interfaz del producto.

```mermaid
flowchart LR
  Create[Crear integracion] --> Auth[Configurar Basic Auth]
  Auth --> Call[GET users]
  Call --> Read[Leer data y meta]
  Read --> Page[Paginar con cursor]
```

## Cómo crear una integración

1. En Fuxam Web, abra **Organization → API integrations**.

2. Cree una nueva integración y anote el `clientId` y el `clientSecret` cuando se muestren. Guarde el secreto de inmediato — lo necesitará en cada solicitud.

3. Confirme que la integración está activa para su institución antes de hacer llamadas. Las credenciales tienen ámbito de institución; solo ven los datos de esa institución.

:::warning[Proteja el client secret]
Cualquiera con `clientId` y `clientSecret` puede llamar a la API como su integración. Basic Auth de v4 es todo o nada — no hay ámbitos de permisos. Consulte [Autenticación](/docs/es/api/authentication).
:::

## Cómo construir el encabezado Authorization

HTTP Basic Auth codifica `clientId:clientSecret` en Base64 y lo envía en el encabezado `Authorization`:

```http
Authorization: Basic <base64(clientId:clientSecret)>
```

Genere el valor con su shell (sustituya los marcadores):

```bash
CLIENT_ID="your_client_id"
CLIENT_SECRET="your_client_secret"
AUTH=$(printf '%s:%s' "$CLIENT_ID" "$CLIENT_SECRET" | base64 | tr -d '\n')
echo "Authorization: Basic $AUTH"
```

:::tip
Prefiera que su biblioteca HTTP configure Basic Auth desde usuario/contraseña en lugar de codificar Base64 a mano cuando vaya más allá de `curl`. Las bibliotecas manejan el relleno y la codificación de caracteres de forma coherente.
:::

## Cómo hacer su primera solicitud

Liste usuarios con `GET /users`. Es una llamada de solo lectura segura y una buena prueba de humo.

```bash
curl -sS \
  -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -H "Accept: application/json" \
  "https://fuxam.app/api/v4/users?limit=25"
```

HTTP en bruto equivalente:

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

Una respuesta exitosa se parece a:

```json
{
  "data": [
    { "id": "usr_123", "email": "user@example.com" },
    { "id": "usr_456", "email": "another@example.com" }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6MTIzfQ==",
    "has_more": true,
    "limit": 25
  },
  "meta": {
    "requestId": "req_1700000000000_abc123",
    "timestamp": "2026-01-15T10:30:00.000Z",
    "version": "v4"
  }
}
```

### Lectura del sobre

| Campo | Función |
|---|---|
| `data` | El recurso o la lista de recursos. En listas siempre es un array. |
| `pagination` | Presente en respuestas de lista: `next_cursor`, `has_more`, `limit`. |
| `meta.requestId` | Correlacione esta respuesta con los registros del servidor al solucionar problemas. |
| `meta.timestamp` | Hora del servidor para la respuesta. |
| `meta.version` | Siempre `"v4"` en esta API. |

Conserve `meta.requestId` cuando abra un ticket de soporte — es la forma más rápida de localizar la solicitud.

## Cómo paginar

Si `pagination.has_more` es `true`, solicite la página siguiente con el valor opaco `next_cursor`:

```bash
curl -sS \
  -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -H "Accept: application/json" \
  "https://fuxam.app/api/v4/users?limit=25&cursor=${NEXT_CURSOR}"
```

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

Deténgase cuando `has_more` sea `false`. No invente ni edite cursores — están firmados con HMAC y ligados a su institución e integración. Un cursor incorrecto devuelve `400` con código `invalid_cursor`.

Los detalles completos (incluido un bucle para recorrer todas las páginas) están en [Paginación y filtrado](/docs/es/api/pagination-and-filtering).

## Lista de comprobación tras la primera llamada

| Comprobación | Esperado |
|---|---|
| Estado HTTP | `200` |
| Forma del cuerpo | Array `data` más `meta` (y normalmente `pagination`) |
| `meta.version` | `"v4"` |
| Fallo de autenticación | `401` si las credenciales son incorrectas — regenere o vuelva a copiar el secreto |
| `data` vacío | Válido si su institución aún no tiene usuarios coincidentes |

## Buenas prácticas para las primeras integraciones

- Empiece con **lecturas de listas** (`GET /users`, `GET /courses`) antes de cualquier creación o actualización.
- Registre `meta.requestId` en cada respuesta en su cliente de integración.
- Use un `limit` modesto (por ejemplo `25`) mientras desarrolla; súbalo hacia `100` solo al sincronizar a escala.
- Almacene credenciales en un gestor de secretos, no en el control de versiones. Consulte [Autenticación](/docs/es/api/authentication).
- Cuando esté listo para escribir, siga [Errores e idempotencia](/docs/es/api/errors-and-idempotency) y los patrones de [Recetas](/docs/es/api/recipes).

## Errores frecuentes

| Síntoma | Causa probable | Qué hacer |
|---|---|---|
| `401` Unauthorized | `clientId`/`clientSecret` incorrectos o Base64 dañado | Vuelva a copiar credenciales; use `-u` con `curl` en lugar de codificar a mano |
| Array `data` vacío | Sin recursos coincidentes o filtros inesperados | Confirme que existen usuarios en [User Management](/docs/es/fuxam-web/base/user-management) |
| `400` `invalid_cursor` | Cursor reutilizado entre integraciones o editado | Inicie una lista nueva desde la primera página |
| El cliente solo interpreta `data` | Ignora `pagination` / `meta` | Modele el sobre completo en sus tipos |

## Preguntas frecuentes

**¿Qué endpoint debo llamar primero?**

`GET /users` es una prueba de humo fiable: es de solo lectura y devuelve el sobre de lista estándar. Abra la referencia [Users](/docs/es/api/users/users/list-users) para los detalles completos de la operación.

**¿Necesito una URL base distinta para staging?**

Este manual documenta la URL base de producción `https://fuxam.app/api/v4`. Use el host y la ruta que su institución le haya indicado para cualquier entorno que no sea producción.

**¿Puedo restringir una integración a solo lectura?**

Basic Auth de v4 es todo o nada para la integración — los ámbitos de permisos de clave API no están implementados. Controle el acceso por quién puede crear integraciones y por lo que su código cliente puede invocar.

## Páginas relacionadas

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

Credenciales, rotación y práctica de seguridad.

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

Cursores, campos y filtros en profundidad.

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

Convenciones e índice por recurso.

**[Referencia de Users](/docs/es/api/users/users/list-users)**

Referencia de endpoint generada para usuarios.
