סקירת API

Joryio REST API מספק גישה תכנותית לכל יכולות הפלטפורמה.

כתובת בסיס

https://api-eu1.joryio.com

כל סביבות העבודה מוגשות כיום מאזור יחיד; נקודות קצה אזוריות יתועדו כאשר אזורים נוספים יושקו.

אימות

כל בקשות ה־API דורשות אימות באמצעות מפתח API. מפתחות משויכים לסביבת עבודה אחת, נושאים מערך הרשאות מפורש וניתן להגביל אותם לרשימת כתובות IP. ראו את מסמך מפתחות API לקטלוג ההרשאות המלא ולהסבר על התנהגות ה־IP allowlist.

GET /users/by-user-id/user_123
Host: api-eu1.joryio.com
Authorization: Bearer jry_live_your_api_key_here
Content-Type: application/json

העבירו את המפתח כטוקן Bearer בכותרת Authorization בכל בקשה. מפתחות תמיד מתחילים ב־jry_live_ (סביבת ייצור) או jry_test_ (בדיקה). את הקידומת הגלויה של המפתח (לדוגמה jry_live_98f31a72) אפשר לתעד בבטחה ביומנים - השאר סודי.

קבלת מפתח API

התחברו ללוח הבקרה של Joryio.
עברו אל Settings → API Keys.
לחצו Create API Key, בחרו את ההרשאות שהאינטגרציה צריכה והעתיקו את הערך שמוצג פעם אחת בלבד.

שמרו על מפתחות API בסוד

לעולם אל תשמרו מפתחות API בבקרת גרסאות ואל תחשפו אותם בקוד בצד הלקוח. הערך המלא מוצג פעם אחת בלבד לאחר היצירה - שמרו אותו מיד במנהל הסודות שלכם.

אוסף Postman

הדרך המהירה ביותר להכיר את ה־API היא לייבא את האוסף הרשמי ל־Postman. הוא כולל כל נקודת קצה ציבורית עם גוף בקשה לדוגמה, ומוגדר מראש עם המשתנה {{baseUrl}} ועם אימות באמצעות טוקן Bearer.

הורידו את האוסף
ב־Postman: Import → גררו את הקובץ פנימה.
הגדירו את משתני האוסף: baseUrl = https://api-eu1.joryio.com, token = מפתח ה־API שלכם (jry_live_...).

פורמט בקשה

כל הבקשות והתגובות משתמשות ב־JSON:

POST /users
Content-Type: application/json

{
  "userId": "user_123",
  "email": "user@example.com",
  "attributes": {
    "plan": "premium"
  }
}

פורמט תגובה

נקודות הקצה מחזירות את ה־JSON של המשאב ישירות - אין מעטפת { "success": true, "data": ... }.

תגובת הצלחה

לדוגמה, GET /users/by-user-id/user_123 מחזיר את אובייקט המשתמש עצמו:

{
  "id": "665f1e2a9b3c4d5e6f7a8b9c",
  "userId": "665f1e2a9b3c4d5e6f7a8b9c",
  "externalId": "user_123",
  "email": "user@example.com",
  "phone": "+14155550123",
  "attributes": { "plan": "premium" },
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-01-15T10:30:00.000Z"
}

id / userId הם המזהה הפנימי של Joryio; המזהה שסיפקתם מוחזר בשדה externalId.

תגובת שגיאה

לכל השגיאות מבנה אחיד, שמופק באמצעות מסנן חריגות גלובלי:

{
  "statusCode": 400,
  "message": "Cannot create user without a valid identifier (userId, externalId, or email)",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "path": "/users"
}

כשלי תיקוף של הבקשה (400) כוללים גם מערך errors ובו הודעה לכל שדה שנכשל:

{
  "statusCode": 400,
  "message": "Bad Request Exception",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "path": "/events/track",
  "errors": [
    "eventName must be shorter than or equal to 500 characters"
  ]
}

קודי סטטוס HTTP

קוד	משמעות	תיאור
`200`	OK	הבקשה הצליחה
`201`	Created	המשאב נוצר בהצלחה
`204`	No Content	מחיקה הצליחה (גוף תגובה ריק)
`400`	Bad Request	פרמטרים לא תקינים
`401`	Unauthorized	מפתח API שגוי או חסר
`403`	Forbidden	למפתח ה־API אין הרשאות נדרשות
`404`	Not Found	המשאב לא נמצא
`409`	Conflict	המשאב כבר קיים
`429`	Too Many Requests	חריגה ממגבלת קצב
`500`	Internal Server Error	שגיאת שרת
`503`	Service Unavailable	השירות אינו זמין זמנית

מגבלות קצב

