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

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

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

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

يتم تقديم أساليب gRPC-Gateway والأساليب الخارجية القديمة على مضيفين مختلفين:

الأساليب	عنوان URL الأساسي
gRPC-Gateway: /api/v3/journeygateway/... (دورة الحياة، الإنشاء، التحديث)	https://journey-api.svc-nue.pushwoosh.com
خارجي قديم: /api/journey/... (البدء عبر API، الإحصائيات، إسقاط المستخدمين)	https://journey.pushwoosh.com

نصيحة

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

المصادقة

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

Authorization: Api YOUR_API_TOKEN

ملاحظة

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

الأساليب

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

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

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

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

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

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

مرجع

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

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

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

بدء دورة الحياة يغير حالة الرحلة (على سبيل المثال، من مسودة إلى قيد التشغيل). البدء عبر API يُدخل المستخدمين في رحلة جارية بالفعل. يقارن الجدول أدناه بينهما جنبًا إلى جنب.

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

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

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

بداية سريعة

بدء رحلة

curl -X POST https://journey-api.svc-nue.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

الحصول على إحصائيات Journey

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

كائن Journey

مرجع النقطة