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

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

כל נקודות הקצה בעמוד זה יחסיות לכתובת הבסיס: https://api-eu1.joryio.com/api - ראו סקירת 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:enter`	הכנסת משתמש (טריגר API) - ותו לא. כלולה ב-`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/api/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` ‏`timeOfDay` בפורמט `HH:MM` בשעון 24 שעות (`09:00`, `17:30`); כל ערך אחר נדחה עם `400`.
`targeting`	object	לא	קהל היעד למסעות מתוזמנים או מיידיים: `userIds`, `filterGroups`, `excludeFilterGroups`, `filterOperator`, `subscriptionPreference`
`exitCriteria`	object	לא	אותו מבנה מסננים כמו `targeting`; משתמשים פעילים שתואמים - יוצאים מהמסע
`tags`	string[]	לא	תגיות

מבנה צומת

לכל פריט ב־nodes יש id, ‏type, ‏config (בהתאם לסוג הצומת) ו־position אופציונלי (x ו־y עבור העורך). אלה ערכי type החוקיים:

trigger, message, in_app_message, delay, condition, behavior_split,
context, update_user, update_wallet, connector, experiment,
ai_decision, ai_agent

יש צומת message אחד; הערוץ הוא config.channel (email, sms, push, whatsapp, viber, in_app, webhook). סוגי הצמתים הישנים לכל ערוץ - email, sms, push, whatsapp, whatsapp_message, wallet, webhook והכינוי in_app - הוסרו וכעת נדחים ביצירה ובעדכון.

לכל פריט ב־edges יש id, ‏source, ‏target, ולפי הצורך גם sourceHandle, ‏targetHandle או label. השדה sourceHandle בוחר את יציאת המקור בצמתים בעלי כמה יציאות (קבוצות של צומת הסתעפות, או did ו־timed_out בפיצול לפי התנהגות).

טריגר כניסה

ל־entryTrigger יש type ו־config שתלוי בסוג. אלה הסוגים החוקיים: event, api, entity_change, whatsapp_inbound, sms_inbound, viber_inbound, attribute_change, subscription_status, schedule.

Segment Entry אינו טריגר. לכניסות שנגרמות ממשהו שהאדם עשה, השתמשו בטריגר אירוע עם מסנן; לכניסות שנגרמות מחלוף הזמן, השתמשו במסע חוזר על הסגמנט.

וריאנטים של המסע כולו

כל פריט ב־variants כולל id, ‏name, ‏percentage (בין 0 ל־100; סכום כל הווריאנטים חייב להיות 100), ‏isControlGroup (וריאנט ביקורת הוא קבוצת ביקורת נמדדת שאינה עוברת בתהליך) ו־triggerNodeId (צומת הטריגר שממנו מתחיל וריאנט הטיפול). ראו אנליטיקת מסעות להסבר על אופן הדיווח של תוצאות הווריאנטים. בעבר נקרא השדה isControl; הכתיב הזה עדיין מתקבל בכתיבה ומומר ל־isControlGroup.

דוגמת בקשה

curl -X POST https://api-eu1.joryio.com/api/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/api/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/api/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`). רק למסע שכבר פעיל (`status: active`); אחרת `409` עם `code: "journey_not_live"` - הפעלה ראשונה דרך `POST /journeys/:canvasId/activate`.
`POST`	`/journeys/:canvasId/rerun`	`canvas:activate`	ריצה חוזרת של הגרסה המפורסמת ללא יצירת גרסה חדשה

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

הכנסת משתמש (טריגר API)

רישום משתמש ספציפי למסע - נתיב הכניסה עבור entryTrigger.type: "api".

POST /journeys/:canvasId/enter/:userId

הרשאה: canvas:enter (כלולה ב-canvas:activate), כך שאינטגרציה כמו Zapier יכולה להוסיף אנשים למסע בלי יכולת להפעיל, להשהות או לערוך אותו.

גוף אופציונלי: context - אובייקט JSON שזמין לריצה (אפשר לקרוא אותו בהודעות ובתנאים כמשתני הקשר של המסע).

curl -X POST https://api-eu1.joryio.com/api/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/enterable?q=

המסעות הפעילים (active), בצורה { "data": [{ "id", "name", "activatedAt" }] }, ממוינים לפי שם, עד 100; q מסנן לפי חלק מהשם. הרשאה: canvas:enter (או canvas:read) - אינטגרציה שרשאית להוסיף אנשים למסעות יכולה לבחור מסע בלי לקרוא את המסעות עצמם.

ריצות ואנליטיקה

