---
title: Przegląd Publicznego API
description: Punkty końcowe REST API dla aplikacji mobilnych, integracji i platform
  whitelabel
order: 5
source_hash: bbd272c97e8f
slug: przeglad-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.

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

## Alternatywa eksportu danych

Dla jednorazowych arkuszy kalkulacyjnych bez kodowania użyj **eksportów** menedżera — [Dokumenty organizatora](organizer-documents.md), [Eksportowanie danych wyników](../results/exporting-results-data.md), [Roczny eksport dochodów](../finance-module/yearly-income-export.md).

## Powiązane

- [Whitelabel i konfiguracja korporacyjna](../running-events/whitelabel-and-enterprise-setup.md)
- [Jak eksportować dane z DistantRace](how-to-export-data-from-distantrace.md)
- [Integracje](../integrations/introduction-to-integrations.md)