# الدخول المستند إلى API

<Aside type="caution" icon="setting" title="تحتاج إلى مساعدة المطور">
 ستحتاج إلى مساعدة من فريق التطوير لديك لإعداد رحلة دخول مستندة إلى API. يرجى مشاركة هذا الدليل معهم.
</Aside>

## كيف يعمل

يسمح لك الدخول المستند إلى API بإطلاق رحلة العميل في اللحظة التي يقع فيها حدث تجاري معين. لبدء حملة، يجب عليك إرسال طلب API خاص.

فيما يلي بعض حالات الاستخدام للدخول المستند إلى API:

* إعلام العملاء عند عودة المنتجات إلى المخزون
* إخبار المستخدمين بانخفاض سعر منتج شائع
* إشعار المشتركين عند صدور حلقة بودكاست جديدة

على عكس الأحداث (Events) العادية، قد تحدث كل هذه الأحداث التجارية خارج التطبيق. على سبيل المثال، لا يمكن التحقق من توفر منتج إلا في قاعدة بيانات خارجية. هنا يأتي دور الدخول المستند إلى API: يمكنك إعداد إرسال طلب لإطلاق رحلة كلما حدثت تغييرات معينة خارج التطبيق (على سبيل المثال، في قاعدة بياناتك الخارجية).

<img src="/shared-33.webp" alt="عنصر الدخول المستند إلى API على لوحة الرحلة"/>

يعمل على النحو التالي:

1. أنشئ رحلة بدخول مستند إلى API. في إعدادات الدخول، ستجد قالب الطلب الذي يطلق الرحلة.
2. أضف شروط التجزئة إلى الطلب باستخدام [لغة التجزئة](/ar/developer/api-reference/segmentation-filters-api/segmentation-language). يمكنك أيضًا إضافة عناصر نائبة للمحتوى إلى الطلب لتغيير محتوى الرسالة حسب السياق.
3. أتمتة الطلب إذا لزم الأمر. على سبيل المثال، يمكن إرسال معلومات حول تغيير السعر فورًا من قاعدة البيانات إلى الـ webhook. بمجرد حدوث ذلك، يجب على الـ webhook إرسال الطلب تلقائيًا لإطلاق الرحلة. يمكنك أيضًا إرسال الطلب يدويًا إذا لم تكن بحاجة إلى الأتمتة.

يمكنك إرسال الطلب عددًا غير محدود من المرات لتغيير شروط التجزئة أو محتوى الرسالة.

لمزيد من التفاصيل، اتبع التعليمات أدناه.

## إعداد رحلة بدخول مستند إلى API

1. أنشئ رحلة بدخول مستند إلى API:

<video src="/journey-elements-api-based-entry-1.webm" title="إنشاء رحلة جديدة واختيار الدخول المستند إلى API" autoplay loop muted playsinline />

2. انقر نقرًا مزدوجًا على خطوة الدخول المستند إلى API. ستفتح نافذة تكوين الدخول.

3. يمكنك تعديل محتوى الإشعارات الفورية (push) والبريد الإلكتروني (email) في كل مرة يتم فيها إطلاق الرحلة باستخدام العناصر النائبة للمحتوى. يمكن تغيير قيمة كل عنصر نائب في الطلب. إذا لم تكن بحاجة إلى هذا الخيار، يمكنك تخطي هذه الخطوة.

> على سبيل المثال، أنت تنشئ رحلة لإشعار المشتركين عند إصدار حلقة بودكاست جديدة. باستخدام عنصر نائب للمحتوى، يمكنك تغيير عنوان البودكاست في كل مرة تطلق فيها الرحلة.

أولاً، أضف أسماء العناصر النائبة في نافذة إعداد الدخول المستند إلى API. يمكنك استخدام أي أسماء مناسبة لك.

<img src="/journey-elements-api-based-entry-2.webp" alt="إضافة أسماء العناصر النائبة للمحتوى في نافذة إعداد الدخول المستند إلى API"/>

الآن، أنشئ [إعدادًا مسبقًا للإشعارات الفورية](/ar/product/content/push-presets) أو [محتوى بريد إلكتروني](/ar/product/content/email-content/) وأدرج العنصر النائب بدلاً من النص الذي تريد تعديله. يجب أن يكون العنصر النائب بأحد التنسيقات التالية حسب احتياجاتك:

* `{placeholder_name|format_modifier|}` – إذا لم يتم تحديد قيمة العنصر النائب عند إطلاق الحملة، سيرى المستخدمون مساحة فارغة في مكانه.
* `{placeholder_name|format_modifier}` – إذا لم يتم تحديد قيمة العنصر النائب ولم يتم تعيينها بالفعل لمستخدم (في حال استخدمت وسمًا (Tag) كعنصر نائب)، فلن يتم إرسال الرسالة.

<details>

<summary>معدِّلات التنسيق</summary>

* **CapitalizeFirst** – يحول الحرف الأول في قيمة العنصر النائب إلى حرف كبير
* **CapitalizeAllFirst** – يحول الحرف الأول في كل كلمة من قيمة العنصر النائب إلى حرف كبير
* **UPPERCASE** – يحول كل الحروف إلى أحرف كبيرة
* **lowercase** – يحول كل الحروف إلى أحرف صغيرة
* **regular** – يدرج قيمة العنصر النائب تمامًا كما هي محددة في الطلب

</details>

<img src="/journey-elements-api-based-entry-3.webp" alt="إدراج عنصر نائب في إعداد مسبق للإشعارات الفورية للمحتوى الديناميكي"/>

