Panoramica dell'API pubblica
Panoramica dell'API pubblica
DistantRace offre una REST API (/api/v1/) utilizzata dall'app mobile, dalle integrazioni dei partner e dalle piattaforme whitelabel. Questa è una mappa di alto livello — non una referenza completa OpenAPI.
Supporto per l'integrazione
L'accesso all'API per lo sviluppo di terze parti è generalmente organizzato con il supporto di DistantRace. Si applicano autenticazione e limiti di velocità.
URL di base #
https://distantrace.com/api/v1/
Autenticazione #
| Concessione / token | Chiamante tipico | Ambito |
|---|---|---|
| Session / mobile token | App DistantRace, web connesso | Lettura/scrittura a livello utente |
Org token (client_credentials) |
Backend del portale whitelabel | Elenchi pubblici, validazione/riscatto del codice di partecipazione, immagini eroiche |
| User OAuth (codice di autorizzazione + aggiornamento) | SPA whitelabel dopo l'accesso | Partecipazione, allenamenti, profilo, checkout |
Le integrazioni whitelabel utilizzano due tipi di credenziali:
| Credenziale | Uso |
|---|---|
| Org token (bearer a lunga durata) | Elenchi pubblici di eventi/sfide, immagini eroiche, validazione del codice di partecipazione, riscatto del token email |
| User OAuth client (codice di autorizzazione) | Accesso dei partecipanti, partecipazione agli eventi, allenamenti, profilo, checkout |
Il token org è risolto dal proprietario dell'applicazione OAuth — ogni chiamata API whitelabel è implicitamente limitata a un club.
Gli endpoint dell'account includono QR di accesso, accesso sociale, profilo (/api/v1/account/me/) e registrazione del dispositivo.
Vedi Configurazione whitelabel e aziendale per il modello completo del portale dei partecipanti.
Flussi di codice di partecipazione whitelabel #
| Endpoint | Metodo | Scopo |
|---|---|---|
event/joincode/{code}/validate/ |
GET | Verifica se un codice è attivo per la tua organizzazione; restituisce il payload pubblico dell'evento (nessun dato personale del partecipante) |
event/joincode/redeem-email-token/ |
POST | Consuma un token magic-link da un'email di invito; restituisce i token OAuth e può iscrivere automaticamente a una sfida |
event/joincode/ |
POST | Crea un codice di partecipazione e invia un'email di invito (solo token utente amministratore — non il token org pubblico) |
Il riscatto del magic-link utilizza il token org più un token monouso nel corpo del POST. Il server può creare un utente dai dati precompilati del codice di partecipazione, emettere token di accesso/aggiornamento e chiamare l'iscrizione automatica quando il codice è associato a una sfida.
Immagini eroiche (solo whitelabel) #
GET orgs/hero-images/?language=<code> — immagini attive del carosello per l'organizzazione del token. Richiede is_whitelabel sul club. Il filtro lingua opzionale restituisce immagini specifiche per la località più fallback neutrali rispetto alla lingua.
Principali gruppi di risorse #
| Prefisso | Risorse |
|---|---|
event/ |
Eventi, codici di partecipazione, post |
gamification/ |
Sfide, partecipanti alle sfide, sfide di squadra, obiettivi, statistiche giornaliere |
races/ |
Competizioni, partecipanti (corridori), risultati |
shop/ |
Carrelli, articoli del carrello, prodotti, livelli premium |
users/ |
Utenti, partecipanti, dispositivi push |
workouts/ |
Attività, caricamento, metadati sport/tipo |
orgs/ |
Organizzazioni, immagini eroiche (whitelabel) |
finances/ |
Canali di pagamento, assistenti di prezzo |
Compiti comuni di integrazione #
| Compito | Endpoint tipici |
|---|---|
| Elenco degli eventi pubblicati | event/event/ |
| Registrazione del partecipante | races/registration/entrant/ |
| Sincronizzazione delle attività | workouts/ o workouts/upload/ |
| Lettura dei risultati | races/result/ |
| Passi giornalieri mobili | gamification/dailystat/ |
SSO aziendale #
Endpoint SAML (host di autenticazione della piattaforma):
| Percorso | Scopo |
|---|---|
/saml2/discovery/ |
Inserisci l'email di lavoro → instrada al corretto IdP per dominio |
/saml2/login/ |
Avvia l'autenticazione SAML (parametri di query opzionali idp e next) |
/saml2/acs/ |
Consumer di asserzioni (callback IdP) |
/saml2/metadata/ |
Metadati del fornitore di servizi per la configurazione IdP |
Quando esistono più fornitori di identità, la discovery abbina il dominio dell'email a un IdP prima di reindirizzare al login. Con un singolo IdP, la discovery passa direttamente a /saml2/login/.
Flussi per partecipanti e staff: SSO aziendale e accesso whitelabel.
Alternativa all'esportazione dei dati #
Per fogli di calcolo una tantum senza codifica, utilizza le esportazioni del manager — Documenti dell'organizzatore, Esportazione dei dati dei risultati, Esportazione dei redditi annuali.