نظرة عامة على Canvas API

أدر رحلات Canvas، وهي أتمتات متعددة الخطوات تُنشأ في منشئ الرحلات المرئي، عبر REST API.

جميع نقاط النهاية في هذه الصفحة نسبية إلى عنوان الأساس: https://api-eu1.joryio.com. راجع نظرة عامة على API.

المسار هو /journeys

توجد نقاط نهاية Canvas تحت المسار /journeys: اسم مورد API لـ canvas هو journey. يشير canvasId ومعرّف الرحلة إلى المعرّف نفسه.

المصادقة

تتطلب جميع الطلبات مصادقة مفتاح API:

Authorization: Bearer jry_live_your_api_key_here
Content-Type: application/json

النطاقات المطلوبة لكل مجموعة نقاط نهاية:

النطاق	نقاط النهاية
canvas:read	السرد والجلب والتنفيذات والإحصاءات وتحليلات العُقد والإصدارات
canvas:write	الإنشاء والتحديث والتكرار والأرشفة والوسوم والنسخ والتجارب
canvas:activate	التفعيل والإيقاف المؤقت والاستئناف والنشر وإعادة التشغيل وإدخال مستخدم والتراجع
canvas:delete	الحذف والحذف المجمع

---

سرد الرحلات

GET /journeys

معاملات الاستعلام

المعامل	النوع	الافتراضي	الوصف
status	string	-	الفلترة حسب الحالة
tags	string	-	الفلترة حسب الوسوم، مفصولة بفواصل
q	string	-	بحث نص حر
createdBy / editedBy	string	-	الفلترة حسب المنشئ/آخر محرر، معرّفات مستخدمين مفصولة بفواصل
page	number	1	رقم الصفحة
limit	number	-	النتائج في الصفحة، حتى 100

طلب مثال

curl -X GET "https://api-eu1.joryio.com/journeys?status=active&limit=20" \
  -H "Authorization: Bearer jry_live_your_api_key"

الاستجابة

{
  "data": [
    { "id": "3c9d2f1a-5e8b-4a7c-9f0d-1b2a3c4d5e6f", "name": "Welcome journey", "status": "active" }
  ],
  "pagination": {
    "total": 8,
    "page": 1,
    "limit": 20,
    "offset": 0,
    "totalPages": 1,
    "hasMore": false
  }
}

---

إنشاء رحلة

POST /journeys

نص الطلب

الحقل	النوع	مطلوب	الوصف
name	string	نعم	اسم الرحلة، بحد أقصى 255 حرفًا
description	string	لا	الوصف، بحد أقصى 1000 حرف
nodes	array	لا	عُقد الرسم البياني، بحد أقصى 500. قد تبدأ المسودة المنشأة بالمعالج فارغة
edges	array	لا	حواف الرسم البياني، بحد أقصى 1000
entryTrigger	object	لا	كيفية دخول المستخدمين، راجع أدناه
variants	array	لا	نسخ A/B/n للرحلة كاملة، راجع أدناه
settings	object	لا	timezone وquietTime وconversionTracking وreEntryPolicy وpersonalizedVariants مع الإعداد
sendType	string	لا	immediate أو scheduled أو recurring أو trigger
scheduledAt	string	لا	تاريخ ISO 8601 لـ sendType: "scheduled"
recurringSchedule	object	لا	frequency (daily/weekly/monthly/custom) وcron وdayOfWeek وdayOfMonth وtimeOfDay وtimezone وendDate وmaxOccurrences
targeting	object	لا	جمهور الرحلات المجدولة/الفورية: userIds وfilterGroups وexcludeFilterGroups وfilterOperator وsubscriptionPreference
exitCriteria	object	لا	شكل الفلاتر نفسه لـ targeting؛ ويُخرج المستخدمون النشطون المطابقون
tags	string[]	لا	الوسوم

بنية العُقدة

يحمل كل إدخال في nodes حقول id وtype وconfig الخاص بالنوع وposition اختياريًا (x/y للمحرر). قيم type الصالحة:

trigger, delay, condition, behavior_split, context, message,
email, sms, push, in_app, in_app_message, whatsapp, whatsapp_message,
webhook, update_user, connector, experiment, ai_decision,
wallet, update_wallet

يحمل كل إدخال في edges حقول id وsource وtarget وsourceHandle / targetHandle / label اختيارية. يختار sourceHandle منفذ الإخراج في العُقد متعددة المخرجات، مثل مجموعات الفروع أو did / timed_out في behavior split.

