Overzicht van de openbare API
Overzicht van de openbare API
DistantRace biedt een REST API (/api/v1/) die wordt gebruikt door de mobiele app, partnerintegraties en whitelabelplatforms. Dit is een overzicht op hoog niveau — geen volledige OpenAPI-referentie.
Integratie-ondersteuning
API-toegang voor ontwikkeling door derden wordt doorgaans geregeld met ondersteuning van DistantRace. Authenticatie en snelheidslimieten zijn van toepassing.
Basis-URL #
https://distantrace.com/api/v1/
Authenticatie #
| Toekenning / token | Typische oproeper | Bereik |
|---|---|---|
| Sessie / mobiele token | DistantRace-app, ingelogde web | Gebruikersgericht lezen/schrijven |
Org token (client_credentials) |
Whitelabel portal backend | Openbare lijsten, join-code valideren/inwisselen, hero-afbeeldingen |
| User OAuth (autorisatiecode + vernieuwen) | Whitelabel SPA na inloggen | Deelnemen, trainingen, profiel, afrekenen |
Whitelabelintegraties gebruiken twee soorten referenties:
| Referentie | Gebruik |
|---|---|
| Org token (langdurige drager) | Openbare evenement/uitdaging lijsten, hero-afbeeldingen, join-code validatie, e-mailtoken inwisseling |
| User OAuth client (autorisatiecode) | Deelnemer inloggen, deelnemen aan evenementen, trainingen, profiel, afrekenen |
Het org token wordt afgeleid van de eigenaar van de OAuth-applicatie — elke whitelabel API-oproep is impliciet gericht op één club.
Account-eindpunten omvatten login QR, sociale login, profiel (/api/v1/account/me/), en apparaatregistratie.
Zie Whitelabel en enterprise setup voor het volledige deelnemersportaalmodel.
Whitelabel join-code stromen #
| Eindpunt | Methode | Doel |
|---|---|---|
event/joincode/{code}/validate/ |
GET | Controleer of een code actief is voor uw organisatie; retourneert openbare evenementgegevens (geen persoonlijke gegevens van deelnemers) |
event/joincode/redeem-email-token/ |
POST | Gebruik een magic-link token uit een uitnodigingse-mail; retourneert OAuth-tokens en kan automatisch inschrijven voor een uitdaging |
event/joincode/ |
POST | Maak een join-code en stuur een uitnodigingse-mail (alleen admin-gebruikertoken — niet het openbare org token) |
Magic-link inwisseling gebruikt het org token plus een eenmalige token in de POST-body. De server kan een gebruiker maken van join-code vooraf ingevulde gegevens, toegang/vernieuw tokens uitgeven, en automatisch inschrijven wanneer de code aan een uitdaging is gekoppeld.
Hero-afbeeldingen (alleen whitelabel) #
GET orgs/hero-images/?language=<code> — actieve carrouselafbeeldingen voor de organisatie van het token. Vereist is_whitelabel op de club. Optioneel taalfilter retourneert taalspecifieke afbeeldingen plus taalneutrale back-ups.
Belangrijkste resourcegroepen #
| Prefix | Resources |
|---|---|
event/ |
Evenementen, join-codes, berichten |
gamification/ |
Uitdagingen, uitdagers, teamuitdagingen, doelen, dagelijkse statistieken |
races/ |
Wedstrijden, deelnemers (racers), resultaten |
shop/ |
Winkelwagens, winkelwagenitems, producten, premium niveaus |
users/ |
Gebruikers, deelnemers, push-apparaten |
workouts/ |
Activiteiten, uploaden, sport/type metadata |
orgs/ |
Organisaties, hero-afbeeldingen (whitelabel) |
finances/ |
Betalingskanalen, prijshelpers |
Veelvoorkomende integratietaken #
| Taak | Typische eindpunten |
|---|---|
| Gepubliceerde evenementenlijst | event/event/ |
| Deelnemer registreren | races/registration/entrant/ |
| Activiteiten synchroniseren | workouts/ of workouts/upload/ |
| Resultaten lezen | races/result/ |
| Mobiele dagelijkse stappen | gamification/dailystat/ |
Enterprise SSO #
SAML-eindpunten (platformauthenticatiehost):
| Pad | Doel |
|---|---|
/saml2/discovery/ |
Voer werk-e-mail in → routeer naar de juiste IdP op basis van domein |
/saml2/login/ |
Start SAML-authenticatie (optionele idp en next query parameters) |
/saml2/acs/ |
Assertion consumer (IdP callback) |
/saml2/metadata/ |
Serviceprovider metadata voor IdP-configuratie |
Wanneer er meerdere identiteitsproviders zijn, stemt discovery het e-mail domein af op een IdP voordat er naar login wordt omgeleid. Met een enkele IdP slaat discovery direct naar /saml2/login/ over.
Deelnemer- en personeelstromen: Enterprise SAML en whitelabel login.
Alternatief voor data-export #
Voor eenmalige spreadsheets zonder codering, gebruik manager exports — Organisator documenten, Resultaatgegevens exporteren, Jaarlijkse inkomensexport.