Créer une clé API et transmettre la documentation à un partenaire externe

Grâce à l'API partenaire de Club Planner, un partenaire externe — votre agence web, un outil marketing, un logiciel comptable ou votre propre application — peut lire des données de votre plateforme ou y en écrire. Cet accès passe toujours par une clé API que vous créez, limitez et révoquez vous-même.

Cet article explique comment créer une telle clé, quels droits accorder et ce qu'il faut exactement transmettre au partenaire externe.

1. Avant de commencer

Convenez d'abord de quelques points avec le partenaire externe :

Quelles données lui sont nécessaires (membres, agenda, ventes, check-in, …).
S'il doit uniquement lire, ou également écrire (modifier ou ajouter des données).
Si l'intégration est temporaire — dans ce cas, donnez une date d'expiration à la clé.

Plus la clé est restreinte, plus c'est sûr. Vous pouvez toujours ajouter des droits par la suite. Vous devez avoir accès aux Paramètres pour gérer les clés API.

2. Où trouver les clés API ?

Dans Club Planner, rendez-vous dans Paramètres → Général → Plateforme et ouvrez l'onglet API partenaire. Vous y voyez toutes les clés existantes de votre plateforme ; leur nombre est affiché à côté du nom de l'onglet.

Les captures d'écran de cet article proviennent de l'interface en anglais ; dans votre langue, les libellés sont traduits.

3. Créer une nouvelle clé

Étape 1 — Démarrer une nouvelle clé. Cliquez sur Ajouter sous la liste. Si vous n'avez encore aucune clé, cliquez sur Créer une clé API.

Étape 2 — Nom de la clé. Indiquez en haut un nom explicite, par exemple Studio Nova - Website ou Exact Online. Utilisez une clé par partenaire ou par application : vous pourrez ainsi arrêter une intégration sans toucher aux autres.

Étape 3 — Général.

Club — le club auquel la clé est destinée. Avec un seul club, laissez Tous les clubs.
Expire le — date de fin facultative. À partir de cette date, la clé ne fonctionne plus ; choisissez donc le jour qui suit le dernier jour d'utilisation prévu. Laissez vide pour une clé sans date de fin.

Étape 4 — Utilisation et journalisation.

Limite de requêtes — le nombre maximum d'appels autorisés et la période concernée (Toutes les 5 minutes, Toutes les 15 minutes, Par heure, Par jour, Par mois ou Total). Par défaut : 25 toutes les 5 minutes.
Journalisation — Désactivé, Normal ou Détaillé. Avec la journalisation activée, chaque appel est enregistré (heure, méthode, chemin, code de statut, durée, IP). Utile lors de la mise en place d'une intégration ou en cas de problème.

Besoin d'une limite plus élevée ? Tout ce qui dépasse la valeur par défaut de 25 appels toutes les 5 minutes nécessite un code de dérogation. Cliquez sur Demander une limite plus élevée et contactez le support Club Planner pour obtenir ce code. Sans code correct, la clé ne peut pas être enregistrée.

Étape 5 — Accès. Vous déterminez ici ce que la clé peut faire pour chaque domaine. Vous choisissez à chaque fois entre (aucun), Lecture seule et Lecture + écriture.

General — données du club, heures d'ouverture, modes de paiement, documents, modèles d'e-mail, tâches et journaux de la plateforme
Employee — collaborateurs : liste, détail et photo
Members — membres : fiche, abonnements, paiements et contrats, crédit, visites, statut/blocage et communication
Planner — agendas, activités, éléments d'agenda et réservations
Leads — leads (prospects), leurs étapes de vente et les agendas commerciaux
Financial — ventes en caisse, crédit des membres, entrées/sorties d'argent, soldes, articles, groupes de chiffre d'affaires et de caisse, coupons, factures et commandes
Check-in — codes QR des membres, connexion des appareils, check-in et check-out des membres et collaborateurs
IO — commande de l'éclairage et des portiques via un relais Loxone
Chat — conversations du chatbot de votre site web (lecture seule)

Mettez sur (aucun) tout ce dont le partenaire n'a pas besoin. Une clé qui doit uniquement récupérer des données se met partout sur Lecture seule.

