نظرة عامة على واجهة برمجة التطبيقات العامة
نظرة عامة على واجهة برمجة التطبيقات العامة
تقدم DistantRace واجهة برمجة تطبيقات REST (/api/v1/) التي تستخدمها التطبيقات المحمولة، وتكاملات الشركاء، والمنصات ذات العلامات البيضاء. هذه خريطة عالية المستوى — ليست مرجع OpenAPI كامل.
دعم التكامل
يتم ترتيب الوصول إلى واجهة برمجة التطبيقات لتطوير الطرف الثالث عادةً مع دعم DistantRace. تنطبق المصادقة وحدود المعدل.
عنوان URL الأساسي #
https://distantrace.com/api/v1/
المصادقة #
| المنحة / الرمز | المتصل النموذجي | النطاق |
|---|---|---|
| رمز الجلسة / المحمول | تطبيق DistantRace، الويب المسجل الدخول | قراءة/كتابة مخصصة للمستخدم |
رمز المنظمة (client_credentials) |
خلفية بوابة العلامة البيضاء | قوائم عامة، التحقق من رمز الانضمام/استرداده، صور البطل |
| OAuth المستخدم (رمز التفويض + التحديث) | SPA العلامة البيضاء بعد تسجيل الدخول | الانضمام، التدريبات، الملف الشخصي، الدفع |
تستخدم تكاملات العلامة البيضاء نوعين من بيانات الاعتماد:
| بيانات الاعتماد | الاستخدام |
|---|---|
| رمز المنظمة (حامل طويل الأمد) | قوائم الأحداث/التحديات العامة، صور البطل، التحقق من رمز الانضمام، استرداد رمز البريد الإلكتروني |
| عميل OAuth المستخدم (رمز التفويض) | تسجيل دخول المشاركين، الانضمام إلى الأحداث، التدريبات، الملف الشخصي، الدفع |
يتم حل رمز المنظمة من مالك تطبيق OAuth — كل استدعاء API للعلامة البيضاء يتم تحديده ضمنيًا لنادٍ واحد.
تشمل نقاط نهاية الحساب تسجيل الدخول عبر QR، تسجيل الدخول الاجتماعي، الملف الشخصي (/api/v1/account/me/)، وتسجيل الجهاز.
راجع إعداد العلامة البيضاء والمؤسسات لنموذج بوابة المشاركين الكامل.
تدفقات رمز الانضمام للعلامة البيضاء #
| نقطة النهاية | الطريقة | الهدف |
|---|---|---|
event/joincode/{code}/validate/ |
GET | التحقق مما إذا كان الرمز نشطًا لمنظمتك؛ يعيد حمولة الحدث العامة (بدون معلومات شخصية للمشاركين) |
event/joincode/redeem-email-token/ |
POST | استهلاك رمز الرابط السحري من بريد الدعوة؛ يعيد رموز OAuth وقد يسجل تلقائيًا في تحدٍ |
event/joincode/ |
POST | إنشاء رمز انضمام وإرسال بريد دعوة (رمز مستخدم المسؤول فقط — ليس رمز المنظمة العامة) |
يستخدم استرداد الرابط السحري رمز المنظمة بالإضافة إلى token للاستخدام مرة واحدة في نص POST. قد يقوم الخادم بإنشاء مستخدم من بيانات الملء المسبق لرمز الانضمام، وإصدار رموز الوصول/التحديث، واستدعاء التسجيل التلقائي عندما يكون الرمز مرتبطًا بتحدٍ.
صور البطل (العلامة البيضاء فقط) #
GET orgs/hero-images/?language=<code> — صور الكاروسيل النشطة لمنظمة الرمز. يتطلب is_whitelabel على النادي. مرشح اللغة الاختياري يعيد الصور الخاصة بالموقع بالإضافة إلى الصور الاحتياطية المحايدة لغويًا.
مجموعات الموارد الرئيسية #
| البادئة | الموارد |
|---|---|
event/ |
الأحداث، رموز الانضمام، المنشورات |
gamification/ |
التحديات، المتحدون، تحديات الفريق، الأهداف، الإحصائيات اليومية |
races/ |
المسابقات، المشاركون (المتسابقون)، النتائج |
shop/ |
السلال، عناصر السلة، المنتجات، المستويات المميزة |
users/ |
المستخدمون، المشاركون، أجهزة الدفع |
workouts/ |
الأنشطة، التحميل، بيانات الرياضة/النوع |
orgs/ |
المنظمات، صور البطل (العلامة البيضاء) |
finances/ |
قنوات الدفع، مساعدي التسعير |
المهام التكاملية الشائعة #
| المهمة | نقاط النهاية النموذجية |
|---|---|
| قائمة الأحداث المنشورة | event/event/ |
| تسجيل المشاركين | races/registration/entrant/ |
| مزامنة الأنشطة | workouts/ أو workouts/upload/ |
| قراءة النتائج | races/result/ |
| خطوات اليومية المحمولة | gamification/dailystat/ |
SSO المؤسسات #
نقاط نهاية SAML (مضيف مصادقة المنصة):
| المسار | الهدف |
|---|---|
/saml2/discovery/ |
أدخل البريد الإلكتروني للعمل → التوجيه إلى موفر الهوية الصحيح حسب النطاق |
/saml2/login/ |
بدء مصادقة SAML (اختياري idp وnext معلمات الاستعلام) |
/saml2/acs/ |
مستهلك التأكيد (استدعاء موفر الهوية) |
/saml2/metadata/ |
بيانات مزود الخدمة لتكوين موفر الهوية |
عندما توجد عدة موفري هوية، يطابق الاكتشاف نطاق البريد الإلكتروني مع موفر الهوية قبل إعادة التوجيه إلى تسجيل الدخول. مع موفر هوية واحد، يتخطى الاكتشاف مباشرة إلى /saml2/login/.
تدفقات المشاركين والموظفين: تسجيل الدخول SAML المؤسساتي والعلامة البيضاء.
بديل تصدير البيانات #
لجداول البيانات الفردية بدون ترميز، استخدم التصديرات الإدارية — وثائق المنظم، تصدير بيانات النتائج، تصدير الدخل السنوي.