Aperçu de l'API publique
Aperçu de l'API publique
DistantRace propose une API REST (/api/v1/) utilisée par l'application mobile, les intégrations partenaires et les plateformes en marque blanche. Ceci est une carte de haut niveau — pas une référence OpenAPI complète.
Support d'intégration
L'accès à l'API pour le développement tiers est généralement organisé avec le support de DistantRace. L'authentification et les limites de taux s'appliquent.
URL de base #
https://distantrace.com/api/v1/
Authentification #
| Type de jeton | Appelant typique | Portée |
|---|---|---|
| Session / jeton mobile | Application DistantRace, web connecté | Lecture/écriture à l'échelle de l'utilisateur |
Jeton d'organisation (client_credentials) |
Backend du portail en marque blanche | Listes publiques, validation/réclamation de code de participation, images héroïques |
| OAuth utilisateur (code d'autorisation + rafraîchissement) | SPA en marque blanche après connexion | Participation, entraînements, profil, paiement |
Les intégrations en marque blanche utilisent deux types d'identifiants :
| Identifiant | Utilisation |
|---|---|
| Jeton d'organisation (porteur de longue durée) | Listes publiques d'événements/défis, images héroïques, validation de code de participation, réclamation de jeton email |
| Client OAuth utilisateur (code d'autorisation) | Connexion des participants, participation aux événements, entraînements, profil, paiement |
Le jeton d'organisation est résolu à partir du propriétaire de l'application OAuth — chaque appel API en marque blanche est implicitement limité à un club.
Les points de terminaison de compte incluent le QR de connexion, la connexion sociale, le profil (/api/v1/account/me/) et l'enregistrement de l'appareil.
Voir Configuration en marque blanche et entreprise pour le modèle complet du portail des participants.
Flux de codes de participation en marque blanche #
| Point de terminaison | Méthode | Objectif |
|---|---|---|
event/joincode/{code}/validate/ |
GET | Vérifie si un code est actif pour votre organisation ; renvoie la charge utile de l'événement public (sans PII des participants) |
event/joincode/redeem-email-token/ |
POST | Consomme un jeton de lien magique à partir d'un email d'invitation ; renvoie des jetons OAuth et peut s'inscrire automatiquement à un défi |
event/joincode/ |
POST | Crée un code de participation et envoie un email d'invitation (jeton utilisateur administrateur uniquement — pas le jeton d'organisation public) |
La réclamation de lien magique utilise le jeton d'organisation plus un token à usage unique dans le corps du POST. Le serveur peut créer un utilisateur à partir des données de pré-remplissage du code de participation, émettre des jetons d'accès/rafraîchissement, et appeler l'inscription automatique lorsque le code est lié à un défi.
Images héroïques (uniquement en marque blanche) #
GET orgs/hero-images/?language=<code> — images de carrousel actives pour l'organisation du jeton. Nécessite is_whitelabel sur le club. Le filtre de langue optionnel renvoie des images spécifiques à la locale plus des images de secours neutres en termes de langue.
Principaux groupes de ressources #
| Préfixe | Ressources |
|---|---|
event/ |
Événements, codes de participation, publications |
gamification/ |
Défis, participants aux défis, défis d'équipe, objectifs, statistiques quotidiennes |
races/ |
Compétitions, participants (coureurs), résultats |
shop/ |
Paniers, articles de panier, produits, niveaux premium |
users/ |
Utilisateurs, participants, appareils push |
workouts/ |
Activités, téléchargement, métadonnées sport/type |
orgs/ |
Organisations, images héroïques (en marque blanche) |
finances/ |
Canaux de paiement, aides à la tarification |
Tâches d'intégration courantes #
| Tâche | Points de terminaison typiques |
|---|---|
| Lister les événements publiés | event/event/ |
| Enregistrer un participant | races/registration/entrant/ |
| Synchroniser les activités | workouts/ ou workouts/upload/ |
| Lire les résultats | races/result/ |
| Pas quotidiens mobiles | gamification/dailystat/ |
SSO d'entreprise #
Points de terminaison SAML (hôte d'authentification de la plateforme) :
| Chemin | Objectif |
|---|---|
/saml2/discovery/ |
Entrez l'email professionnel → redirige vers le bon IdP par domaine |
/saml2/login/ |
Démarrer l'authentification SAML (paramètres de requête idp et next optionnels) |
/saml2/acs/ |
Consommateur d'assertion (retour IdP) |
/saml2/metadata/ |
Métadonnées du fournisseur de services pour la configuration IdP |
Lorsque plusieurs fournisseurs d'identité existent, la découverte associe le domaine de l'email à un IdP avant de rediriger vers la connexion. Avec un seul IdP, la découverte passe directement à /saml2/login/.
Flux des participants et du personnel : Connexion SAML d'entreprise et en marque blanche.
Alternative d'exportation de données #
Pour des feuilles de calcul ponctuelles sans codage, utilisez les exports du gestionnaire — Documents de l'organisateur, Exportation des données de résultats, Exportation des revenus annuels.