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.
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.
export EVENT_API='https://api.sportorganizer.de/functions/v1/event-api'
export TOKEN='DEIN_ZUGRIFFSTOKEN'
/v1/eventsTermine 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.
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,nooderwaitlist.nullsteht 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,optionaloderrequiredfür die Begründung.
Abgesagte Einzeltermine werden ausgelassen. Die vollständigen Felder inklusive Uhrzeiten, Gruppe und Antwortfrist stehen in der OpenAPI-Datei.
/v1/events/{occurrenceId}/rsvpRü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.
# 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_typecodeclient_id- Deine registrierte Client-ID
redirect_uri- Registrierte Rücksprungadresse
scopeevents:read rsvp:writestate- Zufälliger Wert dieses Vorgangs
code_challenge- PKCE-Challenge
code_challenge_methodS256
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
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
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.
| Status | Was du tun kannst |
|---|---|
400 invalid_request | Zeitraum, Termin-ID und Felder der Rückmeldung prüfen. |
401 unauthorized | OAuth-Token erneuern oder den Zugang neu verbinden. Persönliche Tokens bei Ablauf in der App ersetzen. |
404 not_found | Terminliste neu laden. Der Termin ist für dieses Mitglied möglicherweise nicht mehr sichtbar. |
409 rsvp_rejected | Termin neu laden und die aktuellen Antwortoptionen, Frist und Begründung prüfen. |
500 internal_error | Später erneut versuchen. Bei anhaltenden Fehlern den HTTP-Status und Endpoint an den Support melden. |