مشغّل الدخول

يحمل entryTrigger حقل type وإعداد config خاصًا بالنوع. الأنواع الصالحة: event وsegment وapi وentity_change وwhatsapp_inbound وsms_inbound وviber_inbound وattribute_change وsubscription_status وschedule.

نسخ الرحلة كاملة

يحمل كل إدخال في variants: id وname وpercentage (من 0 إلى 100، ويجب أن يكون مجموع كل النسخ 100) وisControl، إذ إن نسخة التحكم مجموعة محجوبة مقاسة بلا مسار، وtriggerNodeId، أي عُقدة المشغّل التي تنطلق منها نسخة المعالجة. راجع تحليلات الرحلات لطريقة عرض نتائج النسخ.

طلب مثال

curl -X POST https://api-eu1.joryio.com/journeys \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome journey",
    "sendType": "trigger",
    "entryTrigger": {
      "type": "event",
      "config": { "eventName": "signed_up" }
    },
    "nodes": [
      { "id": "n1", "type": "trigger", "config": { "type": "event", "eventName": "signed_up" } },
      { "id": "n2", "type": "delay", "config": { "delayType": "duration", "value": 1, "unit": "days" } },
      { "id": "n3", "type": "email", "config": { "subject": "Welcome!", "html": "<p>Hi {{ user.firstName }}</p>" } }
    ],
    "edges": [
      { "id": "e1", "source": "n1", "target": "n2" },
      { "id": "e2", "source": "n2", "target": "n3" }
    ]
  }'

يعيد كائن الرحلة المُنشأ بحالة draft.

---

جلب رحلة

GET /journeys/:canvasId

curl -X GET https://api-eu1.joryio.com/journeys/3c9d2f1a-5e8b-4a7c-9f0d-1b2a3c4d5e6f \
  -H "Authorization: Bearer jry_live_your_api_key"

يعيد الرحلة كاملة، بما فيها nodes وedges وentryTrigger وvariants وsettings.

---

تحديث رحلة

PUT /journeys/:canvasId

يقبل النص الحقول نفسها في إنشاء رحلة؛ كلها اختيارية ولا تُحدّث إلا الحقول المقدمة.

curl -X PUT https://api-eu1.joryio.com/journeys/3c9d2f1a-5e8b-4a7c-9f0d-1b2a3c4d5e6f \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Welcome journey v2" }'

---

حذف رحلة

DELETE /journeys/:canvasId

يعيد 204 No Content. يفضّل أرشفة الرحلات ذات سجل التشغيل بدل حذفها عبر POST /journeys/:canvasId/archive، إذ توقف الأرشفة التسجيل والإرسال مع الاحتفاظ بالتحليلات.

---

نقاط نهاية الحالة

الطريقة	المسار	النطاق	الوصف
POST	/journeys/:canvasId/activate	canvas:activate	تفعيل؛ يمكن للمستخدمين البدء بالدخول
POST	/journeys/:canvasId/pause	canvas:activate	إيقاف مؤقت؛ يوقف الإدخالات الجديدة والتقدم
POST	/journeys/:canvasId/resume	canvas:activate	استئناف رحلة موقفة
POST	/journeys/:canvasId/archive	canvas:write	أرشفة، توقف التسجيل/الإرسال وتحفظ السجل
POST	/journeys/:canvasId/unarchive	canvas:write	استعادة إلى حالة غير مشغلة؛ فعّل صراحة للاستئناف
POST	/journeys/:canvasId/publish	canvas:activate	نشر المسودة الحالية كإصدار جديد. النص: changeSummary اختياري وuserTransition (keep_on_version / force_exit / migrate_to_new)
POST	/journeys/:canvasId/rerun	canvas:activate	إعادة تشغيل الإصدار المنشور الحالي دون إنشاء إصدار جديد

curl -X POST https://api-eu1.joryio.com/journeys/3c9d2f1a-5e8b-4a7c-9f0d-1b2a3c4d5e6f/activate \
  -H "Authorization: Bearer jry_live_your_api_key"

---

إدخال مستخدم (مشغّل API)

سجّل مستخدمًا محددًا في رحلة؛ وهو مسار الإدخال لـ entryTrigger.type: "api".

POST /journeys/:canvasId/enter/:userId

النص اختياري: context، وهو كائن JSON متاح للتنفيذ ويمكن قراءته في الرسائل والشروط كمتغيرات سياق الرحلة.

