Przegląd Publicznego API
Przegląd Publicznego API
DistantRace udostępnia REST API (/api/v1/) używane przez aplikację mobilną, integracje partnerskie i platformy whitelabel. Jest to ogólny zarys — nie pełna dokumentacja OpenAPI.
Wsparcie dla integracji
Dostęp do API dla rozwoju zewnętrznego jest zazwyczaj uzgadniany z pomocą techniczną DistantRace. Obowiązują uwierzytelnianie i limity zapytań.
Podstawowy URL #
https://distantrace.com/api/v1/
Uwierzytelnianie #
| Grant / token | Typowy wywołujący | Zakres |
|---|---|---|
| Session / mobile token | Aplikacja DistantRace, zalogowana strona internetowa | Odczyt/zapis w zakresie użytkownika |
Org token (client_credentials) |
Backend portalu whitelabel | Publiczne listy, walidacja/realizacja kodu dołączenia, obrazy hero |
| User OAuth (kod autoryzacyjny + odświeżenie) | Whitelabel SPA po zalogowaniu | Dołączenie, treningi, profil, płatność |
Integracje whitelabel używają dwóch typów poświadczeń:
| Poświadczenie | Zastosowanie |
|---|---|
| Org token (długoterminowy bearer) | Publiczne listy wydarzeń/wyzwań, obrazy hero, walidacja kodu dołączenia, realizacja tokenu e-mail |
| User OAuth client (kod autoryzacyjny) | Logowanie uczestników, dołączanie do wydarzeń, treningi, profil, płatność |
Token organizacji jest rozwiązywany z właściciela aplikacji OAuth — każde wywołanie API whitelabel jest domyślnie przypisane do jednego klubu.
Punkty końcowe konta obejmują login QR, logowanie społecznościowe, profil (/api/v1/account/me/) i rejestrację urządzeń.
Zobacz Whitelabel i konfiguracja korporacyjna dla pełnego modelu portalu uczestnika.
Przepływy kodu dołączenia whitelabel #
| Punkt końcowy | Metoda | Cel |
|---|---|---|
event/joincode/{code}/validate/ |
GET | Sprawdza, czy kod jest aktywny dla twojej organizacji; zwraca publiczne dane wydarzenia (bez danych osobowych uczestników) |
event/joincode/redeem-email-token/ |
POST | Konsumuje token magic-link z e-maila z zaproszeniem; zwraca tokeny OAuth i może automatycznie zapisać do wyzwania |
event/joincode/ |
POST | Tworzy kod dołączenia i wysyła e-mail z zaproszeniem (tylko token użytkownika administratora — nie publiczny token organizacji) |
Realizacja magic-link używa tokenu organizacji plus jednorazowego token w treści POST. Serwer może utworzyć użytkownika z danych wstępnie wypełnionych kodem dołączenia, wydać tokeny dostępu/odświeżenia i wywołać automatyczne zapisanie, gdy kod jest powiązany z wyzwaniem.
Obrazy hero (tylko whitelabel) #
GET orgs/hero-images/?language=<code> — aktywne obrazy karuzeli dla organizacji tokenu. Wymaga is_whitelabel dla klubu. Opcjonalny filtr językowy zwraca obrazy specyficzne dla lokalizacji plus neutralne językowo zamienniki.
Główne grupy zasobów #
| Prefiks | Zasoby |
|---|---|
event/ |
Wydarzenia, kody dołączenia, posty |
gamification/ |
Wyzwania, uczestnicy wyzwań, wyzwania drużynowe, cele, codzienne statystyki |
races/ |
Zawody, uczestnicy (biegacze), wyniki |
shop/ |
Koszyki, elementy koszyka, produkty, poziomy premium |
users/ |
Użytkownicy, uczestnicy, urządzenia push |
workouts/ |
Aktywności, przesyłanie, metadane sportu/rodzaju |
orgs/ |
Organizacje, obrazy hero (whitelabel) |
finances/ |
Kanały płatności, pomocnicy cenowi |
Typowe zadania integracyjne #
| Zadanie | Typowe punkty końcowe |
|---|---|
| Lista opublikowanych wydarzeń | event/event/ |
| Rejestracja uczestnika | races/registration/entrant/ |
| Synchronizacja aktywności | workouts/ lub workouts/upload/ |
| Odczyt wyników | races/result/ |
| Mobilne codzienne kroki | gamification/dailystat/ |
Korporacyjne SSO #
Punkty końcowe SAML (host uwierzytelniania platformy):
| Ścieżka | Cel |
|---|---|
/saml2/discovery/ |
Wprowadź e-mail służbowy → przekierowanie do odpowiedniego IdP według domeny |
/saml2/login/ |
Rozpocznij uwierzytelnianie SAML (opcjonalne parametry zapytania idp i next) |
/saml2/acs/ |
Konsument asercji (callback IdP) |
/saml2/metadata/ |
Metadane dostawcy usług dla konfiguracji IdP |
Gdy istnieje wielu dostawców tożsamości, discovery dopasowuje domenę e-mail do IdP przed przekierowaniem do logowania. Przy jednym IdP, discovery przechodzi bezpośrednio do /saml2/login/.
Przepływy uczestników i personelu: Korporacyjne SAML i logowanie whitelabel.
Alternatywa eksportu danych #
Dla jednorazowych arkuszy kalkulacyjnych bez kodowania użyj eksportów menedżera — Dokumenty organizatora, Eksportowanie danych wyników, Roczny eksport dochodów.