סקירת API

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

כתובת בסיס

https://api-eu1.joryio.com/api

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

אימות

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

GET /api/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

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

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

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

אוסף Postman

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

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

פורמט בקשה

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

POST /users/track
Content-Type: application/json

{
  "attributes": {
    "externalId": "user_123",
    "email": "[email protected]",
    "attributes": {
      "plan": "premium"
    }
  }
}

פורמט תגובה

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

תגובת הצלחה

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

{
  "id": "665f1e2a9b3c4d5e6f7a8b9c",
  "userId": "665f1e2a9b3c4d5e6f7a8b9c",
  "externalId": "user_123",
  "email": "[email protected]",
  "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": "/api/users/track",
  "errors": [
    "eventName must be shorter than or equal to 500 characters"
  ]
}

שגיאות בגוף הבקשה

גוף בקשה שהשרת אינו יכול לקרוא נדחה לפני שהוא מגיע לנקודת הקצה, עם message שמציין את הבעיה. הגוף ששלחתם לעולם אינו מוחזר בתגובה.

סטטוס	message	סיבה
400	Request body is not valid JSON.	ב-JSON יש שגיאת תחביר.
400	Request body must be a JSON object or array - a bare string, number, boolean or null is not accepted.	הרמה העליונה אינה אובייקט {...} או מערך [...].
413	Request body is too large - the limit is 1 MB.	הגוף גדול מ-1 MB.
415	Request body charset is not supported - send UTF-8.	ה-Content-Type מציין קידוד תווים שאינו UTF-8.

קודי סטטוס HTTP

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

מגבלות קצב

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

משטח	מגבלה	לפי
בקשות API	1,200/דקה	הארגון שלך
קליטת אנשי קשר ואירועים (POST /users/track)	6,000/דקה	הארגון שלך
כניסה ואיפוס סיסמה	5-10/דקה	כתובת IP

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

המגבלות הנוכחיות של החשבון שלך מוצגות ב־הגדרות -> שימוש, וניתן להעלות אותן. אם ייבוא גדול או שליחה עמוסה מתקרבים למגבלה, פנו ל־[email protected].

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

X-RateLimit-Limit: 1200
X-RateLimit-Remaining: 1188
X-RateLimit-Reset: 60

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/track מבצע יצירה או עדכון (upsert) לפי ה־externalId שלכם - ניסיון חוזר של אותה בקשה מעדכן את אותו פרופיל במקום ליצור כפילות.
• כל איבר ב־events מקבל 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/track	יצירה או עדכון של אנשים ורישום האירועים, הרכישות ומכשירי הפוש שלהם - כל שדה מקבל אובייקט בודד או מערך (עד 1000 attributes לבקשה)
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	/users/track	מעקב אחר אירוע בודד או כמה אירועים - events מקבל אובייקט בודד או מערך (עד 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/api/users/track \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "attributes": {
      "externalId": "user_123",
      "email": "[email protected]",
      "attributes": {
        "firstName": "John",
        "lastName": "Doe",
        "plan": "premium"
      }
    }
  }'

מעקב אירוע

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

יצירת סגמנט

curl -X POST https://api-eu1.joryio.com/api/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/api/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 מלא
• תיעוד מפתחים
• אימייל: [email protected]