Étape 6 — Créer et copier la clé. Cliquez sur Créer. La clé apparaît alors une seule fois, dans une fenêtre séparée.

Copiez cette clé immédiatement. Elle ne sera plus affichée et ne pourra pas être récupérée — par la suite, seuls les premiers caractères restent visibles pour la reconnaître. Vous l'avez perdue ? Créez simplement une nouvelle clé et supprimez l'ancienne. Cliquez sur Copier et conservez la clé en lieu sûr (par exemple dans un gestionnaire de mots de passe), ou collez-la directement dans le message destiné à votre partenaire externe.

4. Que transmettre au partenaire externe ?

Le bloc Documentation API en haut de chaque clé contient le lien vers la documentation technique complète de votre plateforme. Cliquez sur Copier pour reprendre le lien, ou sur Ouvrir pour la consulter vous-même. Le lien se présente ainsi :

https://[votre-adresse-clubplanner]/api/partner/docs

Cette page reprend tous les endpoints disponibles, avec les champs exacts et des exemples de code. Un développeur n'a pas besoin de plus. Un message prêt à l'emploi :

Documentation : https://[votre-adresse-clubplanner]/api/partner/docs
URL de base : https://[votre-adresse-clubplanner]/api/partner/v1/
Clé API : cp_…
À envoyer comme en-tête : X-API-Key à chaque appel (Authorization: Bearer <clé> fonctionne également)
Pour tester : GET /api/partner/v1/ping pour la connexion, puis GET /api/partner/v1/club pour récupérer le bon clubId
Droits accordés et limite : indiquez les domaines ouverts et la limite de requêtes configurée

N'envoyez pas la clé via un canal public et ne la publiez jamais dans du code qui aboutit dans un navigateur ou une application.

Conseil pour les partenaires techniques : ceux qui travaillent avec des outils d'IA (Claude Desktop, Cursor, …) peuvent utiliser le serveur MCP officiel @clubplanner/partner-api-mcp. Il ajoute la clé automatiquement et permet à l'assistant de découvrir lui-même tous les endpoints. L'explication complète figure en haut de la page de documentation.

5. Suivre et gérer une clé existante

Cliquez sur une clé dans la liste pour la déplier.

Actif / Non actif — l'interrupteur en haut met une clé en pause sans la supprimer.
Dernière utilisation — indique quand la clé a effectué son dernier appel. Pratique pour voir si une intégration est encore active.
Journal — le bouton sous les paramètres de journalisation affiche tous les appels par jour : heure, méthode, chemin, statut, durée et adresse IP. Cliquez sur une ligne pour en voir le détail.
Modifier les droits — adaptez les niveaux sous Accès et cliquez sur Sauvegarder.
Supprimer — via l'icône de corbeille. La clé cesse alors définitivement de fonctionner.

Les modifications sont actives en moins d'une minute ; le partenaire externe ne doit rien redémarrer.

6. Messages d'erreur fréquents

401 — clé absente, incorrecte, expirée ou désactivée. La clé est-elle sur Actif ? La date Expire le est-elle dépassée ? L'en-tête X-API-Key est-il correctement envoyé ?
403 — la clé n'a pas les droits suffisants pour ce domaine. Mettez le domaine concerné sous Accès sur Lecture seule ou Lecture + écriture.
404 — l'endpoint ou les données n'existent pas. Vérifiez le chemin dans la documentation.
429 — la limite de requêtes est atteinte. Augmentez la Limite de requêtes (code de dérogation requis) ou demandez au partenaire d'appeler moins souvent.

En cas de doute, mettez la Journalisation sur Détaillé : le journal montre alors exactement quels appels arrivent et quel statut ils reçoivent.

7. Bonnes pratiques

Une clé par partenaire ou application — vous pouvez ainsi révoquer une intégration sans gêner les autres.
N'accordez que les droits nécessaires et commencez de préférence par Lecture seule.
Prévoyez une date d'expiration pour les projets temporaires ou les tests.
Partagez la clé via un canal sécurisé et conservez-la dans un gestionnaire de mots de passe.
La collaboration prend fin ? Désactivez ou supprimez la clé immédiatement.
Contrôlez régulièrement la colonne Dernière utilisation et supprimez les clés inutilisées.