ClubCoPilot für Entwickler

Die öffentliche API von ClubCoPilot

Mit der API lesen und ändern Sie die Daten Ihres Vereins aus eigenen Programmen — etwa Termine für die Vereins-App oder Sportstätten für die Webseite. Jede Anfrage läuft mit den Rechten der angemeldeten Person, genau wie in der Verwaltung.

GET https://ihr-verein.clubcopilot.de/api/v1/kalender/termine
Authorization: Bearer Zugangstoken

Zugang

  1. Einschalten. Jede Modul-API ist zunächst aus. Ein Vorstand schaltet sie im ClubCoPilot-Kundenportal unter Module ein (z. B. „API: Vereinstermine“). Solange sie aus ist, antwortet die API mit 404.
  2. Anmelden. Ihr Programm holt per OAuth 2.0 ein Zugangstoken für eine Person des Vereins (ZITADEL). Das Token gehört in den Kopf Authorization: Bearer ….
  3. Rechte. Es gelten die Rechte dieser Person im Verein, einschließlich der Einschränkung auf Abteilungen. Wer in der Verwaltung keine Termine anlegen darf, darf es auch über die API nicht.

Die Adresse ist immer https://{Vereins-Domain}/api/{Version}/{Modul}/…. Der Verein ergibt sich aus der Domain — Sie geben ihn nirgends zusätzlich an.

Module

Kalender

Vereinstermine lesen, anlegen, ändern und löschen.

/api/v1/kalender/termine

Trainingsbetrieb

Sportstätten mit ihren Teilflächen lesen.

/api/v1/trainingsbetrieb/sportstaetten

Ablage

Dokumente der Mitglieder lesen. Der Dateiinhalt wird nicht ausgeliefert. Nicht verfügbar für Personen, deren Rolle auf Abteilungen beschränkt ist.

/api/v1/ablage/dokumente

Kommunikation

Vorlagen und den Postausgang lesen, Briefe als Entwurf anlegen. Versendet wird nichts: den Versand bestätigt eine Person in ClubCoPilot.

/api/v1/kommunikation/vorlagen
/api/v1/kommunikation/briefe

Rechnungen

Festgeschriebene Rechnungen mit ihren Positionen lesen, Rechnungsentwürfe anlegen. Ein Entwurf hat keine Nummer; Festschreiben und Versand bleiben der Verwaltung vorbehalten.

/api/v1/rechnungen/rechnungen

Spenden

Zuwendungen mit Datum, Betrag, Art und Status lesen — ohne Angaben zu den Spendern.

/api/v1/spenden/zuwendungen

SEPA

SEPA-Mandate mit Referenz, Status und maskierter IBAN lesen.

/api/v1/sepa/mandate

Rechnungen, Spenden, SEPA, Ablage und Briefe gehören dem ganzen Verein. Für Personen, deren Rolle auf Abteilungen beschränkt ist, antwortet die API darauf mit 403.

Wenn Sie Entwürfe anlegen, können Sie den Kopf Idempotency-Key mitsenden. Wiederholen Sie einen Aufruf mit demselben Schlüssel, bekommen Sie dasselbe Ergebnis zurück, statt einen zweiten Entwurf zu erzeugen.

Alle Felder, Parameter und Antworten stehen in der API-Referenz. Weitere Module folgen; jedes erscheint hier, sobald es angeboten wird.

Fehler

Antwortcodes der API
CodeBedeutung
401Kein oder ungültiges Token. Der Kopf WWW-Authenticate nennt, wo es eines gibt.
403Die Person hat das nötige Recht nicht (recht nennt es) oder ist im Verein unbekannt (unknown_user).
404Nicht gefunden — auch, wenn der Verein die API dieses Moduls nicht eingeschaltet hat.
422Ungültige Angaben; errors nennt je Feld die Gründe.
429Zu viele Anfragen. Retry-After sagt, nach wie vielen Sekunden es weitergeht; X-RateLimit-Limit und X-RateLimit-Remaining zeigen das Kontingent je Minute.
503Kurzzeitig nicht verfügbar; bitte nach Retry-After Sekunden erneut versuchen.

Versionen

Die Version steht im Pfad (v1). Innerhalb einer Version kommt nur dazu: neue Pfade, neue optionale Felder und neue Werte in Antworten — Ihr Programm sollte unbekannte Felder und Werte daher ignorieren. Alles, was einen bestehenden Aufruf brechen würde, kommt nur mit einer neuen Version. Eine abgelöste Version läuft mindestens zwölf Monate weiter und kündigt ihr Ende über die Köpfe Deprecation und Sunset an.

Änderungen