Mit der Partner-API von Club Planner kann ein externer Partner — Ihre Webagentur, ein Marketingtool, eine Buchhaltungssoftware oder Ihre eigene App — Daten aus Ihrer Plattform lesen oder darin schreiben. Dieser Zugriff läuft immer über einen API-Schlüssel, den Sie selbst erstellen, einschränken und jederzeit wieder entziehen können.
In diesem Artikel erfahren Sie, wie Sie einen solchen Schlüssel erstellen, welche Rechte Sie vergeben sollten und was Sie dem externen Partner genau weitergeben.
1. Bevor Sie beginnen
Klären Sie zuerst mit dem externen Partner:
- Welche Daten benötigt werden (Mitglieder, Kalender, Verkäufe, Check-in, …).
- Ob nur gelesen oder auch geschrieben werden muss (Daten ändern oder hinzufügen).
- Ob die Anbindung zeitlich begrenzt ist — dann geben Sie dem Schlüssel ein Ablaufdatum.
Je enger der Schlüssel eingestellt ist, desto sicherer. Rechte können Sie jederzeit nachträglich erweitern. Für die Verwaltung von API-Schlüsseln benötigen Sie Zugriff auf die Einstellungen.
2. Wo finden Sie die API-Schlüssel?
Gehen Sie in Club Planner zu Einstellungen → Allgemein → Plattform und öffnen Sie die Registerkarte Partner-API. Dort sehen Sie alle vorhandenen Schlüssel Ihrer Plattform; die Anzahl wird neben dem Namen der Registerkarte angezeigt.
Die Screenshots in diesem Artikel stammen aus der englischsprachigen Oberfläche; in Ihrer Sprache sind die Bezeichnungen übersetzt.
3. Einen neuen Schlüssel erstellen
Schritt 1 — Neuen Schlüssel starten. Klicken Sie unter der Liste auf Hinzufügen. Haben Sie noch keinen Schlüssel, klicken Sie auf API-Schlüssel erstellen.
Schritt 2 — Schlüsselname. Geben Sie oben einen eindeutigen Namen ein, zum Beispiel Studio Nova - Website oder Exact Online. Verwenden Sie einen Schlüssel pro Partner oder Anwendung: So können Sie eine Anbindung beenden, ohne die anderen zu beeinträchtigen.
Schritt 3 — Allgemein.
- Club — für welchen Club der Schlüssel bestimmt ist. Bei nur einem Club lassen Sie Alle Clubs stehen.
- Läuft ab am — optionales Enddatum. Ab diesem Datum funktioniert der Schlüssel nicht mehr, wählen Sie also den Tag nach dem letzten Einsatztag. Für einen Schlüssel ohne Enddatum leer lassen.
Schritt 4 — Nutzung und Protokollierung.
- Anfragelimit — die maximale Anzahl an Aufrufen und der zugehörige Zeitraum (Alle 5 Minuten, Alle 15 Minuten, Stündlich, Täglich, Monatlich oder Gesamt). Standard: 25 alle 5 Minuten.
- Protokollierung — Aus, Normal oder Ausführlich. Bei aktivierter Protokollierung wird jeder Aufruf erfasst (Zeitpunkt, Methode, Pfad, Statuscode, Dauer, IP). Praktisch beim Einrichten einer Anbindung oder bei Problemen.
Höheres Limit nötig? Alles über dem Standard von 25 Aufrufen alle 5 Minuten erfordert einen Übersteuerungscode. Klicken Sie auf Höheres Limit anfordern und wenden Sie sich an den Club Planner Support, um den Code zu erhalten. Ohne korrekten Code lässt sich der Schlüssel nicht speichern.
Schritt 5 — Zugang. Hier legen Sie pro Bereich fest, was der Schlüssel darf. Sie wählen jeweils zwischen (keine), Nur lesen und Lesen + Schreiben.
- General — Clubdaten, Öffnungszeiten, Zahlungsarten, Dokumente, E-Mail-Vorlagen, Aufgaben und Plattformprotokolle
- Employee — Mitarbeiter: Liste, Detail und Foto
- Members — Mitglieder: Stammdaten, Abonnements, Zahlungen und Verträge, Guthaben, Besuche, Status/Sperrung und Kommunikation
- Planner — Kalender, Aktivitäten, Kalendereinträge und Reservierungen
- Leads — Leads (Interessenten), ihre Verkaufsschritte und die Verkaufskalender
- Financial — Kassenverkäufe, Mitgliederguthaben, Geldein- und -ausgänge, Salden, Artikel, Umsatz- und Kassengruppen, Gutscheine, Rechnungen und Bestellungen
- Check-in — QR-Codes für Mitglieder, Geräte verbinden, Ein- und Auschecken von Mitgliedern und Mitarbeitern
- IO — Steuerung von Licht und Toren über ein Loxone-Relais
- Chat — Unterhaltungen des Chatbots auf Ihrer Website (nur lesen)
Setzen Sie alles, was der Partner nicht benötigt, auf (keine). Ein Schlüssel, der nur Daten abrufen soll, steht überall auf Nur lesen.
Schritt 6 — Erstellen und den Schlüssel kopieren. Klicken Sie auf Erstellen. Der Schlüssel erscheint nun einmalig in einem eigenen Fenster.
Kopieren Sie diesen Schlüssel sofort. Er wird nicht erneut angezeigt und kann nicht abgerufen werden — danach sehen Sie nur noch die ersten Zeichen zur Wiedererkennung. Verloren? Erstellen Sie einfach einen neuen Schlüssel und löschen Sie den alten. Klicken Sie auf Kopieren und bewahren Sie den Schlüssel sicher auf (z. B. in einem Passwort-Manager), oder fügen Sie ihn direkt in die Nachricht an Ihren externen Partner ein.
4. Was geben Sie dem externen Partner weiter?
Der Block API-Dokumentation oben bei jedem Schlüssel enthält den Link zur vollständigen technischen Dokumentation Ihrer Plattform. Klicken Sie auf Kopieren, um den Link zu übernehmen, oder auf Öffnen, um sie selbst anzusehen. Der Link sieht so aus:
https://[Ihre-clubplanner-Adresse]/api/partner/docs
Diese Seite enthält alle verfügbaren Endpunkte mit den genauen Feldern und Beispielcode. Mehr braucht ein Entwickler nicht. Eine fertige Nachricht:
- Dokumentation: https://[Ihre-clubplanner-Adresse]/api/partner/docs
- Basis-URL: https://[Ihre-clubplanner-Adresse]/api/partner/v1/
- API-Schlüssel: cp_…
- Als Header mitsenden:
X-API-Keybei jedem Aufruf (Authorization: Bearer <Schlüssel>funktioniert ebenfalls) - Zum Testen:
GET /api/partner/v1/pingfür die Verbindung, danachGET /api/partner/v1/club, um die richtigeclubIdabzurufen - Vergebene Rechte und Limit: Geben Sie an, welche Bereiche Sie freigegeben und welches Anfragelimit Sie eingestellt haben
Senden Sie den Schlüssel nicht über einen öffentlichen Kanal und veröffentlichen Sie ihn niemals in Code, der im Browser oder in einer App landet.
Tipp für technische Partner: Wer mit KI-Tools arbeitet (Claude Desktop, Cursor, …), kann den offiziellen MCP-Server @clubplanner/partner-api-mcp nutzen. Er fügt den Schlüssel automatisch hinzu und lässt den Assistenten alle Endpunkte selbst entdecken. Die vollständige Erklärung steht oben auf der Dokumentationsseite.
5. Einen bestehenden Schlüssel verfolgen und verwalten
Klicken Sie in der Liste auf einen Schlüssel, um ihn aufzuklappen.
- Aktiv / Nicht aktiv — mit dem Schalter oben pausieren Sie einen Schlüssel vorübergehend, ohne ihn zu löschen.
- Zuletzt verwendet — zeigt, wann der Schlüssel zuletzt einen Aufruf gemacht hat. Praktisch, um zu sehen, ob eine Anbindung noch aktiv ist.
- Protokoll — über die Schaltfläche unter den Protokollierungseinstellungen sehen Sie alle Aufrufe pro Tag: Zeitpunkt, Methode, Pfad, Status, Dauer und IP-Adresse. Klicken Sie eine Zeile an, um die Details zu sehen.
- Rechte ändern — passen Sie die Stufen unter Zugang an und klicken Sie auf Speichern.
- Löschen — über das Papierkorb-Symbol. Der Schlüssel funktioniert danach endgültig nicht mehr.
Änderungen sind innerhalb einer Minute aktiv; der externe Partner muss nichts neu starten.
6. Häufige Fehlermeldungen
- 401 — Schlüssel fehlt, ist falsch, abgelaufen oder deaktiviert. Steht der Schlüssel auf Aktiv? Ist das Datum bei Läuft ab am überschritten? Wird der Header
X-API-Keykorrekt gesendet? - 403 — der Schlüssel hat für diesen Bereich zu wenig Rechte. Stellen Sie den betreffenden Bereich unter Zugang auf Nur lesen oder Lesen + Schreiben.
- 404 — der Endpunkt oder die Daten existieren nicht. Prüfen Sie den Pfad in der Dokumentation.
- 429 — das Anfragelimit ist erreicht. Erhöhen Sie das Anfragelimit (Übersteuerungscode erforderlich) oder lassen Sie den Partner seltener aufrufen.
Im Zweifelsfall stellen Sie die Protokollierung auf Ausführlich: Im Protokoll sehen Sie dann genau, welche Aufrufe eingehen und welchen Status sie erhalten.
7. Bewährte Vorgehensweise
- Ein Schlüssel pro Partner oder Anwendung — so entziehen Sie eine Anbindung, ohne die übrigen zu stören.
- Vergeben Sie nur die notwendigen Rechte und starten Sie möglichst mit Nur lesen.
- Setzen Sie ein Ablaufdatum bei zeitlich begrenzten Projekten oder Tests.
- Teilen Sie den Schlüssel über einen sicheren Kanal und bewahren Sie ihn in einem Passwort-Manager auf.
- Endet die Zusammenarbeit? Deaktivieren oder löschen Sie den Schlüssel sofort.
- Prüfen Sie regelmäßig die Spalte Zuletzt verwendet und räumen Sie ungenutzte Schlüssel auf.