Instructions pour agents IA
Cette page est le point d'entrée rapide pour un agent IA (Claude Code, Cursor, OpenCode ou équivalent) chargé de construire une intégration partenaire avec l'API Resamania. Considère-la comme la source de vérité pour les conventions et les valeurs par défaut, et suis les pages liées pour le détail de chaque sujet.
Ce qu'est Resamania
Resamania (par Xplor Technologies) est un SaaS multi-tenant de gestion de clubs de sport/fitness : adhérents (CRM), contrôle d'accès, planning et réservation de cours, ventes en ligne, facturation (CB, SEPA, BACS) et campagnes marketing. L'API REST publique (sécurisée en OAuth2, Symfony / API Platform) est ce que documente ce site. L'application mobile adhérent s'appelle Xplor Active.
Faits non négociables
- Passe toujours par l'API Gateway. Depuis juin 2026, les appels directs à l'API Resamania ne sont plus supportés — toute requête passe par l'API Gateway. Voir API Gateway.
- Chaque URL est scopée par tenant. Les requêtes sont de la forme
https://{gateway_base_url}/{clientToken}/...— leclientTokenidentifie le client Resamania (club ou chaîne de clubs) avec lequel tu t'intègres. Ne l'invente jamais ; il est fourni lors de l'enregistrement de l'application partenaire. - Les identifiants sont des IRI, pas des nombres bruts. Référence les autres ressources par leur IRI complète (ex.
/{clientToken}/clubs/22), jamais par un simple entier. - En-têtes requis sur chaque appel :
authorization: Bearer {access_token},x-gravitee-api-key, etx-user-club-id. Ajoutex-user-network-node-iddès que le client exploite une chaîne de clubs. Détail complet : composantes d'une requête. - Appelle l'API uniquement depuis ton backend. L'API Resamania ne doit jamais être appelée directement depuis un navigateur ou une application mobile. C'est ton serveur qui détient les identifiants et parle à Resamania ; il n'expose ensuite que ce dont ton propre front a besoin. Voir Sécurité et responsabilités du partenaire.
client_credentialsest générique, pas personnalisé. Quandgrant_type=client_credentialsest utilisé, le token obtenu ne porte aucun contexte club/utilisateur implicite — chaque requête suivante effectuée avec ce token doit systématiquement définir à la foisx-user-club-idetx-user-network-node-id, même pour un client mono-club où le second en-tête est normalement optionnel. Voir la méthode "client_credentials".- Sandbox ≠ production. La sandbox ne contient que des données de test ; n'attends et ne demande jamais de vraies données adhérents dessus. L'accès en production n'est ouvert qu'après revue par l'équipe Resamania de tes appels en phase de test — voir Démarrage.
Choisir une méthode d'authentification
Resamania propose plusieurs grant types OAuth2 — le choix dépend de qui agit, pas d'une valeur par défaut :
| Grant type | À utiliser quand |
|---|---|
client_credentials | Accès serveur à serveur, non personnalisé (ton backend agissant pour lui-même) |
code | Un utilisateur final autorise ton application de façon interactive |
password | Tu collectes directement les identifiants d'un utilisateur final Resamania (usage legacy/limité) |
http://clubclientcredentials | Accès serveur à serveur scopé à un club précis |
http://contactclientcredentials | Accès pour le compte d'un contact/adhérent précis |
refresh_token | Renouveler une session existante sans ré-authentification |
Détail complet : Authentification.
Implémenter un workflow métier
N'improvise pas l'enchaînement des appels — chaque domaine a un ordre documenté et obligatoire. Lis la page correspondante avant d'écrire le code, pas après :
- Vendre à un adhérent existant : Vendre à un client existant — identifier le contact → vérifier la dette → récupérer le catalogue → créer le panier → ajouter les articles → vérifier la validité → encaisser le paiement.
- Contrat / mandat de prélèvement / signature électronique : Contrat, mandat, signature — mandat → affichage du contrat → demande de signature par SMS → validation de la signature.
- Inscription en ligne d'un nouvel adhérent : Inscription en ligne.
- Réserver un cours : Récupérer le planning, Réserver un cours.
- Résiliation : Résiliation en ligne.
- Chaînes de clubs / multi-club : Fonctionnement des chaînes de clubs.
Référence OpenAPI complète, une spec par domaine métier (catalogue, club, contact, comptabilité, vente, planning...) : API Reference.
Valeurs par défaut raisonnables quand le partenaire n'a pas précisé
- Préfère les webhooks au polling pour être notifié des changements (voir Webhooks) ; si tu dois quand même faire du polling, respecte la politique de rate limiting et applique un backoff sur les
429. - Traite les appels de création de paiement (
POST .../sales/{id}/payments) comme non idempotents et dangereux à rejouer sans précaution — un retry naïf après un timeout peut créer un paiement en double. Protège-toi explicitement contre ce cas. - Ne persiste ni ne logue jamais de données de carte, d'IBAN ou autres données de paiement au-delà de ce qui est strictement nécessaire au traitement en cours.
- Traite les données adhérents comme des données personnelles au sens RGPD / UK GDPR : ne collecte que ce dont l'intégration a besoin, et respecte le signal d'anonymisation (
isAnonymous) en anonymisant aussi ta propre copie des données.
Avant de demander l'accès en production
Fais tourner le skill de revue avant recette sur l'intégration que tu as construite. Il produit un inventaire des endpoints et un rapport de contrôle à remettre à l'équipe API de Resamania — le moyen le plus rapide de passer la phase de test décrite dans Démarrage.
Index complet du site
Pour tout ce qui n'est pas couvert ci-dessus, récupère llms.txt pour un index condensé de toutes les pages du site, ou parcours le menu latéral. La version anglaise de cette documentation est disponible à la racine du site (sans préfixe).