REST API v1

Die Termin-API

Hole Vereinstermine in deine App oder Website und lass Mitglieder direkt dort zu- oder absagen. Ihre Antwort erscheint auch in Sport Organizer.

Schnellstart

Jeder Zugriff gilt für ein Mitglied in genau einem Verein. Die API liefert die sichtbaren Termine dieses Vereins, die eigene Antwort und die Zahl bestätigter Zusagen.

Persönlicher API-Token

Für eigene Skripte und erste Tests. In der App unter Profil → Integrationen → API-Tokens einen Verein wählen und einen Token erstellen. Der Token wird einmal angezeigt, läuft nach 90 Tagen ab und lässt sich jederzeit widerrufen.

Mit MyTeam verbinden

Für Apps, in denen sich Mitglieder selbst verbinden. Sie melden sich bei Sport Organizer an und geben einen Verein frei. Deine App erneuert den Zugriff im Hintergrund. OAuth einrichten

Setze die Basisadresse und verwende den persönlichen Token oder den OAuth-Access-Token im Header Authorization: Bearer …. Bewahre Tokens geschützt auf, etwa serverseitig oder im System-Schlüsselspeicher einer nativen App.

Shell
export EVENT_API='https://api.sportorganizer.de/functions/v1/event-api'
export TOKEN='DEIN_ZUGRIFFSTOKEN'
GET/v1/events

Termine abrufen

Übergib from und to als YYYY-MM-DD. Der Zeitraum zählt beide Tage mit und umfasst bis zu 90 Kalendertage. Maßgeblich ist der tatsächliche Starttag in Europe/Berlin. Serien werden zu Einzelterminen aufgelöst.

Anfrage
curl -H "Authorization: Bearer $TOKEN" \
  "$EVENT_API/v1/events?from=2026-12-01&to=2026-12-31"

Wichtige Felder

id
ID des konkreten Einzeltermins. Verwende sie für Rückmeldungen. Sie bleibt bei einer Verschiebung stabil.
myRsvp
Eigene Antwort als yes, maybe, no oder waitlist. null steht für eine offene Antwort.
confirmedCount
Bestätigte Zusagen von eingeladenen Mitgliedern. Warteliste und „Vielleicht“ zählen dabei nicht mit.
allowedStatuses
Antworten, die jetzt zur Auswahl stehen. Eine leere Liste schließt Rückmeldungen für diesen Termin aus.
reasonRequirements
Je Status off, optional oder required für die Begründung.

Abgesagte Einzeltermine werden ausgelassen. Die vollständigen Felder inklusive Uhrzeiten, Gruppe und Antwortfrist stehen in der OpenAPI-Datei.

PUT/v1/events/{occurrenceId}/rsvp

Rückmeldung senden

Übernimm die id aus der Terminliste als URL-kodierten Pfadabschnitt. Sende yes für Zusage, maybe für Vielleicht oder no für Absage. Wenn der Termin eine Begründung verlangt, gib sie als reason mit.

Anfrage
# Beispiel-ID aus GET /v1/events
OCCURRENCE_ID='550e8400-e29b-41d4-a716-446655440000%402026-12-04'

curl -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"status":"yes"}' \
  "$EVENT_API/v1/events/$OCCURRENCE_ID/rsvp"

Verwende danach myRsvp und confirmedCount aus der Antwort. Bei einem vollen Termin kann eine Zusage je nach Termineinstellung als waitlist gespeichert werden. Die Antwort bleibt an das Mitglied des Tokens gebunden.

OAuth für Partner

Verwende den Authorization-Code-Flow mit PKCE (S256). Das Mitglied wählt den Verein auf der Freigabeseite von Sport Organizer. Deine App erhält Zugriff auf Termine und eigene Rückmeldungen in diesem Verein.

Partner-App registrieren

Schicke den App-Namen, eine kurze Beschreibung der Integration und die vollständigen HTTPS-Rücksprungadressen an info@sportorganizer.de. Du erhältst eine öffentliche client_id. Die Callback-Adresse muss bei Freigabe und Code-Austausch exakt mit einer registrierten Adresse übereinstimmen.

Freigabe starten

Erzeuge pro Vorgang einen eigenen zufälligen state und PKCE-Verifier. Für den Verifier eignen sich 32 zufällige Bytes als Base64url ohne Padding. Leite daraus die Challenge BASE64URL(SHA256(verifier)) ohne Padding ab. Speichere den Verifier und state für den Vorgang.

Öffne GET /authorize im Browser. Basisadresse für die OAuth-Endpunkte ist https://api.sportorganizer.de/functions/v1/event-oauth.

response_type
code
client_id
Deine registrierte Client-ID
redirect_uri
Registrierte Rücksprungadresse
scope
events:read rsvp:write
state
Zufälliger Wert dieses Vorgangs
code_challenge
PKCE-Challenge
code_challenge_method
S256

Vergleiche am Callback zuerst state mit deinem gespeicherten Wert. Bei einer Freigabe erhältst du einen einmaligen code, der zwei Minuten gültig ist. Eine Ablehnung liefert error=access_denied.

Code gegen Tokens tauschen

Code-Austausch
OAUTH_API='https://api.sportorganizer.de/functions/v1/event-oauth'

curl -X POST "$OAUTH_API/token" \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode "client_id=$CLIENT_ID" \
  --data-urlencode "redirect_uri=$REDIRECT_URI" \
  --data-urlencode "code=$OAUTH_CODE" \
  --data-urlencode "code_verifier=$CODE_VERIFIER"

Die Antwort enthält access_token, refresh_token, token_type, expires_in und scope. Der Access-Token gilt 15 Minuten. Verwende ihn als Bearer-Token an der Termin-API.

Zugriff erneuern oder trennen

Erneuerung
curl -X POST "$OAUTH_API/token" \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode "client_id=$CLIENT_ID" \
  --data-urlencode "refresh_token=$REFRESH_TOKEN"

Ersetze nach jeder erfolgreichen Erneuerung beide Tokens. Führe pro Verbindung höchstens einen Erneuerungsaufruf gleichzeitig aus. Ein erneut verwendeter Refresh-Token widerruft die Verbindung. Bei invalid_grant kann sich das Mitglied neu verbinden. Nach 90 Tagen ohne Erneuerung ist erneut eine Freigabe erforderlich.

Zum Trennen sendet die Partner-App POST /revoke mit den Formfeldern client_id und token. Mitglieder können den Zugriff unter Profil → Integrationen → Verbundene Apps selbst widerrufen.

Fehler behandeln

Bei einem Fehler liefert die Termin-API einen HTTP-Status und ein JSON-Feld error.

StatusWas du tun kannst
400 invalid_requestZeitraum, Termin-ID und Felder der Rückmeldung prüfen.
401 unauthorizedOAuth-Token erneuern oder den Zugang neu verbinden. Persönliche Tokens bei Ablauf in der App ersetzen.
404 not_foundTerminliste neu laden. Der Termin ist für dieses Mitglied möglicherweise nicht mehr sichtbar.
409 rsvp_rejectedTermin neu laden und die aktuellen Antwortoptionen, Frist und Begründung prüfen.
500 internal_errorSpäter erneut versuchen. Bei anhaltenden Fehlern den HTTP-Status und Endpoint an den Support melden.