curl -X POST https://api-eu1.joryio.com/journeys/3c9d2f1a-5e8b-4a7c-9f0d-1b2a3c4d5e6f/enter/user_123 \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "context": { "source": "crm-sync", "priority": "high" } }'

---

التنفيذات والتحليلات

الطريقة	المسار	الوصف
GET	/journeys/:canvasId/executions	سرد التنفيذات، status وlimit حتى 100 وoffset
GET	/journeys/:canvasId/executions/:executionId	جلب تنفيذ واحد
GET	/journeys/:canvasId/executions/:executionId/context	متغيرات سياق التنفيذ مع الأنواع المستنتجة
GET	/journeys/:canvasId/stats	إحصاءات مستوى الرحلة، startDate وendDate
GET	/journeys/:canvasId/node-analytics	تحليلات لكل عُقدة، startDate وendDate
GET	/journeys/:canvasId/variant-stats	أداء نسخ الرحلة كاملة، A/B/n والتحكم
GET	/journeys/:canvasId/experiments/:nodeId/stats	إحصاءات عُقدة التجربة مع اختبار الدلالة
POST	/journeys/:canvasId/experiments/:nodeId/declare-winner	إعلان فائز، النص pathId
POST	/journeys/:canvasId/experiments/:nodeId/reset	إعادة تجربة إلى جمع البيانات
GET	/journeys/:canvasId/personalization-status	حالة مرحلة النسخ المخصصة

---

نقاط نهاية إضافية

الطريقة	المسار	الوصف
PUT	/journeys/:canvasId/variants	ضبط نسخ الرحلة كاملة، نص variants
GET	/journeys/:canvasId/versions	سرد الإصدارات
GET	/journeys/:canvasId/versions/compare?v1=&v2=	مقارنة إصدارين
GET	/journeys/:canvasId/versions/compare-draft	مقارنة المسودة الحالية بآخر إصدار منشور
GET	/journeys/:canvasId/versions/migration-preview	معاينة توافق التنفيذ قبل نشر مع ترحيل
GET	/journeys/:canvasId/versions/:versionId	جلب إصدار
POST	/journeys/:canvasId/versions/:versionId/rollback	التراجع إلى إصدار
GET	/journeys/:canvasId/versions/:versionId/stats	إحصاءات خاصة بإصدار
GET	/journeys/:canvasId/versions/:versionId/executions	تنفيذات إصدار محدد
GET	/journeys/:canvasId/version-execution-counts	أعداد التنفيذات لكل إصدار
POST	/journeys/:canvasId/versions/:versionId/migrate	ترحيل التنفيذات المتوافقة قسرًا إلى إصدار
GET	/journeys/:canvasId/history	سجل التدقيق، limit حتى 200
POST	/journeys/bulk-delete / bulk-duplicate / bulk-archive / bulk-unarchive	إجراءات مجمعة؛ النص { "ids": [...] } ويعيد { succeeded, failed }
POST	/journeys/bulk-tag	إضافة وسوم مجمعة؛ النص { "ids": [...], "tags": [...] }
POST	/journeys/webhook/test	تشغيل إعداد عُقدة Webhook مرة بسياق عينة، مع تحديد للمعدل
POST	/journeys/preview-context-value	عرض تعبير Liquid بسياق عينة
POST	/journeys/preview-user-updates	تشغيل تجريبي لصفوف عُقدة Update User على مستخدم عينة
POST	/journeys/:canvasId/nodes/:nodeId/send-test-email / send-test-sms / send-test-whatsapp / send-test-push	إرسال اختباري لعُقدة رسالة
POST	/journeys/:canvasId/cleanup-stuck-executions	تنظيف التنفيذات العالقة
GET	/journeys/:canvasId/executions/:executionId/rendered-message/:nodeId	الرسالة المعروضة لتنفيذ وعُقدة محددين

---

استجابات الأخطاء

تشترك جميع الأخطاء في الشكل القياسي. راجع استجابة الخطأ في نظرة API العامة لمعرفة التنسيق ورموز الحالة وسلوك تحديد المعدل.

{
  "statusCode": 404,
  "message": "Canvas with ID 8f14e45f-ceea-467f-a11d-2f4b6a1c9e3b not found",
  "timestamp": "2026-07-12T09:00:00.000Z",
  "path": "/journeys/8f14e45f-ceea-467f-a11d-2f4b6a1c9e3b"
}

---

ذو صلة

• إنشاء Canvas
• عُقد Canvas
• التفرع في Canvas
• تحليلات Canvas