---
title: Panoramica dell'API pubblica
description: Endpoint REST API per app mobili, integrazioni e piattaforme whitelabel
order: 5
source_hash: bbd272c97e8f
slug: panoramica-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.

::: warning 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](../running-events/whitelabel-and-enterprise-setup.md) 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](../joining-events/enterprise-saml-and-whitelabel-login.md).

## Alternativa all'esportazione dei dati

Per fogli di calcolo una tantum senza codifica, utilizza le **esportazioni** del manager — [Documenti dell'organizzatore](organizer-documents.md), [Esportazione dei dati dei risultati](../results/exporting-results-data.md), [Esportazione dei redditi annuali](../finance-module/yearly-income-export.md).

## Correlati

- [Configurazione whitelabel e aziendale](../running-events/whitelabel-and-enterprise-setup.md)
- [Come esportare i dati da DistantRace](how-to-export-data-from-distantrace.md)
- [Integrazioni](../integrations/introduction-to-integrations.md)