נקודות הקצה המרכזיות של ה־API (משתמשים, אירועים, סגמנטים וקמפיינים) אינן אוכפות כיום מגבלות קצב קבועות לכל נקודת קצה. הגבלת קצב חלה על ממשקים שמועדים לשימוש לרעה - נקודות קצה לאימות ומקלטי Webhook נכנסים - בחלונות קבועים של דקה.

כאשר בקשה נחסמת, ה־API מחזיר 429 Too Many Requests עם כותרת Retry-After (שניות עד לאיפוס החלון):

HTTP/1.1 429 Too Many Requests
Retry-After: 42

{
  "statusCode": 429,
  "message": "Too Many Requests",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "path": "/auth/login"
}

טיפול במגבלות קצב

ייתכן שמגבלות יתווספו או יוחמרו בעתיד - לאחר 429 תמיד נסו שוב, כבדו את Retry-After וממשו השהיה מעריכית:

async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || Math.pow(2, i);
      await sleep(retryAfter * 1000);
      continue;
    }

    return response;
  }
}

עימוד

נקודות קצה של רשימות מעמדות באמצעות פרמטרי השאילתה limit / offset:

GET /users?limit=50&offset=100

פרמטרים:

limit: תוצאות לעמוד (ברירות המחדל והערכים המרביים משתנים לפי נקודת הקצה - משתמשים: ברירת מחדל 50, לכל היותר 200; סגמנטים: ברירת מחדל 100, לכל היותר 100; שאילתת אירועים: ברירת מחדל 100, לכל היותר 1000)
offset: מספר פריטים לדילוג (ברירת מחדל: 0)

תגובה:

תגובות של רשימות מעומדות עוטפות את העמוד במערך data בתוספת אובייקט pagination:

{
  "data": [...],
  "pagination": {
    "total": 1234,
    "limit": 50,
    "offset": 100,
    "hasMore": true
  }
}

חלק מנקודות הקצה כוללות שדות עימוד נוספים (כגון page / totalPages), וחלק מהרשימות הקטנות מחזירות מערך JSON חשוף - העמוד של כל נקודת קצה מתעד את המבנה המדויק שלה.

סינון

אין תחביר כללי של filter[field] או sort. נקודות קצה שמחזירות רשימות מספקות במקום זאת פרמטרי מסנן ייעודיים, לדוגמה:

GET /events/query?eventName=Order+Completed&startDate=2026-01-01&endDate=2026-01-31
GET /segments?q=vip&status=active&tags=onboarding
GET /users/search?query=jane

התוצאות מוחזרות בסדר קבוע, מהעדכני ביותר לישן.

אידמפוטנטיות

אין כותרת בקשה גנרית Idempotency-Key. בטיחות בניסיון חוזר מסופקת לפי נקודת קצה:

POST /users מבצע יצירה או עדכון (upsert) לפי ה־userId שלכם - ניסיון חוזר של אותה בקשה מעדכן את אותו פרופיל במקום ליצור כפילות.
POST /events/track מקבל clientEventId אופציונלי; הוא משמש כמזהה האירוע השמור, ולכן כפילות מוסרת מבקשה חוזרת עם אותו clientEventId.
POST /campaigns/transactional/send מקבל idempotencyKey אופציונלי בגוף הבקשה - ניסיון חוזר עם אותו מפתח לא ישלח פעמיים.

חותמות זמן

כל חותמות הזמן הן בפורמט ISO 8601 עם אזור זמן UTC:

{
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T14:45:30.000Z"
}

נקודות קצה

Users API

שיטה	Endpoint	תיאור
POST	`/users`	יצירה או עדכון של משתמש בודד (גוף אובייקט) או רבים (גוף מערך חשוף, עד 1000)
GET	`/users`	רשימת משתמשים (`limit` / `offset`)
GET	`/users/search`	חיפוש משתמשים לפי אימייל, שם, טלפון או מזהה
GET	`/users/:userId`	קבלת משתמש לפי המזהה הפנימי של Joryio
GET	`/users/by-user-id/:userId`	קבלת משתמש לפי ה־`userId` שלכם
PUT	`/users/:userId`	עדכון משתמש לפי מזהה פנימי
PUT	`/users/by-user-id/:userId`	עדכון משתמש לפי ה־`userId` שלכם
DELETE	`/users/:userId`	מחיקת משתמש (מחזיר `204`)

Events API

שיטה	Endpoint	תיאור
POST	`/events/track`	מעקב אחר אירוע בודד (גוף אובייקט) או כמה אירועים (גוף מערך חשוף, עד 500)
GET	`/events/query`	שאילתת אירועים עם מסננים
POST	`/events/aggregate`	צבירת מדדי אירועים לאורך זמן

