סקירת API של מסעות

ניהול מסעות - אוטומציות מרובות שלבים שנבנות בבונה המסעות החזותי - באמצעות REST API.

כל נקודות הקצה בעמוד זה יחסיות לכתובת הבסיס: https://api-eu1.joryio.com - ראו סקירת API.

הנתיב הוא /journeys

נקודות הקצה של המסעות נמצאות תחת הנתיב /journeys - שם משאב ה־API של Canvas הוא מסע. 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 בפיצול לפי התנהגות).

טריגר כניסה

ל־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"
}

---

קישורים קשורים

• יצירת מסע
• צומתי המסע
• הסתעפויות במסע
• ניתוח נתוני מסע