Öffentliche API-Übersicht
Öffentliche API-Übersicht
DistantRace bietet eine REST API (/api/v1/), die von der mobilen App, Partnerintegrationen und Whitelabel-Plattformen genutzt wird. Dies ist eine Übersicht auf hoher Ebene — keine vollständige OpenAPI-Referenz.
Integrationsunterstützung
Der API-Zugang für Drittentwicklungen wird in der Regel mit dem DistantRace-Support arrangiert. Authentifizierung und Ratenbegrenzungen gelten.
Basis-URL #
https://distantrace.com/api/v1/
Authentifizierung #
| Grant / Token | Typischer Anrufer | Umfang |
|---|---|---|
| Session / mobile token | DistantRace-App, eingeloggtes Web | Benutzerbezogene Lese-/Schreibrechte |
Org-Token (client_credentials) |
Whitelabel-Portal-Backend | Öffentliche Listen, Beitrittscode-Validierung/-Einlösung, Hero-Bilder |
| User OAuth (Autorisierungscode + Aktualisierung) | Whitelabel SPA nach Anmeldung | Beitritt, Workouts, Profil, Checkout |
Whitelabel-Integrationen verwenden zwei Arten von Anmeldedaten:
| Anmeldedaten | Verwendung |
|---|---|
| Org-Token (langlebiger Berechtigungsträger) | Öffentliche Veranstaltungs-/Challenge-Listen, Hero-Bilder, Beitrittscode-Validierung, E-Mail-Token-Einlösung |
| User OAuth-Client (Autorisierungscode) | Teilnehmeranmeldung, Beitritt zu Veranstaltungen, Workouts, Profil, Checkout |
Das Org-Token wird vom Eigentümer der OAuth-Anwendung abgeleitet — jeder Whitelabel-API-Aufruf ist implizit einem Verein zugeordnet.
Konten-Endpunkte umfassen Login-QR, soziale Anmeldung, Profil (/api/v1/account/me/) und Geräteanmeldung.
Siehe Whitelabel- und Unternehmens-Setup für das vollständige Teilnehmerportal-Modell.
Whitelabel-Beitrittscode-Flows #
| Endpunkt | Methode | Zweck |
|---|---|---|
event/joincode/{code}/validate/ |
GET | Überprüft, ob ein Code für Ihre Organisation aktiv ist; gibt öffentliche Veranstaltungsdaten zurück (keine Teilnehmer-PII) |
event/joincode/redeem-email-token/ |
POST | Verbraucht ein Magic-Link-Token aus einer Einladungsemail; gibt OAuth-Tokens zurück und kann automatisch in eine Challenge eintragen |
event/joincode/ |
POST | Erstellt einen Beitrittscode und sendet eine Einladungsemail (nur Admin-Benutzertoken — nicht das öffentliche Org-Token) |
Die Einlösung von Magic-Links verwendet das Org-Token plus ein einmaliges token im POST-Body. Der Server kann einen Benutzer aus den Vorabfüllungsdaten des Beitrittscodes erstellen, Zugriffs-/Aktualisierungstokens ausstellen und die automatische Anmeldung aufrufen, wenn der Code an eine Challenge gebunden ist.
Hero-Bilder (nur Whitelabel) #
GET orgs/hero-images/?language=<code> — aktive Karussellbilder für die Organisation des Tokens. Erfordert is_whitelabel beim Verein. Der optionale Sprachfilter gibt lokalspezifische Bilder plus sprachneutrale Fallbacks zurück.
Hauptressourcengruppen #
| Präfix | Ressourcen |
|---|---|
event/ |
Veranstaltungen, Beitrittscodes, Beiträge |
gamification/ |
Challenges, Herausforderer, Team-Challenges, Ziele, tägliche Statistiken |
races/ |
Wettkämpfe, Teilnehmer (Rennfahrer), Ergebnisse |
shop/ |
Warenkörbe, Warenkorbelemente, Produkte, Premium-Level |
users/ |
Benutzer, Teilnehmer, Push-Geräte |
workouts/ |
Aktivitäten, Upload, Sport-/Art-Metadaten |
orgs/ |
Organisationen, Hero-Bilder (Whitelabel) |
finances/ |
Zahlungskanäle, Preishelfer |
Häufige Integrationsaufgaben #
| Aufgabe | Typische Endpunkte |
|---|---|
| Veröffentliche Veranstaltungen auflisten | event/event/ |
| Teilnehmer registrieren | races/registration/entrant/ |
| Aktivitäten synchronisieren | workouts/ oder workouts/upload/ |
| Ergebnisse lesen | races/result/ |
| Mobile tägliche Schritte | gamification/dailystat/ |
Unternehmens-SSO #
SAML-Endpunkte (Plattform-Authentifizierungs-Host):
| Pfad | Zweck |
|---|---|
/saml2/discovery/ |
Arbeits-E-Mail eingeben → zum richtigen IdP nach Domain weiterleiten |
/saml2/login/ |
SAML-Authentifizierung starten (optionale idp und next Abfrageparameter) |
/saml2/acs/ |
Assertion Consumer (IdP-Callback) |
/saml2/metadata/ |
Dienstanbieter-Metadaten für IdP-Konfiguration |
Wenn mehrere Identitätsanbieter existieren, ordnet die Discovery die E-Mail-Domain einem IdP zu, bevor sie zur Anmeldung weiterleitet. Bei einem einzigen IdP überspringt die Discovery direkt zu /saml2/login/.
Teilnehmer- und Mitarbeiterflüsse: Unternehmens-SAML und Whitelabel-Anmeldung.
Datenexport-Alternative #
Für einmalige Tabellenkalkulationen ohne Programmierung verwenden Sie Manager-Exporte — Organisator-Dokumente, Ergebnisse-Daten exportieren, Jahreseinkommen exportieren.