שיטה	נתיב	תיאור
`GET`	`/journeys/:canvasId/executions`	רשימת ריצות (`status`, ‏`limit` עד 100, `offset`)
`GET`	`/journeys/:canvasId/executions/:executionId`	שליפת ריצה בודדת. כל שלב Webhook ב‑`history` כולל `webhook` (סטטוס, הצלחה, משך, ניסיונות, שגיאה, שדות שנשמרו); קריאה שנכשלה (לא 2xx) מוסיפה `webhook.response` (`{ status, contentType, body, truncated }`) - מוסתרת, 2 KB הראשונים של הגוף, נשמרת 30 יום, מוחזרת רק למי שיש לו `pii:view` (מפתח API רק עם הרשאה זו; אחרים מקבלים `webhook.responseHidden: true`). גוף של תגובה מוצלחת לעולם לא נשמר
`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/recovered-carts`	העגלות הנטושות שהמסע שחזר - הרשימה שמאחורי `revenue.recoveredCarts` ב-`/stats`, מאותה שאילתה, כך ש-`total` שווה לספירה הזו לאותם `startDate`/`endDate` (עגלות ששוחזרו בטווח; סוף בתאריך בלבד כולל את כל היום, לפי אזור הזמן של סביבת העבודה). `limit` ‏1-100 (ברירת מחדל 25), `offset`; מהחדשה לישנה. שורות: `orderNumber` (של החנות), `placedAt`, `recoveredAt`, `match` (`recovery_link`, `order` = אותה עגלה, `reported`), `cartValue`/`cartCurrency`, `creditedRevenue`/`creditedCurrency` (אחרי החזרים), `contact` (בעל העגלה) ו-`buyer` (רק כשההזמנה נשמרה תחת מישהו אחר); שמות אנשי קשר מוסתרים בלי `pii:view`. מחזיר `{ data, total, limit, offset, summary }`
`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`	שחזור לגרסה. רק למסעות פעילים; אחרת `409 journey_not_live`.
`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 והחזרת התגובה בזמן אמת יחד עם הבקשה שנשלחה (פרטי הזדהות מוסתרים). `user.userId` מרנדר איש קשר אמיתי מסביבת העבודה בדיוק כמו בשליחה אמיתית; אחרת נעשה שימוש בערכים לדוגמה (כפוף להגבלת קצב)
`POST`	`/journeys/preview-context-value`	הפקת ביטוי Liquid מול הקשר לדוגמה
`POST`	`/journeys/preview-user-updates`	הרצה מדומה של שורות צומת Update User מול משתמש לדוגמה
`POST`	`/journeys/preview-user-update-json`	הרצה מדומה של JSON מותאם בצומת Update User: נכנס `{ json, sample }`, יוצא `{ errors, preview: { errors, result } }`. `errors` חוסמים שמירה או הפעלה; `preview` הוא ה-JSON מרונדר מול הדוגמה. לא כותב דבר
`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`	ההודעה שהופקה עבור שילוב של ריצה וצומת

בדיקת שיגור

אותה בדיקה שלפני שליחה שקמפיינים מקבלים (ראו את מדריך בדיקת השיגור), רצה על כל צומת הודעה: קישור הסרה, שדות מיזוג, אימות שולח, קישורים לא שמישים, אורך נושא, גרסת טקסט חסרה, שעות שקט, ובנוסף node_unreachable לצמתים שאף טריגר לא מגיע אליהם, cart_variable_no_cart_trigger להודעה שקוראת cart במסע שלא מתחיל באירוע עגלה, וגם channel_not_set_up לערוץ שהמסע משתמש בו ואין לו ספק או שולח (params.channel; חוסם, או המלצה עם params.sandbox: 1 בסביבת עבודה לדוגמה, שבה השליחות מדומות לכולם). גם הפעלה ופרסום מריצים אותה.

GET /journeys/{canvasId}/launch-review

הרשאה: canvas:read. לתגובה המבנה המתועד ב-API הקמפיינים; ממצא של צומת נושא scope.kind = "node", scope.id = מזהה הצומת ו-fix.nodeId.

כשסביבת העבודה דורשת רשימה נקייה (settings.launchReview.requireClean, ברירת מחדל true) ויש חוסמים, POST /journeys/{canvasId}/activate ו-POST /journeys/{canvasId}/publish עונים 409 עם code: "launch_review_blocked" והחוסמים בגוף.

תגובות שגיאה

כל השגיאות משתמשות במבנה הסטנדרטי - ראו תגובת שגיאה בסקירת ה־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"
}

אימות​

רשימת מסעות​

פרמטרי שאילתה​

דוגמת בקשה​

תגובה​

יצירת מסע​

גוף הבקשה​

מבנה צומת​

טריגר כניסה​

וריאנטים של המסע כולו​

דוגמת בקשה​

שליפת מסע​

עדכון מסע​

מחיקת מסע​

נקודות קצה של סטטוס​

הכנסת משתמש (טריגר API)​

רשימת המסעות שאפשר להכניס אליהם אדם​

ריצות ואנליטיקה​

נקודות קצה נוספות​

בדיקת שיגור​

תגובות שגיאה​

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

אימות

רשימת מסעות

פרמטרי שאילתה

דוגמת בקשה

תגובה

יצירת מסע

גוף הבקשה

מבנה צומת

טריגר כניסה

וריאנטים של המסע כולו

דוגמת בקשה

שליפת מסע

עדכון מסע

מחיקת מסע

נקודות קצה של סטטוס

הכנסת משתמש (טריגר API)

רשימת המסעות שאפשר להכניס אליהם אדם

ריצות ואנליטיקה

נקודות קצה נוספות

בדיקת שיגור

תגובות שגיאה

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