Campaigns API

שיטה	Endpoint	תיאור
POST	`/campaigns`	יצירת קמפיין
GET	`/campaigns/:id`	קבלת קמפיין
PUT	`/campaigns/:id`	עדכון קמפיין
DELETE	`/campaigns/:id`	מחיקת קמפיין
POST	`/campaigns/:id/send`	שליחת קמפיין
GET	`/campaigns/:id/stats`	סטטיסטיקות קמפיין

Segments API

שיטה	Endpoint	תיאור
POST	`/segments`	יצירת סגמנט
GET	`/segments`	רשימת סגמנטים
GET	`/segments/:id`	קבלת סגמנט
PUT	`/segments/:id`	עדכון סגמנט
POST	`/segments/:id/archive`	ארכוב סגמנט (סגמנטים אינם ניתנים למחיקה קשיחה)
GET	`/segments/:id/users`	משתמשים בסגמנט
GET	`/segments/:id/size`	גודל סגמנט

Apps API

שיטה	Endpoint	תיאור
POST	`/apps`	יצירת אפליקציה
GET	`/apps/:id`	קבלת אפליקציה
PUT	`/apps/:id`	עדכון אפליקציה
DELETE	`/apps/:id`	מחיקת אפליקציה
POST	`/apps/:id/regenerate-key`	יצירת מפתח SDK מחדש
GET	`/apps/:id/stats`	סטטיסטיקות אפליקציה

ערכות SDK

לשילוב קל יותר, השתמשו בערכות ה־SDK הרשמיות שלנו:

Web SDK: npm install @joryio/web-sdk
iOS SDK: Swift Package / CocoaPods
Android SDK: Gradle
React Native SDK: npm install @joryio/react-native-sdk

דוגמאות

יצירת משתמש

curl -X POST https://api-eu1.joryio.com/users \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "email": "user@example.com",
    "attributes": {
      "firstName": "John",
      "lastName": "Doe",
      "plan": "premium"
    }
  }'

מעקב אירוע

curl -X POST https://api-eu1.joryio.com/events/track \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "eventName": "Order Completed",
    "properties": {
      "orderId": "order_456",
      "total": 99.99,
      "currency": "USD"
    }
  }'

יצירת סגמנט

curl -X POST https://api-eu1.joryio.com/segments \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Users",
    "description": "Users on premium plan",
    "filterGroups": [{
      "filters": [{
        "type": "attribute",
        "field": "plan",
        "operator": "equals",
        "value": "premium"
      }],
      "operator": "AND"
    }],
    "groupOperator": "AND"
  }'

שליחת קמפיין

נקודת הקצה של השליחה אינה מקבלת גוף בקשה - התצורה השמורה של הקמפיין קובעת מה נשלח:

curl -X POST https://api-eu1.joryio.com/campaigns/:id/send \
  -H "Authorization: Bearer jry_live_your_api_key"

שגיאות

אין אוסף נפרד של קודי שגיאה לקריאה ממוכנת - השתמשו בקוד המצב של HTTP יחד עם השדה message בגוף השגיאה הסטנדרטי (ראו פורמט תגובה):

{
  "statusCode": 404,
  "message": "Segment with ID 3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d not found",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "path": "/segments/3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d"
}

בדיקות

אפשר ליצור מפתחות עם התווית test‏ (jry_test_...) כדי להבדיל במבט בין מפתחות אינטגרציה למפתחות סביבת ייצור - התווית אינה משנה את יכולות המפתח. לניסויים בטוחים, צרו סביבת עבודה נפרדת לבדיקות: סביבות עבודה מבודדות לחלוטין פרופילים, אירועים וקמפיינים, כך ששום ניסוי לא ייגע בנתוני סביבת ייצור או בנמענים אמיתיים. שליחות בדיקה לערוצים (אימיילים והודעות SMS לבדיקה) מובנות בעורכי הקמפיינים.

תמיכה

צריכים עזרה?

כתובת בסיס​

אימות​

קבלת מפתח API​

אוסף Postman​

פורמט בקשה​

פורמט תגובה​

תגובת הצלחה​

תגובת שגיאה​

קודי סטטוס HTTP​

מגבלות קצב​

טיפול במגבלות קצב​

עימוד​

סינון​

אידמפוטנטיות​

חותמות זמן​

נקודות קצה​

Users API​

Events API​

Campaigns API​

Segments API​

Apps API​

ערכות SDK​

דוגמאות​

יצירת משתמש​

מעקב אירוע​

יצירת סגמנט​

שליחת קמפיין​

שגיאות​

בדיקות​

תמיכה​