# كائن الرحلة (Journey)

تقوم جميع طرق [دورة الحياة](/ar/developer/api-reference/customer-journey-api/lifecycle/)، و[الإنشاء والتحديث](/ar/developer/api-reference/customer-journey-api/create-update/) بإرجاع كائن رحلة بنفس الهيكل العام:

```json title="الشكل"
{
  "info": { ... },        // بيانات وصفية للقراءة فقط (في الاستجابات فقط)
  "params": { ... },      // تكوين على مستوى الرحلة (إنشاء / تحديث)
  "points": [ ... ],      // عُقد اللوحة واتصالاتها
  "comments": [ ... ]     // تعليقات اللوحة
}
```

عندما تقوم بـ **إنشاء** أو **تحديث** رحلة، فإنك ترسل `title`، و`params`، و`points`، و`comments`. تُرجع الاستجابات `info` (الذي يحتوي على `params`) بالإضافة إلى `points` و`comments`.

## المعلومات (Info)

بيانات وصفية للرحلة للقراءة فقط. يتم إرجاعها بواسطة كل طريقة من طرق v3. ليست جزءًا من جسم الطلب.

| الحقل | النوع | الوصف |
|---|---|---|
| `uuid` | string | [معرف الرحلة (Journey ID)](/ar/developer/api-reference/api-identifiers/#journey-id). |
| `title` | string | اسم الرحلة. |
| `status` | [`JourneyStatus`](#journeystatus-enum) | الحالة الحالية. |
| `created_at` | string | الطابع الزمني للإنشاء (ISO 8601). |
| `updated_at` | string | الطابع الزمني لآخر تحديث (ISO 8601). |
| `is_first_activated` | bool | ما إذا كانت الرحلة قد بدأت مرة واحدة على الأقل. |
| `params` | [`JourneyParams`](#journeyparams) | تكوين على مستوى الرحلة. |
| `category_uuid` | string | UUID للفئة، أو فارغ إذا لم تكن مصنفة. |
| `pointCounts` | map<string, uint32> | عدد النقاط حسب النوع. |
| `campaign_type` | [`CampaignType`](#campaigntype-enum) | كيف يدخل المستخدمون الرحلة. |
| `stop_reason` | string | سبب توقف الرحلة، إن وجد. |
| `last_edited_by` | `User` | المستخدم الذي قام بآخر تعديل للرحلة. |
| `dynamic_entry` | bool | ما إذا كان الدخول الديناميكي ممكّنًا. |

## معلمات الرحلة (JourneyParams)

تكوين على مستوى الرحلة. يتم إرساله عند الإنشاء/التحديث ويتم إرجاعه داخل `info.params`.

| الحقل | النوع | الوصف |
|---|---|---|
| `application_code` | string | [رمز التطبيق (Application code)](/ar/developer/api-reference/api-identifiers/#application-code) الذي تنتمي إليه الرحلة. مطلوب عند الإنشاء. |
| `silent_hours` | [`SilentHours`](#silenthours) | الساعات التي يتم خلالها منع الرسائل، لكل قناة. |
| `capping` | [`EntryCapping`](#entrycapping) | قيود على عدد المرات التي يمكن للمستخدم إعادة الدخول فيها إلى الرحلة. |
| `conversion_window` | [`ConversionWindow`](#conversionwindow) | نافذة زمنية لإسناد تحويلات الأهداف. |
| `user_id_track_change_policy` | [`UserIDTrackChangePolicy`](#useridtrackchangepolicy-enum) | كيفية التعامل مع تغيير معرف المستخدم (User ID) في منتصف الرحلة. |

### ساعات الصمت (SilentHours)

يمنع الإرسال خلال ساعات الهدوء. يتم تكوينه **لكل قناة**: تأخذ كل قناة `SilentHoursParams` خاصة بها:

| الحقل | النوع | الوصف |
|---|---|---|
| `push_params` | `SilentHoursParams` | ساعات الصمت لإشعارات الدفع (push notifications). |
| `inapp_params` | `SilentHoursParams` | ساعات الصمت للرسائل داخل التطبيق (in-app messages). |
| `email_params` | `SilentHoursParams` | ساعات الصمت للبريد الإلكتروني. |
| `sms_params` | `SilentHoursParams` | ساعات الصمت للرسائل النصية القصيرة (SMS). |
| `whatsapp_params` | `SilentHoursParams` | ساعات الصمت لتطبيق WhatsApp. |
| `line_params` | `SilentHoursParams` | ساعات الصمت لتطبيق LINE. |

كل `SilentHoursParams` هو:

| الحقل | النوع | الوصف |
|---|---|---|
| `enabled` | bool | ما إذا كانت ساعات الصمت تنطبق على هذه القناة. |
| `from_time` | `Time` | بداية فترة الهدوء: `{ "hour": 0–23, "minute": 0–59 }`. |
| `to_time` | `Time` | نهاية فترة الهدوء. |
| `week_days` | bool[] | سبعة قيم منطقية للأيام التي تنطبق فيها الفترة (الاثنين = الفهرس 0). |
| `behavior` | enum | ما يجب فعله عندما تقع رسالة داخل ساعات الصمت: `WaitAndSend` (انتظر، ثم أرسل عند انتهاء الفترة)، `DropAndGo` (تخط الرسالة، واستمر في الرحلة فورًا)، أو `WaitAndDrop` (انتظر حتى انتهاء الفترة، ثم استمر دون إرسال). |

### تحديد سقف الدخول (EntryCapping)

يحد من عدد المرات التي يمكن لنفس المستخدم الدخول فيها إلى الرحلة.

| الحقل | النوع | الوصف |
|---|---|---|
| `is_enabled` | bool | ما إذا كان تحديد سقف الدخول مفعّلاً. |
| `period` | uint64 | الحد الأدنى لعدد الثواني بين مرات دخول المستخدم. |

### نافذة التحويل (ConversionWindow)

| الحقل | النوع | الوصف |
|---|---|---|
| `seconds` | uint64 | المدة التي بعدها لا يزال إكمال هدف المستخدم يُحتسب كتحويل بعد دخوله الرحلة. |

## النقطة (Point)

النقطة هي عقدة على لوحة الرحلة: نقطة دخول، رسالة، تأخير، مقسّم، وهكذا.

| الحقل | النوع | الوصف |
|---|---|---|
| `uuid` | string | معرف فريد للنقطة داخل الرحلة. يجب أن يكون UUID أساسيًا وفقًا لـ [RFC 4122](https://www.rfc-editor.org/rfc/rfc4122): 32 رقمًا سداسيًا عشريًا في مجموعات 8-4-4-4-12. |
| `title` | string | اسم العرض للنقطة. |
| `point_type` | [`PointType`](#pointtype-enum) | نوع العقدة. |
| `outputs` | array of [`PointOutput`](#pointoutput) | الاتصالات بالنقاط التالية في المسار. |
| `position` | [`Position`](#position) | إحداثيات اللوحة. |
| `point_data` | object | مفتاح واحد متداخل بالضبط، يطابق `point_type` (انظر جدول [أنواع النقاط](#point-types-and-point_data)). |

<Aside type="note">
يجب أن تكون جميع معرفات UUID (`info.uuid`، كل `uuid` للنقاط، و`next_point_uuid` لكل مخرج) معرفات UUID أساسية وفقًا لـ RFC 4122 (مجموعات سداسية عشرية 8-4-4-4-12).
</Aside>

### مخرجات النقطة (PointOutput)

مخرجات النقطة هي فروعها الصادرة. مفاتيحها **ليست حرة الشكل**. يتوقع المدقق مجموعة دقيقة من المفاتيح لكل نوع نقطة، ويرفض الرحلة التي تحتوي نقطتها على عدد خاطئ من المخرجات أو مفتاح لا يتعرف عليه.

| الحقل | النوع | الوصف |
|---|---|---|
| `identity.key` | string | مفتاح الفرع. يجب أن يتبع [قواعد مفاتيح المخرجات](#output-keys) أدناه. |
| `identity.order` | int | ترتيب عرض الفرع. |
| `info.title` | string | تسمية فرع اختيارية. |
| `info.next_point_uuid` | string | UUID للنقطة التالية التي يتصل بها هذا الفرع. |

#### مفاتيح المخرجات (Output keys)

يُسمى الفرع الافتراضي (الأول) دائمًا `"default"`. تُسمى الفروع الإضافية `"output1"`، `"output2"`، ... (البادئة `output` متبوعة بفهرس يبدأ من 1). يكسر نوعان من النقاط هذه القاعدة، كما هو موضح أدناه.

| نوع النقطة | مفاتيح المخرجات المتوقعة |
|---|---|
| نقاط الدخول (`START_BY_SEGMENT`، `START_BY_API`، `EVENT`)، `INAPP`، `SET_TAGS`، `WEBHOOK`، `AUDIENCE_SYNC`، ونقاط الرسائل بدون مقسّم (`SEND_PUSH`، `SEND_EMAIL`، `SEND_SMS`، `SEND_WHATSAPP`، `SEND_LINE`، `SEND_KAKAO`، `SEND_TELEGRAM`، `SEND_DATA`) | `default` |
| `GOAL_EVENT`، `EXIT` | لا شيء (لا توجد مخرجات) |
| `FILTER` | `default`، `output1` |
| `BOOLEAN_SPLITTER` | `default`، ثم `output1` ... `outputN` (فرع إضافي واحد لكل شرط. التقسيم البسيط بنعم/لا هو `default` + `output1`) |
| `WAIT` (تأخير) | `default`. يضيف التأخير الديناميكي مع تقسيم الفروع `output1` |
| `WAIT_EVENT` | `default` هو فرع **الحدث-لم-يتم-تشغيله**. `output1` (أو، مع نص برمجي للشروط، فرع واحد لكل شرط) هو المسار الذي تم تشغيله |
| `SEND_PUSH` مع مقسّم | `default`، `output1` (و `output2` عندما يكون كل من مقسّم الرسالة والتسليم مفعّلين) |
| `SEND_EMAIL` / `SEND_SMS` / `SEND_LINE` / `SEND_WHATSAPP` مع مقسّم | `default`، `output1` |
| `SEND_WHATSAPP` مع إعداد مسبق للرد السريع | `default`، بالإضافة إلى فرع واحد لكل رد سريع. المفتاح هو قيمة الرد السريع نفسها |
| `AB_SPLITTER` | `output0`، `output1`، `output2`، ... (واحد لكل متغير. **لا يوجد فرع `default`**) |

### الموضع (Position)

| الحقل | النوع | الوصف |
|---|---|---|
| `x` | float | الإحداثي الأفقي على اللوحة. |
| `y` | float | الإحداثي الرأسي على اللوحة. |

## أنواع النقاط و point_data

`point_data` هو واحد من: يحمل كائنًا متداخلاً واحدًا بالضبط يتم تحديد مفتاحه بواسطة `point_type` للنقطة.

| `point_type` | مفتاح `point_data` | الغرض |
|---|---|---|
| `POINT_TYPE_START_BY_SEGMENT` | `start_by_segment` | الدخول: المستخدمون الذين يطابقون شريحة. |
| `POINT_TYPE_EVENT` | `message_bus` | الدخول: المستخدمون الذين يطلقون حدثًا. |
| `POINT_TYPE_START_BY_API` | `start_by_api` | الدخول: المستخدمون الذين يتم إدخالهم عبر استدعاء [Start by API](/ar/developer/api-reference/customer-journey-api/start-by-api/). |
| `POINT_TYPE_WAIT` | `delay` | انتظر لفترة ثابتة أو ديناميكية. |
| `POINT_TYPE_WAIT_EVENT` | `wait_event` | انتظر حتى يقع حدث. |
| `POINT_TYPE_SEND_PUSH` | `send_push` | إرسال إشعار دفع (push notification). |
| `POINT_TYPE_SEND_EMAIL` | `send_email` | إرسال بريد إلكتروني. |
| `POINT_TYPE_SEND_SMS` | `send_sms` | إرسال رسالة نصية قصيرة (SMS). |
| `POINT_TYPE_SEND_WHATSAPP` | `send_whatsapp` | إرسال رسالة WhatsApp. |
| `POINT_TYPE_SEND_TELEGRAM` | `send_telegram` | إرسال رسالة Telegram. |
| `POINT_TYPE_SEND_KAKAO` | `send_kakao` | إرسال رسالة Kakao. |
| `POINT_TYPE_SEND_LINE` | `send_line` | إرسال رسالة LINE. |
| `POINT_TYPE_SEND_DATA` | `send_data` | إرسال رسالة بيانات صامتة. |
| `POINT_TYPE_INAPP` | `inapp` | عرض رسالة داخل التطبيق. |
| `POINT_TYPE_BOOLEAN_SPLITTER` | `boolean_splitter` | تقسيم المستخدمين حسب شرط (شريحة، علامات، أو حدث). |
| `POINT_TYPE_AB_SPLITTER` | `ab_splitter` | تقسيم المستخدمين إلى مجموعات A/B. |
| `POINT_TYPE_FILTER` | `filter` | السماح فقط للمستخدمين الذين يطابقون مرشحًا بالاستمرار. |
| `POINT_TYPE_SET_TAGS` | `set_tags` | تحديث علامات المستخدم. |
| `POINT_TYPE_WEBHOOK` | `web_hook` | إرسال طلب HTTP صادر. |
| `POINT_TYPE_GOAL_EVENT` | `goal_event` | تتبع هدف تحويل. |
| `POINT_TYPE_AUDIENCE_SYNC` | `audience_sync` | مزامنة المستخدمين مع جمهور خارجي. |
| `POINT_TYPE_EXIT` | `terminator` | الخروج من الرحلة. |

<Aside type="note">
تم توثيق حمولات `point_data` لكل نوع في [مرجع النقطة](/ar/developer/api-reference/customer-journey-api/point-reference/). يتم تغطية نقاط الدخول، والتوقيت، والتقسيم، والإجراءات بالكامل هناك. يتم تغطية نقاط المراسلة على مستوى الغلاف مع روابط إلى وثائق القناة ذات الصلة.
</Aside>

### مثال على نقطة

نقطة "تعيين العلامات" مع اتصال واحد تالٍ:

```json
{
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "title": "Tag as engaged",
  "point_type": "POINT_TYPE_SET_TAGS",
  "position": { "x": 480, "y": 120 },
  "outputs": [
    {
      "identity": { "key": "default", "order": 0 },
      "info": { "title": "", "next_point_uuid": "ffffffff-1111-2222-3333-444444444444" }
    }
  ],
  "point_data": {
    "set_tags": {
      "application_code": "XXXXX-XXXXX",
      "tags": [ { "name": "engaged", "value": "true" } ]
    }
  }
}
```

## تعليق الرحلة (JourneyComment)

| الحقل | النوع | الوصف |
|---|---|---|
| `id` | string | UUID للتعليق. |
| `message` | string | نص التعليق. |
| `position` | [`Position`](#position) | إحداثيات اللوحة. |
| `index` | int | ترتيب العرض. |
| `created_at` | string | الطابع الزمني للإنشاء (ISO 8601). |
| `deleted` | bool | ما إذا كان التعليق محذوفًا. |

## التعدادات (Enums)

### تعداد JourneyStatus

`STATUS_DRAFT`, `STATUS_RUNNING`, `STATUS_FINISHED`, `STATUS_ARCHIVED`, `STATUS_PAUSED`, `STATUS_UNKNOWN`.

### تعداد CampaignType

- `TriggerBased`: يدخل المستخدمون بناءً على حدث.
- `AudienceBased`: يدخل المستخدمون من شريحة.
- `APIBased`: يدخل المستخدمون عبر استدعاء Start by API.
- `Mixed`: أكثر من نوع دخول واحد.
- `Unknown`: لم يتم تحديد نوع الدخول.

### تعداد PointType

انظر جدول [أنواع النقاط](#point-types-and-point_data) أعلاه للحصول على القائمة الكاملة ومفتاح `point_data` الذي يرتبط به كل نوع.

### تعداد UserIDTrackChangePolicy

يتحكم في ما يحدث للمستخدم الذي يكون في منتصف الرحلة عندما يتغير [معرف المستخدم (User ID)](/ar/developer/api-reference/api-identifiers/#user-id) الخاص به:

- `DEFAULT`: السلوك الافتراضي.
- `TRACK`: استمر في تتبع المستخدم تحت المعرف الجديد.
- `DROP`: أزل المستخدم من الرحلة عندما يتغير معرفه.

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

<CardGrid>
  <LinkCard title="مرجع النقطة" href="/developer/api-reference/customer-journey-api/point-reference/" />
  <LinkCard title="الإنشاء والتحديث" href="/developer/api-reference/customer-journey-api/create-update/" />
  <LinkCard title="دورة الحياة" href="/developer/api-reference/customer-journey-api/lifecycle/" />
</CardGrid>