# البدء عبر API

`POST` `https://journey.pushwoosh.com/api/journey/{id}/start/external`

يُدخل مجموعة من المستخدمين إلى **نقطة دخول API** لرحلة ما. استخدمها لتوجيه الرحلات من الواجهة الخلفية (backend) الخاصة بك. على سبيل المثال، ابدأ تدفق تأهيل (onboarding flow) عندما يكمل مستخدم التسجيل على خادمك.

<Aside type="tip">
لا تخلط بين هذه الاستدعاء و[بدء دورة الحياة](/ar/developer/api-reference/customer-journey-api/lifecycle/#endpoints)، الذي ينشط رحلة وينقلها إلى حالة **قيد التشغيل (Running)**. يقوم "البدء عبر API" بإدخال المستخدمين إلى رحلة قيد التشغيل بالفعل. انظر [جدول المقارنة](/ar/developer/api-reference/customer-journey-api/#lifecycle-start-vs-start-by-api).
</Aside>

## المتطلبات الأساسية

-   الرحلة في حالة **قيد التشغيل (Running)**.
-   تحتوي الرحلة على نقطة دخول API واحدة بالضبط (عنصر "البدء عبر API")، وهذا العنصر غير معطل.
-   أسماء السمات التي ترسلها تتطابق مع السمات المكونة في نقطة دخول API تلك.

<Aside type="caution" title="حد المعدل">
تقبل كل نقطة دخول API **طلبًا واحدًا في الدقيقة**. يؤدي طلب ثانٍ خلال تلك الفترة إلى إرجاع خطأ (`Enhance your calm! only one request per minute is allowed`). قم بتجميع المستلمين في طلب واحد بدلاً من إرسال العديد من الطلبات الصغيرة.
</Aside>

## معلمات المسار

| الاسم | النوع | الوصف |
|---|---|---|
| `id` | string | [معرف الرحلة (Journey ID)](/ar/developer/api-reference/api-identifiers/#journey-id) للرحلة قيد التشغيل. |

## ترويسات الطلب

| الاسم | مطلوب | القيمة |
|---|---|---|
| `Content-Type` | نعم | `application/json` |
| `Authorization` | نعم | `Api <server_api_token>`. انظر [رمز API للخادم (Server API token)](/ar/developer/api-reference/api-access-token/#server-api-token). |

## محتوى الطلب

يحتوي المحتوى على كائن `payload` واحد. يجب عليك توفير **واحد فقط** من `users` أو `hwids` أو `filter` لتحديد من يدخل الرحلة.

| الحقل | النوع | الوصف |
|---|---|---|
| `payload.users` | string[] | [معرفات المستخدمين (User IDs)](/ar/developer/api-reference/api-identifiers/#user-id) للدخول. لا يمكن استخدامها مع `hwids` و `filter`. |
| `payload.hwids` | string[] | [معرفات الأجهزة (HWIDs)](/ar/developer/pushwoosh-knowledge-hub/device-identifiers/#hwid) للدخول. لا يمكن استخدامها مع `users` و `filter`. |
| `payload.filter` | string | تعبير [seglang](/ar/developer/api-reference/segmentation-filters-api/segmentation-language/) يحدد الجمهور. لا يمكن استخدامه مع `users` و `hwids`. |
| `payload.attribute_values` | map&lt;string, string&gt; | اختياري. قيم للسمات المخصصة المحددة في نقطة دخول API. يجب أن يتطابق كل مفتاح مع اسم سمة مكون. |

### أمثلة على الطلبات

##### إدخال مستخدمين محددين

```bash
curl -X POST 'https://journey.pushwoosh.com/api/journey/<journey_id>/start/external' \
  -H 'Authorization: Api YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "payload": {
      "users": ["user-123", "user-456"]
    }
  }'
```
##### إدخال مستخدمين محددين مع سمات

```json
{
  "payload": {
    "users": ["user-123", "user-456"],
    "attribute_values": {
      "promo_code": "SUMMER25",
      "tier": "gold"
    }
  }
}
```

##### إدخال جمهور حسب الفلتر

```json
{
  "payload": {
    "filter": "A(\"XXXXX-XXXXX\").tags(\"City\").eq(\"London\")"
  }
}
```


## الاستجابة

<Tabs>
<TabItem label="200">

```json
{
  "request_uuid": "9f8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d"
}
```

| الحقل | النوع | الوصف |
|---|---|---|
| `request_uuid` | string | معرف طلب الدخول المقبول. تتم معالجة الطلب بشكل غير متزامن. |

</TabItem>
<TabItem label="400">

تُرجع أخطاء التحقق من الصحة HTTP `400` مع رسالة وصفية. الحالات الشائعة:

| الرسالة | السبب |
|---|---|
| `one of users, hwids or filter must be provided` | لم يتم تعيين أي من المحددات الثلاثة. |
| `only one of users, hwids or filter must be provided` | تم تعيين أكثر من محدد واحد. |
| `Journey is not running` | الرحلة ليست في حالة التشغيل. |
| `zero api start points` | لا تحتوي الرحلة على نقطة دخول API. |
| `there is more then one api start point` | تحتوي الرحلة على أكثر من نقطة دخول API واحدة. |
| `point is deactivated` | نقطة دخول API معطلة. |
| `unknown attribute: <name>` | مفتاح `attribute_values` غير مكون في نقطة دخول API. |
| `Enhance your calm! only one request per minute is allowed` | تم الوصول إلى حد المعدل (طلب واحد في الدقيقة لكل نقطة دخول). |

</TabItem>
</Tabs>

## مواضيع ذات صلة

<CardGrid>
  <LinkCard title="دورة الحياة" href="/developer/api-reference/customer-journey-api/lifecycle/" />
  <LinkCard title="الحصول على إحصائيات الرحلة" href="/developer/api-reference/customer-journey-api/statistics/" />
  <LinkCard title="لغة التجزئة" href="/developer/api-reference/segmentation-filters-api/segmentation-language/" />
</CardGrid>