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

Primeros pasos

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 para seguridad de credenciales, Descripción general para el resumen completo de convenciones y User Management para cómo aparecen los usuarios en la interfaz del producto.

Cómo crear una integración

En Fuxam Web, abra Organization → API integrations.

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.

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.

Cómo construir el encabezado Authorization

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

Authorization: Basic <base64(clientId:clientSecret)>

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

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"

Cómo hacer su primera solicitud

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

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

HTTP en bruto equivalente:

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:

{
  "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:

curl -sS \
  -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -H "Accept: application/json" \
  "https://fuxam.app/api/v4/users?limit=25&cursor=${NEXT_CURSOR}"
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.

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.
  • Cuando esté listo para escribir, siga Errores e idempotencia y los patrones de Recetas.

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
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 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

¿Te ha resultado útil esta página?