Aller au contenu principal

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 :

CodeSignification
AUTH_INVALID_CREDENTIALSE-mail ou mot de passe incorrect
AUTH_TOKEN_EXPIREDLe 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_PERMISSIONSVotre rôle ne permet pas cette action
BOOKING_CLASS_FULLAucune place disponible dans le cours
BOOKING_ALREADY_EXISTSLe client est déjà inscrit à ce cours
BOOKING_NO_MEMBERSHIPLe client n'a aucun abonnement actif ni crédit (également utilisé pour la réservation de rendez-vous)
BOOKING_CANCELLATION_WINDOW_PASSEDTrop proche du début du cours pour annuler
CHECKIN_NO_BOOKINGAucune réservation confirmée trouvée pour ce client et ce cours
CHECKIN_OUTSIDE_WINDOWHors de la fenêtre horaire de check-in
CHECKIN_ALREADY_CHECKED_INLe client a déjà effectué son check-in
WAIVER_SIGNATURE_REQUIREDLe client a une décharge obligatoire non signée et ne peut pas réserver
APPOINTMENT_SERVICE_INACTIVELe service de rendez-vous demandé a été désactivé
APPOINTMENT_INSTRUCTOR_INACTIVELe compte de l'instructeur demandé n'est pas actif
APPOINTMENT_IN_PASTL'heure de début du rendez-vous demandé est passée
APPOINTMENT_OUTSIDE_AVAILABILITYL'horaire demandé est hors des disponibilités de l'instructeur
APPOINTMENT_SLOT_CONFLICTL'horaire demandé chevauche un autre rendez-vous confirmé (y compris le temps tampon)
APPOINTMENT_ALREADY_CANCELLEDLe rendez-vous n'est pas dans un état confirmé et ne peut pas être annulé à nouveau
APPOINTMENT_NOT_CONFIRMEDLe rendez-vous doit être confirmé pour être marqué comme terminé ou comme absence
CHECKOUT_INVALID_REDIRECT_URLUn 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_FOUNDLa ressource demandée n'existe pas
VALIDATION_ERRORLe corps de la requête ne contient pas les champs requis ou contient des valeurs invalides

Codes d'erreur de l'Assistant IA :

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


Pages associées​