---
title: نظرة عامة على واجهة برمجة التطبيقات العامة
description: نقاط نهاية REST API للتطبيقات المحمولة والتكاملات والمنصات ذات العلامات
  البيضاء
order: 5
source_hash: bbd272c97e8f
---

# نظرة عامة على واجهة برمجة التطبيقات العامة

تقدم DistantRace **واجهة برمجة تطبيقات REST** (`/api/v1/`) التي تستخدمها التطبيقات المحمولة، وتكاملات الشركاء، والمنصات ذات العلامات البيضاء. هذه خريطة عالية المستوى — ليست مرجع OpenAPI كامل.

::: warning دعم التكامل
يتم ترتيب الوصول إلى واجهة برمجة التطبيقات لتطوير الطرف الثالث عادةً مع دعم DistantRace. تنطبق المصادقة وحدود المعدل.
:::

## عنوان URL الأساسي

```
https://distantrace.com/api/v1/
```

## المصادقة

| المنحة / الرمز | المتصل النموذجي | النطاق |
|---------------|----------------|-------|
| **رمز الجلسة / المحمول** | تطبيق DistantRace، الويب المسجل الدخول | قراءة/كتابة مخصصة للمستخدم |
| **رمز المنظمة** (`client_credentials`) | خلفية بوابة العلامة البيضاء | قوائم عامة، التحقق من رمز الانضمام/استرداده، صور البطل |
| **OAuth المستخدم** (رمز التفويض + التحديث) | SPA العلامة البيضاء بعد تسجيل الدخول | الانضمام، التدريبات، الملف الشخصي، الدفع |

تستخدم تكاملات العلامة البيضاء نوعين من بيانات الاعتماد:

| بيانات الاعتماد | الاستخدام |
|------------|-----|
| **رمز المنظمة** (حامل طويل الأمد) | قوائم الأحداث/التحديات العامة، صور البطل، التحقق من رمز الانضمام، استرداد رمز البريد الإلكتروني |
| **عميل OAuth المستخدم** (رمز التفويض) | تسجيل دخول المشاركين، الانضمام إلى الأحداث، التدريبات، الملف الشخصي، الدفع |

يتم حل رمز المنظمة من مالك تطبيق OAuth — كل استدعاء API للعلامة البيضاء يتم تحديده ضمنيًا لنادٍ واحد.

تشمل نقاط نهاية الحساب تسجيل الدخول عبر QR، تسجيل الدخول الاجتماعي، الملف الشخصي (`/api/v1/account/me/`)، وتسجيل الجهاز.

راجع [إعداد العلامة البيضاء والمؤسسات](../running-events/whitelabel-and-enterprise-setup.md) لنموذج بوابة المشاركين الكامل.

### تدفقات رمز الانضمام للعلامة البيضاء

| نقطة النهاية | الطريقة | الهدف |
|----------|--------|---------|
| `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 المؤسساتي والعلامة البيضاء](../joining-events/enterprise-saml-and-whitelabel-login.md).

## بديل تصدير البيانات

لجداول البيانات الفردية بدون ترميز، استخدم **التصديرات** الإدارية — [وثائق المنظم](organizer-documents.md)، [تصدير بيانات النتائج](../results/exporting-results-data.md)، [تصدير الدخل السنوي](../finance-module/yearly-income-export.md).

## ذات صلة

- [إعداد العلامة البيضاء والمؤسسات](../running-events/whitelabel-and-enterprise-setup.md)
- [كيفية تصدير البيانات من DistantRace](how-to-export-data-from-distantrace.md)
- [التكاملات](../integrations/introduction-to-integrations.md)