Genel API Özeti
Genel API Özeti
DistantRace, mobil uygulama, ortak entegrasyonlar ve beyaz etiket platformları tarafından kullanılan bir REST API (/api/v1/) sunar. Bu, yüksek seviyede bir haritadır — tam bir OpenAPI referansı değildir.
Entegrasyon desteği
Üçüncü taraf geliştirme için API erişimi genellikle DistantRace desteği ile düzenlenir. Kimlik doğrulama ve hız sınırlamaları uygulanır.
Temel URL #
https://distantrace.com/api/v1/
Kimlik Doğrulama #
| Yetki / token | Tipik çağırıcı | Kapsam |
|---|---|---|
| Oturum / mobil token | DistantRace uygulaması, oturum açmış web | Kullanıcıya özel okuma/yazma |
Org token (client_credentials) |
Beyaz etiket portalı arka planı | Genel listeler, katılım kodu doğrulama/kullanma, kahraman görselleri |
| Kullanıcı OAuth (yetkilendirme kodu + yenileme) | Beyaz etiket SPA oturum açtıktan sonra | Katılım, antrenmanlar, profil, ödeme |
Beyaz etiket entegrasyonları iki kimlik bilgisi türü kullanır:
| Kimlik Bilgisi | Kullanım |
|---|---|
| Org token (uzun ömürlü taşıyıcı) | Genel etkinlik/yarışma listeleri, kahraman görselleri, katılım kodu doğrulama, e-posta token kullanımı |
| Kullanıcı OAuth istemcisi (yetkilendirme kodu) | Katılımcı oturumu, etkinliklere katılım, antrenmanlar, profil, ödeme |
Org token, OAuth uygulama sahibinden çözülür — her beyaz etiket API çağrısı dolaylı olarak bir kulübe atanır.
Hesap uç noktaları arasında oturum açma QR, sosyal oturum açma, profil (/api/v1/account/me/) ve cihaz kaydı bulunur.
Tam katılımcı portalı modeli için Beyaz etiket ve kurumsal kurulum bölümüne bakın.
Beyaz etiket katılım kodu akışları #
| Uç Nokta | Metod | Amaç |
|---|---|---|
event/joincode/{code}/validate/ |
GET | Kodun organizasyonunuz için aktif olup olmadığını kontrol eder; genel etkinlik yükünü döndürür (katılımcı KVK'sı yok) |
event/joincode/redeem-email-token/ |
POST | Davet e-postasından bir sihirli bağlantı tokeni kullanır; OAuth tokenleri döndürür ve bir yarışmaya otomatik kaydolabilir |
event/joincode/ |
POST | Bir katılım kodu oluşturur ve davet e-postası gönderir (sadece yönetici kullanıcı tokeni — genel org tokeni değil) |
Sihirli bağlantı kullanımı, org tokeni ve POST gövdesinde tek kullanımlık bir token ile yapılır. Sunucu, katılım kodu önceden doldurma verilerinden bir kullanıcı oluşturabilir, erişim/yenileme tokenleri verebilir ve kod bir yarışmaya bağlı olduğunda otomatik kaydı çağırabilir.
Kahraman görselleri (sadece beyaz etiket) #
GET orgs/hero-images/?language=<code> — tokenin organizasyonu için aktif döngü görselleri. Kulüp için is_whitelabel gerektirir. İsteğe bağlı dil filtresi, yerel dildeki görselleri ve dil açısından nötr yedekleri döndürür.
Ana kaynak grupları #
| Önek | Kaynaklar |
|---|---|
event/ |
Etkinlikler, katılım kodları, gönderiler |
gamification/ |
Yarışmalar, yarışmacılar, takım yarışmaları, hedefler, günlük istatistikler |
races/ |
Yarışmalar, katılımcılar (yarışçılar), sonuçlar |
shop/ |
Sepetler, sepet öğeleri, ürünler, premium seviyeler |
users/ |
Kullanıcılar, katılımcılar, push cihazları |
workouts/ |
Aktiviteler, yükleme, spor/tür meta verileri |
orgs/ |
Organizasyonlar, kahraman görselleri (beyaz etiket) |
finances/ |
Ödeme kanalları, fiyatlandırma yardımcıları |
Yaygın entegrasyon görevleri #
| Görev | Tipik uç noktalar |
|---|---|
| Yayınlanan etkinlikleri listele | event/event/ |
| Katılımcı kaydı | races/registration/entrant/ |
| Aktiviteleri senkronize et | workouts/ veya workouts/upload/ |
| Sonuçları oku | races/result/ |
| Mobil günlük adımlar | gamification/dailystat/ |
Kurumsal SSO #
SAML uç noktaları (platform kimlik doğrulama sunucusu):
| Yol | Amaç |
|---|---|
/saml2/discovery/ |
İş e-postasını gir → alan adına göre doğru IdP'ye yönlendir |
/saml2/login/ |
SAML kimlik doğrulamasını başlat (isteğe bağlı idp ve next sorgu parametreleri) |
/saml2/acs/ |
Beyan tüketici (IdP geri çağrısı) |
/saml2/metadata/ |
IdP yapılandırması için hizmet sağlayıcı meta verileri |
Birden fazla kimlik sağlayıcı mevcut olduğunda, keşif, oturum açmadan önce e-posta alanını bir IdP ile eşleştirir. Tek bir IdP varsa, keşif doğrudan /saml2/login/ adresine geçer.
Katılımcı ve personel akışları: Kurumsal SAML ve beyaz etiket oturum açma.
Veri ihracatı alternatifi #
Kodlama olmadan tek seferlik elektronik tablolar için yönetici ihracatlarını kullanın — Organizatör belgeleri, Sonuç verilerini ihraç etme, Yıllık gelir ihracatı.