Publiskā API pārskats
Publiskā API pārskats
DistantRace piedāvā REST API (/api/v1/), ko izmanto mobilā lietotne, partneru integrācijas un whitelabel platformas. Šis ir augsta līmeņa pārskats — nevis pilna OpenAPI atsauce.
Integrāciju atbalsts
API piekļuvi trešo pušu izstrādei parasti saskaņo ar DistantRace atbalstu. Tiek piemērota autentifikācija un pieprasījumu ierobežojumi.
Bāzes URL #
https://distantrace.com/api/v1/
Autentifikācija #
| Piešķīrums / marķieris | Tipiskais izsaucējs | Tvērums |
|---|---|---|
| Session / mobile token | DistantRace lietotne, pieteicies web | Lietotāja tvēruma lasīšana/rakstīšana |
Org token (client_credentials) |
Whitelabel portāla aizmugursistēma | Publiskie saraksti, pievienošanās kodu validēšana/izmantošana, hero attēli |
| User OAuth (autorizācijas kods + atsvaidzināšana) | Whitelabel SPA pēc pieteikšanās | Pievienošanās, treniņi, profils, apmaksa |
Whitelabel integrācijas izmanto divus akreditācijas datu veidus:
| Akreditācijas dati | Izmantošana |
|---|---|
| Org token (ilgdzīvojošs bearer) | Publiski pasākumu/izaicinājumu saraksti, hero attēli, pievienošanās kodu validēšana, e-pasta marķieru izmantošana |
| User OAuth client (autorizācijas kods) | Dalībnieku pieteikšanās, pievienošanās pasākumiem, treniņi, profils, apmaksa |
Org token tiek noteikts no OAuth lietojumprogrammas īpašnieka — katrs whitelabel API izsaukums ir netieši piesaistīts vienam klubam.
Konta galapunkti ietver pieteikšanās QR, sociālo pieteikšanos, profilu (/api/v1/account/me/) un ierīču reģistrāciju.
Skati Whitelabel un korporatīvā uzstādīšana par pilnu dalībnieku portāla modeli.
Whitelabel pievienošanās kodu plūsmas #
| Galapunkts | Metode | Mērķis |
|---|---|---|
event/joincode/{code}/validate/ |
GET | Pārbauda, vai kods ir aktīvs tavai organizācijai; atgriež publisko pasākuma datu kravu (bez dalībnieku personas datiem) |
event/joincode/redeem-email-token/ |
POST | Izmanto magic-link marķieri no ielūguma e-pasta; atgriež OAuth marķierus un var automātiski pierakstīt izaicinājumā |
event/joincode/ |
POST | Izveido pievienošanās kodu un nosūta ielūguma e-pastu (tikai administratora lietotāja marķieris — nevis publiskais org token) |
Magic-link izmantošana lieto org token kopā ar vienreizēju token POST pieprasījuma pamatteksta laukā. Serveris var izveidot lietotāju no pievienošanās koda priekšaizpildes datiem, izsniegt piekļuves/atsvaidzināšanas marķierus un izsaukt automātisko pierakstīšanu, kad kods ir piesaistīts izaicinājumam.
Hero attēli (tikai whitelabel) #
GET orgs/hero-images/?language=<code> — aktīvie karuseļa attēli marķiera organizācijai. Nepieciešams is_whitelabel klubam. Neobligātais valodas filtrs atgriež konkrētai lokalizācijai atbilstošus attēlus plus valodas ziņā neitrālus rezerves attēlus.
Galvenās resursu grupas #
| Prefikss | Resursi |
|---|---|
event/ |
Pasākumi, pievienošanās kodi, ieraksti |
gamification/ |
Izaicinājumi, izaicinājuma dalībnieki, komandu izaicinājumi, mērķi, ikdienas statistika |
races/ |
Sacensības, dalībnieki (skrējēji), rezultāti |
shop/ |
Grozi, groza vienumi, produkti, premium līmeņi |
users/ |
Lietotāji, dalībnieki, push ierīces |
workouts/ |
Aktivitātes, augšupielāde, sporta/veida metadati |
orgs/ |
Organizācijas, hero attēli (whitelabel) |
finances/ |
Maksājumu kanāli, cenu palīgi |
Biežākie integrācijas uzdevumi #
| Uzdevums | Tipiskie galapunkti |
|---|---|
| Publicēto pasākumu saraksts | event/event/ |
| Dalībnieka reģistrācija | races/registration/entrant/ |
| Aktivitāšu sinhronizācija | workouts/ vai workouts/upload/ |
| Rezultātu lasīšana | races/result/ |
| Mobilie ikdienas soļi | gamification/dailystat/ |
Korporatīvais SSO #
SAML galapunkti (platformas autentifikācijas resursdators):
| Ceļš | Mērķis |
|---|---|
/saml2/discovery/ |
Ievadi darba e-pastu → maršrutē uz pareizo IdP pēc domēna |
/saml2/login/ |
Sāc SAML autentifikāciju (neobligāti idp un next vaicājuma parametri) |
/saml2/acs/ |
Apgalvojuma patērētājs (IdP atzvans) |
/saml2/metadata/ |
Pakalpojuma sniedzēja metadati IdP konfigurēšanai |
Kad pastāv vairāki identitātes sniedzēji, discovery saskaņo e-pasta domēnu ar IdP pirms novirzīšanas uz pieteikšanos. Ja ir viens IdP, discovery pāriet tieši uz /saml2/login/.
Dalībnieku un personāla plūsmas: Korporatīvā SAML un whitelabel pieteikšanās.
Datu eksporta alternatīva #
Vienreizējām izklājlapām bez programmēšanas izmanto pārvaldības eksportus — Organizatora dokumenti, Rezultātu datu eksports, Gada ienākumu eksports.