Referencia de la API
Agon expone una API REST que usan la aplicación de escritorio, la aplicación móvil y el widget público de reservas del sitio web. Si eres desarrollador y quieres integrarte con Agon o construir algo sobre él, esta página explica lo básico.
URL base
La API funciona localmente en el ordenador del studio manager:
http://localhost:8000
Cuando los clientes se conectan desde fuera (mediante la aplicación móvil o el widget del sitio web), usan la URL del Cloudflare Tunnel con nombre del estudio, que tiene este aspecto:
https://studio-<id>.tunnel.agon-studio.dev
Todos los endpoints están versionados bajo /api/v1/. Por ejemplo:
http://localhost:8000/api/v1/clients
Esta página trata sobre el backend, que funciona localmente en el ordenador de cada estudio. No existe una API central de Agon: el servidor de licencias y el proxy de IA alojado ya no existen, y el Asistente IA llama directamente al proveedor de IA configurado por el estudio (ver Studio → Configuración del Asistente IA).
Autenticación
Todos los endpoints protegidos requieren un token de acceso JWT válido en la cabecera Authorization:
Authorization: Bearer <your_access_token>
Para obtener un token, envía una petición POST a /api/v1/auth/login con tu correo y contraseña:
{
"email": "manager@mystudio.com",
"password": "your-password"
}
La respuesta incluye un access_token (válido 8 horas para escritorio, 30 días para móvil) y un refresh_token.
Cuentas desactivadas
Un token de acceso deja de funcionar en el momento en que su cuenta se desactiva: no sigue
siendo válido hasta que caduca. Cada petición vuelve a leer la cuenta, así que un miembro del
personal desactivado, o un cliente cuyo registro se ha desactivado o borrado
(DELETE /api/v1/clients/{client_id}), recibe 401 AUTH_TOKEN_INVALID en la siguiente llamada,
en cualquier endpoint. POST /api/v1/auth/refresh también rechaza el token de refresco, por lo
que no hay forma de volver a entrar sin iniciar sesión de nuevo.
Trata este 401 como cualquier otro: deja de usar el token y devuelve al usuario a la pantalla de inicio de sesión. No es reintentable, y renovar el token no lo soluciona.
Cuando el token de acceso caduca, envía el token de refresco a POST /api/v1/auth/refresh para obtener un nuevo token de acceso sin volver a iniciar sesión.
Cambiar la contraseña cierra las sesiones abiertas
Restablecer o cambiar la contraseña de una cuenta invalida todos los tokens ya emitidos para ella
— incluido el token de refresco, que de otro modo sobrevive meses al token de acceso. Quien
conserve un token antiguo recibe 401 AUTH_TOKEN_INVALID en la siguiente llamada, y
POST /api/v1/auth/refresh también rechaza el token de refresco antiguo.
Se aplica a POST /api/v1/auth/reset-password, POST /api/v1/auth/manager/recover-with-code y a
una contraseña establecida mediante PUT /api/v1/staff/{staff_id}. Incluye la cuenta que hace el
cambio: si restableces tu propia contraseña, también se cierra tu sesión y tienes que volver a
entrar con la nueva.
Formato de respuesta
Todos los endpoints devuelven JSON. Las respuestas correctas devuelven directamente los datos solicitados.
Ejemplo de respuesta correcta:
{
"id": 42,
"full_name": "Jane Smith",
"email": "jane@example.com",
"status": "active"
}
Formato de error
Todas las respuestas de error siguen esta estructura:
{
"error": {
"code": "BOOKING_CLASS_FULL",
"message": "This class is full. Would you like to join the waitlist?",
"details": {}
}
}
Códigos de error comunes:
| Código | Significado |
|---|---|
AUTH_INVALID_CREDENTIALS | Correo o contraseña incorrectos |
AUTH_TOKEN_EXPIRED | El token de acceso ha caducado — renuévalo |
AUTH_TOKEN_INVALID | (401) El token está mal formado, es del tipo equivocado, o pertenece a una cuenta que ya no existe o ha sido desactivada — ver Cuentas desactivadas. No reintentes; inicia sesión de nuevo |
CLIENT_INACTIVE | (409) Un miembro del personal intentó actuar en nombre de un cliente desactivado. Un cliente desactivado que actúa por sí mismo recibe AUTH_TOKEN_INVALID |
AUTH_INSUFFICIENT_PERMISSIONS | Tu rol no permite esta acción |
BOOKING_CLASS_FULL | No hay plazas disponibles en la clase |
BOOKING_ALREADY_EXISTS | El cliente ya tiene una reserva para esta clase |
BOOKING_NO_MEMBERSHIP | El cliente no tiene una membresía activa ni créditos (también se usa para la reserva de citas) |
BOOKING_CANCELLATION_WINDOW_PASSED | Demasiado cerca del inicio de la clase para cancelar |
CHECKIN_NO_BOOKING | No se encontró ninguna reserva confirmada para este cliente y esta clase |
CHECKIN_OUTSIDE_WINDOW | Fuera de la ventana horaria de check-in |
CHECKIN_ALREADY_CHECKED_IN | El cliente ya ha hecho el check-in |
WAIVER_SIGNATURE_REQUIRED | El cliente tiene un descargo de responsabilidad obligatorio sin firmar y no puede reservar |
APPOINTMENT_SERVICE_INACTIVE | El servicio de cita solicitado ha sido desactivado |
APPOINTMENT_INSTRUCTOR_INACTIVE | La cuenta del instructor solicitado no está activa |
APPOINTMENT_IN_PAST | La hora de inicio de la cita solicitada ya pasó |
APPOINTMENT_OUTSIDE_AVAILABILITY | La hora solicitada queda fuera de la disponibilidad del instructor |
APPOINTMENT_SLOT_CONFLICT | La hora solicitada se solapa con otra cita confirmada (incluido el tiempo de margen) |
APPOINTMENT_ALREADY_CANCELLED | La cita no está en un estado confirmado y no se puede cancelar de nuevo |
APPOINTMENT_NOT_CONFIRMED | La cita debe estar confirmada para marcarse como completada o como no presentado |
CHECKOUT_INVALID_REDIRECT_URL | Un success_url o cancel_url del checkout no es un destino de redirección permitido (el esquema de deep link agon://, el origen del widget, la URL del túnel del estudio o una dirección de loopback) |
NOT_FOUND | El recurso solicitado no existe |
VALIDATION_ERROR | Al cuerpo de la petición le faltan campos obligatorios o tiene valores no válidos |
Códigos de error del Asistente IA:
| Código | Significado |
|---|---|
AI_NOT_CONFIGURED | (409) Se continuó una acción de IA pero no hay ningún proveedor de IA configurado — el asistente está en modo básico. Añade una clave de proveedor en Configuración → Asistente IA |
AI_RATE_LIMITED | (429) El proveedor de IA del estudio está limitando las peticiones. details.docs_url apunta a Si esperas un uso intenso |
AI_KEY_INVALID | (400) El proveedor rechazó la clave de API enviada a POST /studio/ai |
AI_INVALID_PROVIDER | (422) El proveedor enviado a POST /studio/ai no está entre los de GET /studio/ai/providers |
Documentación interactiva (Swagger UI)
La API de Agon incluye documentación interactiva basada en Swagger UI. Cuando Agon esté en ejecución, abre esta URL en tu navegador:
http://localhost:8000/docs
La Swagger UI te permite explorar todos los endpoints disponibles, ver sus parámetros y formatos de respuesta, y hacer peticiones de prueba directamente desde tu navegador.
También hay disponible una vista OpenAPI alternativa (ReDoc) en:
http://localhost:8000/redoc
Versionado de la API
Todos los endpoints actuales están bajo /api/v1/. Cuando se introduzcan cambios incompatibles en una futura versión, estarán disponibles bajo /api/v2/, mientras /api/v1/ seguirá activo durante un período de transición.