Saltar al contenido principal

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ódigoSignificado
AUTH_INVALID_CREDENTIALSCorreo o contraseña incorrectos
AUTH_TOKEN_EXPIREDEl 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_PERMISSIONSTu rol no permite esta acción
BOOKING_CLASS_FULLNo hay plazas disponibles en la clase
BOOKING_ALREADY_EXISTSEl cliente ya tiene una reserva para esta clase
BOOKING_NO_MEMBERSHIPEl cliente no tiene una membresía activa ni créditos (también se usa para la reserva de citas)
BOOKING_CANCELLATION_WINDOW_PASSEDDemasiado cerca del inicio de la clase para cancelar
CHECKIN_NO_BOOKINGNo se encontró ninguna reserva confirmada para este cliente y esta clase
CHECKIN_OUTSIDE_WINDOWFuera de la ventana horaria de check-in
CHECKIN_ALREADY_CHECKED_INEl cliente ya ha hecho el check-in
WAIVER_SIGNATURE_REQUIREDEl cliente tiene un descargo de responsabilidad obligatorio sin firmar y no puede reservar
APPOINTMENT_SERVICE_INACTIVEEl servicio de cita solicitado ha sido desactivado
APPOINTMENT_INSTRUCTOR_INACTIVELa cuenta del instructor solicitado no está activa
APPOINTMENT_IN_PASTLa hora de inicio de la cita solicitada ya pasó
APPOINTMENT_OUTSIDE_AVAILABILITYLa hora solicitada queda fuera de la disponibilidad del instructor
APPOINTMENT_SLOT_CONFLICTLa hora solicitada se solapa con otra cita confirmada (incluido el tiempo de margen)
APPOINTMENT_ALREADY_CANCELLEDLa cita no está en un estado confirmado y no se puede cancelar de nuevo
APPOINTMENT_NOT_CONFIRMEDLa cita debe estar confirmada para marcarse como completada o como no presentado
CHECKOUT_INVALID_REDIRECT_URLUn 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_FOUNDEl recurso solicitado no existe
VALIDATION_ERRORAl cuerpo de la petición le faltan campos obligatorios o tiene valores no válidos

Códigos de error del Asistente IA:

CódigoSignificado
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.


Páginas relacionadas​