<Aside type="tip">
يمكنك أيضًا استخدام اسم [وسم (Tag) موجود](/ar/product/audience-data-and-segmentation/user-data-tags/) بدلاً من اسم العنصر النائب. في هذه الحالة، يجب عليك تكوين الكتابة فوق قيمة هذا الوسم بالقيمة المحددة في الطلب كما هو موضح أدناه.
</Aside>

عند تكوين عنصر الإشعار الفوري (Push) أو البريد الإلكتروني (Email) في رحلتك، حدد الإعداد المسبق الذي تم إنشاؤه وقم بتشغيل خيار **تخصيص الرسالة بسمات الحدث (Personalize message with event attributes)**.

حدد العناصر النائبة التي تريد تعديلها في الطلب عند إطلاق الرحلة. اختر **إدخال الدخول المستند إلى API (API-based entry entry)** كمصدر واسم العنصر النائب كسمة ديناميكية:

<video src="/journey-elements-api-based-entry-4.webm" title="تخصيص الرسالة بسمات الحدث من الدخول المستند إلى API" autoplay loop muted playsinline />

انقر على **تطبيق (Apply)** لحفظ التغييرات.

4. في نافذة تكوين الدخول، انسخ قالب الطلب لتعديله:

<img src="/journey-elements-api-based-entry-5.webp" alt="نسخ قالب الطلب من نافذة تكوين الدخول المستند إلى API"/>
<Aside>
لإطلاق رحلة عبر API، يجب عليك تضمين رمز تفويض صالح في رأس `Authorization`.

**تنسيق الرأس المطلوب**

  ```http
  Authorization: Api <your_api_token>
  ```
  **مثال**

  ```http
  Authorization: Api c8dc6435-xxxxxxxxxxxxxxx
  ```

 </Aside>


5. أضف فلاتر الجمهور إلى المعلمة `"filter"` باستخدام [لغة التجزئة](/ar/developer/api-reference/segmentation-filters-api/segmentation-language) أو [انسخ منطق التجزئة](/ar/product/audience-data-and-segmentation/segmentation/#copy-segment-logic) من شرائحك. قم بإعداد [الوسوم (Tags)](/ar/product/audience-data-and-segmentation/user-data-tags/tags) اللازمة مسبقًا.

على سبيل المثال، لاستهداف المستخدمين الذين أضافوا عنصر _Socks_ إلى _Wishlist_ الخاصة بهم، يجب أن تبدو قيمة `"filter"` كما يلي:

`"filter": "A(\"12345-12345\") * "T(\"Wishlist\", EQ, \"Socks\")"`

في هذا المثال، يجب أن يكون لديك وسم _Wishlist_ مهيأ في تطبيقك.

<Aside type="note">
يتم إضافة رمز التطبيق الخاص بك تلقائيًا إلى المعلمة `"filter"` بالتنسيق `A(\"12345-12345\")`. لا تقم بإزالته أو تعديله.

أيضًا، يرجى الأخذ في الاعتبار أنه يجب تهريب علامات الاقتباس ("") والشرطات المائلة العكسية (\\) بشرطة مائلة عكسية (\\) في استعلامات JSON.
</Aside>

<Aside type="tip">
يمكنك أيضًا استهداف أجهزة أو مستخدمين معينين مباشرةً عن طريق تمرير مصفوفة من HWIDs في المعلمة `"hwids"` أو معرفات المستخدمين (User IDs) في المعلمة `"users"` بدلاً من استخدام الفلاتر:

```json
"users": ["user_id_1", "user_id_2", ...],
"hwids": ["hwid_1", "hwid_2", ...]
```
</Aside>

6. إذا قمت بإعداد العناصر النائبة، فحدد المحتوى المطلوب كقيم لها:

<img src="/journey-elements-api-based-entry-6.webp" alt="تحديد قيم العناصر النائبة في طلب API لإطلاق الرحلة"/>


7. إذا كنت تخطط لإعادة تشغيل حملتك بشكل متكرر ولا تريد أن يدخل نفس المستخدمين الرحلة عدة مرات، فقم بتعيين [حدود الدخول إلى الحملة](/ar/product/customer-journey/journey-settings#campaign-entry-limit).

> على سبيل المثال، لقد أنشأت حملة لإشعار المستخدمين بتخفيض سعر منتج معين. وتريد إعادة إطلاق الرحلة عدة مرات عن طريق إرسال عدة طلبات بفلاتر جمهور مختلفة. في هذه الحالة، يمكنك إضافة حدود دخول الحملة حتى لا يتم إرسال الإشعار بشكل متكرر للمستخدمين الذين يتطابقون مع فلاتر متعددة.

8. إذا كنت تريد إطلاق رحلة كلما حدث حدث تجاري معين، فقم بأتمتة الطلب باستخدام الـ webhook. بمجرد وقوع الحدث، يجب على الـ webhook إرسال الطلب تلقائيًا لبدء الرحلة.

يمكنك أيضًا إرسال الطلب يدويًا إذا لم تكن بحاجة إلى الأتمتة.

<Aside type="note">
* إذا قمت بتغيير شروط التجزئة عند إرسال طلب جديد، فلن يؤثر ذلك على المستخدمين الذين دخلوا الرحلة بالفعل.
* إذا قمت بتغيير محتوى الرسالة عند إرسال طلب جديد، فسيتلقى جميع المستخدمين الإصدار الجديد من الرسالة (بما في ذلك أولئك الذين دخلوا الرحلة بالفعل ولكنهم لم يتلقوا هذه الرسالة بعد).
</Aside>