Référence API
Agon expose une API REST utilisée à la fois par l'application de bureau, l'application mobile et le widget public de réservation du site web. Si vous êtes développeur et souhaitez intégrer Agon ou construire quelque chose au-dessus, cette page explique les bases.
URL de base
L'API fonctionne localement sur l'ordinateur du studio manager :
http://localhost:8000
Lorsque les clients se connectent depuis l'extérieur (via l'application mobile ou le widget du site web), ils utilisent l'URL du Cloudflare Tunnel nommé du studio, qui ressemble à :
https://studio-<id>.tunnel.agon-studio.dev
Tous les points de terminaison sont versionnés sous /api/v1/. Par exemple :
http://localhost:8000/api/v1/clients
Cette page couvre le backend, qui fonctionne localement sur l'ordinateur de chaque studio. Il n'existe pas d'API Agon centrale : le service de licences et le proxy IA hébergé n'existent plus, et l'Assistant IA appelle directement le fournisseur d'IA configuré par le studio (voir Studio → Configuration de l'Assistant IA).
Authentification
Tous les points de terminaison protégés exigent un jeton d'accès JWT valide dans l'en-tête Authorization :
Authorization: Bearer <your_access_token>
Pour obtenir un jeton, envoyez une requête POST à /api/v1/auth/login avec votre e-mail et votre mot de passe :
{
"email": "manager@mystudio.com",
"password": "your-password"
}
La réponse inclut un access_token (valide 8 heures pour le bureau, 30 jours pour le mobile) et un refresh_token.
Comptes désactivés
Un jeton d'accès cesse de fonctionner dès que son compte est désactivé : il ne reste pas valide
jusqu'à son expiration. Chaque requête relit le compte, donc un membre du personnel désactivé,
ou un client dont la fiche a été désactivée ou effacée
(DELETE /api/v1/clients/{client_id}), reçoit 401 AUTH_TOKEN_INVALID dès l'appel suivant, sur
n'importe quel endpoint. POST /api/v1/auth/refresh refuse également le jeton de
rafraîchissement : il n'y a donc aucun moyen de revenir sans une nouvelle connexion.
Traitez ce 401 comme n'importe quel autre : cessez d'utiliser le jeton et renvoyez l'utilisateur vers l'écran de connexion. Il n'est pas réessayable, et le rafraîchissement n'y changera rien.
Lorsque le jeton d'accès expire, envoyez le jeton de rafraîchissement à POST /api/v1/auth/refresh pour obtenir un nouveau jeton d'accès sans vous reconnecter.
Changer un mot de passe met fin aux sessions en cours
Réinitialiser ou changer le mot de passe d'un compte invalide tous les jetons déjà émis pour lui
— y compris le jeton de rafraîchissement, qui survit sinon des mois au jeton d'accès. Quiconque
détient encore un ancien jeton reçoit 401 AUTH_TOKEN_INVALID dès l'appel suivant, et
POST /api/v1/auth/refresh refuse lui aussi l'ancien jeton de rafraîchissement.
Cela vaut pour POST /api/v1/auth/reset-password,
POST /api/v1/auth/manager/recover-with-code et pour un mot de passe défini via
PUT /api/v1/staff/{staff_id}. Le compte à l'origine du changement est inclus : si vous
réinitialisez votre propre mot de passe, vous êtes déconnecté et devez vous reconnecter avec le
nouveau.
Format de réponse
Tous les points de terminaison renvoient du JSON. Les réponses réussies renvoient directement les données demandées.
Exemple de réponse réussie :
{
"id": 42,
"full_name": "Jane Smith",
"email": "jane@example.com",
"status": "active"
}
Format d'erreur
Toutes les réponses d'erreur suivent cette structure :
{
"error": {
"code": "BOOKING_CLASS_FULL",
"message": "This class is full. Would you like to join the waitlist?",
"details": {}
}
}
Codes d'erreur courants :
| Code | Signification |
|---|---|
AUTH_INVALID_CREDENTIALS | E-mail ou mot de passe incorrect |
AUTH_TOKEN_EXPIRED | Le jeton d'accès a expiré — rafraîchissez-le |
AUTH_TOKEN_INVALID | (401) Le jeton est malformé, du mauvais type, ou appartient à un compte qui n'existe plus ou a été désactivé — voir Comptes désactivés. Ne réessayez pas ; reconnectez-vous |
CLIENT_INACTIVE | (409) Un membre du personnel a tenté d'agir pour le compte d'un client désactivé. Un client désactivé agissant pour lui-même reçoit AUTH_TOKEN_INVALID |
AUTH_INSUFFICIENT_PERMISSIONS | Votre rôle ne permet pas cette action |
BOOKING_CLASS_FULL | Aucune place disponible dans le cours |
BOOKING_ALREADY_EXISTS | Le client est déjà inscrit à ce cours |
BOOKING_NO_MEMBERSHIP | Le client n'a aucun abonnement actif ni crédit (également utilisé pour la réservation de rendez-vous) |
BOOKING_CANCELLATION_WINDOW_PASSED | Trop proche du début du cours pour annuler |
CHECKIN_NO_BOOKING | Aucune réservation confirmée trouvée pour ce client et ce cours |
CHECKIN_OUTSIDE_WINDOW | Hors de la fenêtre horaire de check-in |
CHECKIN_ALREADY_CHECKED_IN | Le client a déjà effectué son check-in |
WAIVER_SIGNATURE_REQUIRED | Le client a une décharge obligatoire non signée et ne peut pas réserver |
APPOINTMENT_SERVICE_INACTIVE | Le service de rendez-vous demandé a été désactivé |
APPOINTMENT_INSTRUCTOR_INACTIVE | Le compte de l'instructeur demandé n'est pas actif |
APPOINTMENT_IN_PAST | L'heure de début du rendez-vous demandé est passée |
APPOINTMENT_OUTSIDE_AVAILABILITY | L'horaire demandé est hors des disponibilités de l'instructeur |
APPOINTMENT_SLOT_CONFLICT | L'horaire demandé chevauche un autre rendez-vous confirmé (y compris le temps tampon) |
APPOINTMENT_ALREADY_CANCELLED | Le rendez-vous n'est pas dans un état confirmé et ne peut pas être annulé à nouveau |
APPOINTMENT_NOT_CONFIRMED | Le rendez-vous doit être confirmé pour être marqué comme terminé ou comme absence |
CHECKOUT_INVALID_REDIRECT_URL | Un success_url ou cancel_url du checkout n'est pas une destination de redirection autorisée (le schéma de lien profond agon://, l'origine du widget, l'URL du tunnel du studio ou une adresse de loopback) |
NOT_FOUND | La ressource demandée n'existe pas |
VALIDATION_ERROR | Le corps de la requête ne contient pas les champs requis ou contient des valeurs invalides |
Codes d'erreur de l'Assistant IA :
| Code | Signification |
|---|---|
AI_NOT_CONFIGURED | (409) Une action IA a été poursuivie mais aucun fournisseur d'IA n'est configuré — l'assistant est en mode de base. Ajoutez une clé de fournisseur dans Paramètres → Assistant IA |
AI_RATE_LIMITED | (429) Le fournisseur d'IA du studio limite les requêtes. details.docs_url pointe vers Si vous prévoyez un usage intensif |
AI_KEY_INVALID | (400) Le fournisseur a rejeté la clé API envoyée à POST /studio/ai |
AI_INVALID_PROVIDER | (422) Le fournisseur envoyé à POST /studio/ai ne figure pas dans GET /studio/ai/providers |
Documentation interactive (Swagger UI)
L'API d'Agon inclut une documentation interactive propulsée par Swagger UI. Lorsque Agon est en cours d'exécution, ouvrez cette URL dans votre navigateur :
http://localhost:8000/docs
La Swagger UI vous permet de parcourir tous les points de terminaison disponibles, de voir leurs paramètres et formats de réponse, et d'effectuer des requêtes de test directement depuis votre navigateur.
Une vue OpenAPI alternative (ReDoc) est également disponible à :
http://localhost:8000/redoc
Versionnement de l'API
Tous les points de terminaison actuels sont sous /api/v1/. Lorsque des changements non rétrocompatibles seront introduits dans une future version, ils seront disponibles sous /api/v2/, tandis que /api/v1/ restera actif pendant une période de transition.