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

تتيح واجهة برمجة تطبيقات Customer Journey للواجهة الخلفية (backend) إدارة [رحلات العملاء (Customer Journeys)](/ar/product/customer-journey/pushwoosh-journey-overview/) برمجيًا: إنشاء وتعديل تعريفات الرحلة، ونقل الرحلات خلال دورة حياتها (بدء، إيقاف مؤقت، إنهاء، مسودة، أرشفة)، وتشغيل رحلة جارية من أنظمتك الخاصة، وسحب الإحصائيات لكل رحلة.

إنها نفس واجهة برمجة التطبيقات التي يستخدمها منشئ Customer Journey، وهي متاحة عبر REST/JSON من خلال جسر gRPC-Gateway.

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

```
https://journey.pushwoosh.com
```

<Aside type="tip">
إذا كنت تستخدم منطقة مخصصة أو نشرًا خاصًا، فتأكد من عنوان URL الأساسي الدقيق مع مدير نجاح العملاء في Pushwoosh.
</Aside>

## المصادقة

يجب أن يتضمن كل طلب ترويسة `Authorization` مع [رمز وصول API](/ar/developer/api-reference/api-access-token/#server-api-token) من جانب الخادم لـ Pushwoosh:

```
Authorization: Api YOUR_API_TOKEN
```

<Aside type="note">
الرمز مرتبط بالحساب الذي يملكه. تنطبق جميع العمليات على ذلك الحساب. استخدم نفس الرمز الذي تصدره لمكالمات API الأخرى من خادم إلى خادم، ولا تكشف عنه أبدًا في تطبيقات العميل.
</Aside>

## الأساليب (Methods)

### إدارة الرحلات

- [دورة الحياة (Lifecycle)](/ar/developer/api-reference/customer-journey-api/lifecycle/): `POST /api/v3/journeygateway/{action}`. بدء أو إيقاف مؤقت أو إنهاء أو حفظ كمسودة أو أرشفة رحلة بواسطة UUID الخاص بها.
- [الإنشاء والتحديث](/ar/developer/api-reference/customer-journey-api/create-update/): `POST /api/v3/journeygateway` و `PUT /api/v3/journeygateway/{uuid}`. إنشاء تعريف رحلة جديد أو استبدال تعريف موجود.

### تشغيل الرحلات

- [البدء عبر API](/ar/developer/api-reference/customer-journey-api/start-by-api/): `POST /api/journey/{id}/start/external`. إدخال المستخدمين في نقطة دخول API لرحلة قيد التشغيل بالفعل.

### الإحصائيات والجمهور

- [الحصول على إحصائيات الرحلة](/ar/developer/api-reference/customer-journey-api/statistics/): `GET /api/journey/{id}/statistics/external`. مقاييس التسليم والتحويل لكل نقطة.
- [إزالة المستخدمين من الرحلات](/ar/developer/api-reference/customer-journey-api/drop-users/): `POST /api/journey/drop-users/external`. إزالة المستخدمين من جميع الرحلات النشطة أو من رحلات محددة.

### مرجع

- [كائن الرحلة (Journey object)](/ar/developer/api-reference/customer-journey-api/journey-object/): شكل تعريف الرحلة (المعلومات، المعلمات، النقاط، التعليقات) الذي تعيده أساليب دورة الحياة والإنشاء والتحديث.
- [مرجع النقطة (Point reference)](/ar/developer/api-reference/customer-journey-api/point-reference/): بنية `point_data` لكل نوع من أنواع النقاط: عناصر الدخول، والتوقيت، والتقسيم، والإجراء، والمراسلة.

## بدء دورة الحياة مقابل البدء عبر API

لدى Customer Journey عمليتان تبدوان متشابهتين ولكنهما تعملان بشكل مختلف.

يغير [بدء دورة الحياة](/ar/developer/api-reference/customer-journey-api/lifecycle/#endpoints) حالة الرحلة (على سبيل المثال، من مسودة إلى **قيد التشغيل**). يقوم [البدء عبر API](/ar/developer/api-reference/customer-journey-api/start-by-api/) بإدخال المستخدمين في رحلة قيد التشغيل بالفعل. يقارن الجدول أدناه بينهما جنبًا إلى جنب.

| | بدء دورة الحياة | البدء عبر API |
|---|---|---|
| نقطة النهاية (Endpoint) | `POST /api/v3/journeygateway/start` | `POST /api/journey/{id}/start/external` |
| ما الذي تفعله | تنشط الرحلة وتنقلها إلى حالة **قيد التشغيل** | تدخل المستخدمين في **نقطة دخول API** لرحلة قيد التشغيل بالفعل |
| حالة الرحلة المطلوبة | مسودة أو متوقفة مؤقتًا | قيد التشغيل (مع نقطة بدء API) |
| تكرار التشغيل | مرة واحدة لكل تغيير في الحالة | بشكل متكرر، حسب حاجة المستخدمين للدخول |

## تنسيق الطلب والاستجابة

- نوع المحتوى: `application/json`.
- تستخدم أسماء الحقول في `v3` نمط `snake_case`. يتم تحويل قيم Enum إلى أسماء السلاسل النصية الخاصة بها (على سبيل المثال، `"STATUS_RUNNING"`، `"POINT_TYPE_SEND_PUSH"`).
- تعيد أساليب gRPC-Gateway (`/api/v3/journeygateway/...`) [كائن الرحلة (journey object)](/ar/developer/api-reference/customer-journey-api/journey-object/) عند النجاح، ومغلف الخطأ القياسي لـ gRPC-Gateway عند الفشل: `{ "code": ..., "message": ..., "details": [...] }`.
- تعيد الأساليب الخارجية القديمة (`/api/journey/...`) جسم JSON خاص بالأسلوب عند النجاح و `{ "success": false, "message": ... }` مع HTTP `400` عند أخطاء التحقق.

## بداية سريعة

```bash title="بدء رحلة"
curl -X POST https://journey.pushwoosh.com/api/v3/journeygateway/start \
  -H "Authorization: Api YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "uuid": "11111111-2222-3333-4444-555555555555" }'
```

## الخطوات التالية

<CardGrid>
  <LinkCard title="دورة الحياة" href="/developer/api-reference/customer-journey-api/lifecycle/" />
  <LinkCard title="الإنشاء والتحديث" href="/developer/api-reference/customer-journey-api/create-update/" />
  <LinkCard title="البدء عبر API" href="/developer/api-reference/customer-journey-api/start-by-api/" />
  <LinkCard title="الحصول على إحصائيات الرحلة" href="/developer/api-reference/customer-journey-api/statistics/" />
  <LinkCard title="إزالة المستخدمين من الرحلات" href="/developer/api-reference/customer-journey-api/drop-users/" />
  <LinkCard title="كائن الرحلة" href="/developer/api-reference/customer-journey-api/journey-object/" />
  <LinkCard title="مرجع النقطة" href="/developer/api-reference/customer-journey-api/point-reference/" />
</CardGrid>