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

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

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

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

https://journey.pushwoosh.com

نصيحة

إذا كنت تستخدم منطقة مخصصة أو نشرًا خاصًا، فتأكد من عنوان URL الأساسي الدقيق مع مدير نجاح العملاء في Pushwoosh.

المصادقة

يجب أن يتضمن كل طلب ترويسة Authorization مع رمز وصول API من جانب الخادم لـ Pushwoosh:

Authorization: Api YOUR_API_TOKEN

ملاحظة

الرمز مرتبط بالحساب الذي يملكه. تنطبق جميع العمليات على ذلك الحساب. استخدم نفس الرمز الذي تصدره لمكالمات API الأخرى من خادم إلى خادم، ولا تكشف عنه أبدًا في تطبيقات العميل.

الأساليب (Methods)

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

• دورة الحياة (Lifecycle): POST /api/v3/journeygateway/{action}. بدء أو إيقاف مؤقت أو إنهاء أو حفظ كمسودة أو أرشفة رحلة بواسطة UUID الخاص بها.
• الإنشاء والتحديث: POST /api/v3/journeygateway و PUT /api/v3/journeygateway/{uuid}. إنشاء تعريف رحلة جديد أو استبدال تعريف موجود.

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

• البدء عبر API: POST /api/journey/{id}/start/external. إدخال المستخدمين في نقطة دخول API لرحلة قيد التشغيل بالفعل.

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

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

مرجع

• كائن الرحلة (Journey object): شكل تعريف الرحلة (المعلومات، المعلمات، النقاط، التعليقات) الذي تعيده أساليب دورة الحياة والإنشاء والتحديث.
• مرجع النقطة (Point reference): بنية point_data لكل نوع من أنواع النقاط: عناصر الدخول، والتوقيت، والتقسيم، والإجراء، والمراسلة.

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

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

يغير بدء دورة الحياة حالة الرحلة (على سبيل المثال، من مسودة إلى قيد التشغيل). يقوم البدء عبر 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) عند النجاح، ومغلف الخطأ القياسي لـ gRPC-Gateway عند الفشل: { "code": ..., "message": ..., "details": [...] }.
• تعيد الأساليب الخارجية القديمة (/api/journey/...) جسم JSON خاص بالأسلوب عند النجاح و { "success": false, "message": ... } مع HTTP 400 عند أخطاء التحقق.

بداية سريعة

بدء رحلة

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" }'

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

دورة الحياة

الإنشاء والتحديث

البدء عبر API

الحصول على إحصائيات الرحلة

إزالة المستخدمين من الرحلات

كائن الرحلة

مرجع النقطة