E-Commerce API

ניהול קטלוג המוצרים שלך, מעקב אחר הזמנות, ניטור פעילות עגלות וניתוח פלחי לקוחות RFM.

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

מוסכמת שמות מזהים

Joryio משתמש במוסכמת שמות ברורה למזהים:

המזהים שלך (השתמש בהם בעת יצירה/מעקב של נתונים)

שדה	תיאור	דוגמה
`productId`	מזהה המוצר שלך (מק"ט, מזהה מוצר מהפלטפורמה שלך)	`"SKU-12345"`
`orderId`	מזהה ההזמנה שלך (מספר הזמנה מהפלטפורמה שלך)	`"ORD-2024-001"`
`userId`	מזהה המשתמש שלך	`"user-123"`

מזהי Joryio (מוחזרים בתגובות API)

שדה	תיאור	מתי להשתמש
`id`	המזהה הפנימי של Joryio למוצרים/הזמנות	מוחזר בתגובות API, השתמש לעדכונים/מחיקות
`joryioUserId`	מזהה משתמש פנימי של Joryio (ה-`id` בן 24 התווים המוחזר בתגובות ה-API של משתמשים)	חלופה ל-`userId` כאשר רוצים להתייחס למזהה של Joryio

זיהוי משתמשים גמיש

בעת יצירת הזמנות או מעקב אחר אירועים, ניתן לזהות משתמשים באמצעות אחד מהבאים:

userId - מזהה המשתמש שלך (הנפוץ ביותר)
joryioUserId - מזהה משתמש פנימי של Joryio

// Using your user ID (recommended)
{ "orderId": "ORD-001", "userId": "user-123", ... }

// Using Joryio's internal user ID
{ "orderId": "ORD-001", "joryioUserId": "66a1f2c3d4e5f6a7b8c9d0e1", ... }

אימות

כל הבקשות דורשות אימות JWT:

Authorization: Bearer your_jwt_token
Content-Type: application/json
X-Workspace-Id: your_workspace_id

קטלוג מוצרים

יצירת מוצר

יצירת מוצר חדש בקטלוג.

POST /catalog/products

גוף הבקשה:

שדה	סוג	חובה	תיאור
`productId`	string	כן	מזהה המוצר הייחודי שלך (מק"ט, מזהה מוצר)
`name`	string	כן	שם המוצר
`price`	number	כן	מחיר המוצר
`description`	string	לא	תיאור המוצר
`compareAtPrice`	number	לא	מחיר מקורי (להנחות)
`currency`	string	לא	קוד מטבע (ברירת מחדל: USD)
`categories`	string[]	לא	קטגוריות המוצר
`tags`	string[]	לא	תגיות המוצר
`brand`	string	לא	שם המותג
`imageUrl`	string	לא	כתובת תמונה ראשית
`url`	string	לא	כתובת דף המוצר
`inStock`	boolean	לא	זמינות במלאי (ברירת מחדל: true)
`sku`	string	לא	מק"ט
`variants`	object[]	לא	וריאנטים של המוצר
`customFields`	object	לא	שדות מותאמים אישית

דוגמת בקשה:

curl -X POST https://api-eu1.joryio.com/catalog/products \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "SKU-12345",
    "name": "Classic Blue T-Shirt",
    "price": 29.99,
    "compareAtPrice": 39.99,
    "currency": "USD",
    "categories": ["Clothing", "T-Shirts"],
    "tags": ["sale", "bestseller"],
    "brand": "Acme Apparel",
    "imageUrl": "https://example.com/images/blue-tshirt.jpg",
    "url": "https://example.com/products/blue-tshirt",
    "inStock": true,
    "sku": "BTS-001-BL",
    "variants": [
      {
        "id": "var-s",
        "name": "Small",
        "sku": "BTS-001-BL-S",
        "price": 29.99,
        "inStock": true,
        "options": { "size": "S", "color": "Blue" }
      },
      {
        "id": "var-m",
        "name": "Medium",
        "sku": "BTS-001-BL-M",
        "price": 29.99,
        "inStock": true,
        "options": { "size": "M", "color": "Blue" }
      }
    ]
  }'

תגובה:

{
  "id": "prod_abc123",
  "productId": "SKU-12345",
  "name": "Classic Blue T-Shirt",
  "price": 29.99,
  "createdAt": "2024-01-20T10:00:00.000Z"
}

יצירה או עדכון של מוצרים בכמות גדולה (array body)

אין נקודת קצה נפרדת לפעולה באצווה: POST /catalog/products מקבל או אובייקט מוצר יחיד או מערך JSON חשוף של אובייקטי מוצר (ללא אובייקט עוטף). צורת המערך יוצרת או מעדכנת עד 500 מוצרים בבקשה אחת, לפי productId.

POST /catalog/products

גוף הבקשה:

מערך JSON (עד 500 איברים; מערך ריק או יותר מ־500 מחזיר 400). כל איבר באותו פורמט כמו הצורה של אובייקט בודד, כולל שדה source אופציונלי לכל מוצר.

כל איבר עובר תיקוף מלא. איבר לא תקין מדווח ב־failed לפי האינדקס שלו במערך - הוא לעולם אינו מתקבל ללא התראה - ושאר האיברים התקינים עדיין נכתבים.

[
  { "productId": "SKU-001", "name": "Product 1", "price": 19.99 },
  { "productId": "SKU-002", "name": "Product 2", "price": 29.99, "source": "shopify" }
]

תגובה:

בשונה מצורת האובייקט (שמחזירה את המוצר שנוצר), צורת המערך מחזירה סיכום מצרפי:

{
  "processed": 2,
  "upserted": 2,
  "failed": []
}

שדה	תיאור
`processed`	מספר האיברים שהתקבלו במערך הבקשה
`upserted`	מוצרים שנוצרו או עודכנו בפועל
`failed`	כשלים לכל איבר: `index` (מיקום במערך הבקשה), `productId` / `sku` (כשקיימים על האיבר), `reason`

רשימת מוצרים

שאילתת מוצרים עם סינון ודפדוף.

GET /catalog/products

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

פרמטר	סוג	תיאור
`search`	string	חיפוש לפי שם, תיאור או מק"ט
`categories`	string[]	סינון לפי קטגוריות
`tags`	string[]	סינון לפי תגיות
`brand`	string	סינון לפי מותג
`inStock`	boolean	סינון לפי זמינות במלאי
`minPrice`	number	מחיר מינימלי
`maxPrice`	number	מחיר מקסימלי
`limit`	number	תוצאות לעמוד (ברירת מחדל: 50)
`offset`	number	היסט לדפדוף
`sortBy`	string	שדה מיון: name, price, createdAt, updatedAt
`sortOrder`	string	asc או desc

דוגמה:

curl "https://api-eu1.joryio.com/catalog/products?categories=T-Shirts&inStock=true&limit=20" \
  -H "Authorization: Bearer $TOKEN"

קבלת קטגוריות

רשימת כל קטגוריות המוצרים.

GET /catalog/categories

קבלת מותגים

רשימת כל מותגי המוצרים.

GET /catalog/brands

סטטיסטיקות קטלוג

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

GET /catalog/stats

תגובה:

{
  "productCount": 8214,
  "categoryCount": 37,
  "brandCount": 12,
  "outOfStockCount": 341,
  "lowStockCount": 96,
  "unclassifiedCount": 18,
  "lowStockThreshold": 10
}

שדה	תיאור
`outOfStockCount`	מוצרים עם `quantity` 0, או `inStock: false` כשאין מעקב כמות
`lowStockCount`	מוצרים עם `quantity` בין 1 ל-`lowStockThreshold`
`unclassifiedCount`	מוצרים ללא קטגוריה או ללא מותג
`lowStockThreshold`	סף היחידות שלפיו חושב `lowStockCount`

הזמנות

יצירת הזמנה

מעקב אחר הזמנה חדשה.

POST /orders

גוף הבקשה:

שדה	סוג	חובה	תיאור
`orderId`	string	כן	מזהה ההזמנה שלך (מספר הזמנה מהפלטפורמה שלך)
`userId`	string	אחד מהשניים	מזהה המשתמש של הלקוח שלך
`joryioUserId`	string	אחד מהשניים	מזהה משתמש פנימי של Joryio (חלופה ל-userId)
`total`	number	כן	סכום ההזמנה הכולל
`items`	object[]	כן	פריטים בהזמנה
`status`	string	לא	סטטוס הזמנה (ברירת מחדל: pending)
`currency`	string	לא	קוד מטבע
`subtotal`	number	לא	סכום ביניים לפני הנחות
`discount`	number	לא	סכום הנחה
`shipping`	number	לא	עלות משלוח
`tax`	number	לא	סכום מס
`totalRefunded`	number	לא	הסכום שהוחזר עד כה, במטבע ההזמנה (ברירת מחדל 0). להחזר חלקי שלחו את הסכום החלקי עם `status: partiallyRefunded`; להחזר מלא הגדירו אותו ל-`total` עם `status: refunded`. החזרים מקוזזים מההכנסה המיוחסת.
`couponCode`	string	לא	קופון שהופעל
`shippingAddress`	object	לא	כתובת משלוח
`campaignId`	string	לא	קמפיין ייחוס
`canvasId`	string	לא	מסע הייחוס
`source`	string	לא	מקור ההזמנה (email, sms, direct)
`utmSource`	string	לא	מקור UTM
`utmMedium`	string	לא	מדיום UTM
`utmCampaign`	string	לא	קמפיין UTM

זיהוי משתמשים

יש לספק userId או joryioUserId. השתמש ב-userId עם מזהי המשתמשים שלך (הנפוץ ביותר). השתמש ב-joryioUserId כאשר יש לך את מזהה המשתמש הפנימי של Joryio (ה-id בן 24 התווים המוחזר בתגובות ה-API).

מבנה פריט:

{
  "productId": "prod_abc123",
  "name": "Blue T-Shirt",
  "sku": "BTS-001",
  "quantity": 2,
  "price": 29.99,
  "total": 59.98,
  "imageUrl": "https://example.com/image.jpg"
}

דוגמת בקשה:

curl -X POST https://api-eu1.joryio.com/orders \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "ORD-2024-001",
    "userId": "user-123",
    "total": 89.97,
    "subtotal": 99.97,
    "discount": 10.00,
    "shipping": 5.99,
    "tax": 4.99,
    "currency": "USD",
    "couponCode": "SAVE10",
    "items": [
      {
        "productId": "prod_abc123",
        "name": "Blue T-Shirt",
        "quantity": 2,
        "price": 29.99,
        "total": 59.98
      },
      {
        "productId": "prod_def456",
        "name": "Black Jeans",
        "quantity": 1,
        "price": 49.99,
        "total": 49.99
      }
    ],
    "source": "email",
    "campaignId": "camp_xyz789"
  }'

סימון הזמנה כנשלחה

סימון הזמנה כנשלחה.

POST /orders/:id/fulfill

גוף הבקשה:

{
  "trackingNumber": "1Z999AA10123456784",
  "carrier": "UPS"
}

ביטול הזמנה

ביטול הזמנה.

POST /orders/:id/cancel

גוף הבקשה:

{
  "reason": "Customer requested cancellation"
}

החזר כספי להזמנה

עיבוד החזר כספי.

POST /orders/:id/refund

גוף הבקשה:

{
  "refundAmount": 29.99,
  "reason": "Product defective",
  "partial": true
}

סטטיסטיקות הזמנות

קבלת סטטיסטיקות הזמנות לטווח תאריכים.

GET /orders/stats?startDate=2024-01-01&endDate=2024-01-31

תגובה:

{
  "totalOrders": 156,
  "totalRevenue": 12450.50,
  "averageOrderValue": 79.81,
  "ordersByStatus": {
    "pending": 5,
    "processing": 12,
    "shipped": 45,
    "delivered": 90,
    "cancelled": 4
  }
}

מעקב עגלות

עדכון עגלה

מעקב או עדכון עגלת משתמש.

PUT /carts

גוף הבקשה:

{
  "userId": "user_123",
  "items": [
    {
      "productId": "prod_abc123",
      "name": "Blue T-Shirt",
      "price": 29.99,
      "quantity": 2,
      "total": 59.98,
      "imageUrl": "https://example.com/image.jpg"
    }
  ],
  "value": 59.98,
  "currency": "USD",
  "checkoutUrl": "https://store.example.com/checkout?cart=abc123"
}

הוספה לעגלה

הוספת פריט לעגלת משתמש.

POST /carts/add

גוף הבקשה:

{
  "userId": "user_123",
  "item": {
    "productId": "prod_abc123",
    "name": "Blue T-Shirt",
    "price": 29.99,
    "quantity": 1,
    "total": 29.99
  }
}

קבלת עגלות נטושות

רשימת עגלות נטושות לקמפיינים של שחזור.

GET /carts/abandoned

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

פרמטר	סוג	תיאור
`minValue`	number	ערך עגלה מינימלי
`abandonedMinutesAgo`	number	מספר הדקות המרבי מאז הנטישה
`limit`	number	תוצאות לעמוד
`offset`	number	היסט לדפדוף

תגובה:

{
  "data": [
    {
      "id": "cart_123",
      "userId": "user_456",
      "items": [...],
      "value": 149.99,
      "abandonedAt": "2024-01-20T15:30:00.000Z",
      "checkoutUrl": "https://store.example.com/checkout?cart=abc"
    }
  ],
  "total": 42,
  "hasMore": true
}

סטטיסטיקות עגלות

קבלת סטטיסטיקות עגלות ונטישה.

GET /carts/stats

תגובה:

{
  "totalCarts": 1250,
  "abandonedCarts": 312,
  "recoveredCarts": 87,
  "totalAbandonedValue": 45670.50,
  "recoveryRate": 27.88
}

ניתוח RFM

ניתוח RFM (עדכניות, תדירות, ערך כספי) מפלח לקוחות על סמך התנהגות רכישה.

קבלת נתוני RFM של משתמש

קבלת ציוני RFM ופלח עבור משתמש ספציפי.

GET /rfm/user/:userId

תגובה:

{
  "totalOrders": 12,
  "totalSpent": 849.50,
  "averageOrderValue": 70.79,
  "firstOrderDate": "2023-06-15T10:00:00.000Z",
  "lastOrderDate": "2024-01-18T14:30:00.000Z",
  "daysSinceLastOrder": 2,
  "hasActiveCart": false,
  "rfmRecency": 5,
  "rfmFrequency": 4,
  "rfmMonetary": 4,
  "rfmScore": "544",
  "rfmSegment": "champions"
}

קבלת התפלגות RFM

קבלת התפלגות לקוחות על פני פלחי RFM.

GET /rfm/distribution

תגובה:

{
  "champions": { "count": 150, "totalValue": 125000 },
  "loyal": { "count": 320, "totalValue": 89000 },
  "potential_loyalists": { "count": 180, "totalValue": 32000 },
  "new_customers": { "count": 450, "totalValue": 28000 },
  "at_risk": { "count": 95, "totalValue": 42000 },
  "lost": { "count": 280, "totalValue": 15000 }
}

פלחי RFM

פלח	תיאור	ציוני RFM אופייניים
Champions (אלופים)	הלקוחות הטובים ביותר, קונים לעיתים קרובות, מוציאים הכי הרבה	555, 554, 545
Loyal (נאמנים)	לקוחות עקביים	444, 443, 434
Potential Loyalists (נאמנים פוטנציאליים)	לקוחות אחרונים עם תדירות ממוצעת	433, 343, 333
New Customers (לקוחות חדשים)	רק ביצעו רכישה ראשונה	511, 512, 411
Promising (מבטיחים)	אחרונים אך תדירות נמוכה	422, 322, 312
Needs Attention (דורשים תשומת לב)	ממוצעים, מעורבות יורדת	332, 322, 233
About to Sleep (עומדים להירדם)	מתחת לממוצע, בסיכון	211, 212, 221
At Risk (בסיכון)	היו נאמנים, לא קנו לאחרונה	144, 143, 244
Can't Lose (אסור לאבד)	היו הלקוחות הטובים ביותר, כעת לא פעילים	155, 154, 255
Hibernating (במצב שינה)	מעורבות נמוכה, לא פעילים זמן רב	122, 121, 112
Lost (אבודים)	ציונים נמוכים ביותר, כנראה נטשו	111

Webhooks

אירועי מסחר אלקטרוני שולחים Webhooks שיכולים להפעיל מסעות:

אירוע	תיאור
`ecommerce.order.created`	הזמנה חדשה בוצעה
`ecommerce.order.fulfilled`	הזמנה נשלחה
`ecommerce.order.cancelled`	הזמנה בוטלה
`ecommerce.order.refunded`	הזמנה הוחזרה
`ecommerce.order.status_changed`	סטטוס הזמנה השתנה
`ecommerce.cart.abandoned`	עגלה סומנה כנטושה
`ecommerce.cart.recovered`	עגלה נטושה שוחזרה
`ecommerce.cart.updated`	תוכן העגלה השתנה

חיפוש לפי המזהים שלכם

קבלת מוצר לפי מזהה המוצר שלך

קבלת מוצר באמצעות מזהה המוצר שלך.

GET /catalog/products/by-product-id/:productId

דוגמה:

curl "https://api-eu1.joryio.com/catalog/products/by-product-id/SKU-12345" \
  -H "Authorization: Bearer $TOKEN"

קבלת הזמנה לפי מזהה ההזמנה שלך

קבלת הזמנה באמצעות מזהה ההזמנה שלך.

GET /orders/by-order-id/:orderId

דוגמה:

curl "https://api-eu1.joryio.com/orders/by-order-id/ORD-2024-001" \
  -H "Authorization: Bearer $TOKEN"

תגובות שגיאה

{
  "statusCode": 404,
  "message": "Product SKU-12345 not found",
  "error": "Not Found"
}

קוד סטטוס	תיאור
400	גוף בקשה לא תקין
401	נדרש אימות
403	הרשאות לא מספיקות
404	משאב לא נמצא
409	התנגשות (מזהה חיצוני כפול)
500	שגיאת שרת פנימית

מוסכמת שמות מזהים​

המזהים שלך (השתמש בהם בעת יצירה/מעקב של נתונים)​

מזהי Joryio (מוחזרים בתגובות API)​

זיהוי משתמשים גמיש​

אימות​

קטלוג מוצרים​

יצירת מוצר​

יצירה או עדכון של מוצרים בכמות גדולה (array body)​

רשימת מוצרים​

קבלת קטגוריות​

קבלת מותגים​

סטטיסטיקות קטלוג​

הזמנות​

יצירת הזמנה​

סימון הזמנה כנשלחה​

ביטול הזמנה​

החזר כספי להזמנה​

סטטיסטיקות הזמנות​

מעקב עגלות​

עדכון עגלה​

הוספה לעגלה​

קבלת עגלות נטושות​

סטטיסטיקות עגלות​

ניתוח RFM​

קבלת נתוני RFM של משתמש​

קבלת התפלגות RFM​

פלחי RFM​

Webhooks​

חיפוש לפי המזהים שלכם​

קבלת מוצר לפי מזהה המוצר שלך​

קבלת הזמנה לפי מזהה ההזמנה שלך​

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

מוסכמת שמות מזהים

המזהים שלך (השתמש בהם בעת יצירה/מעקב של נתונים)

מזהי Joryio (מוחזרים בתגובות API)

זיהוי משתמשים גמיש

אימות

קטלוג מוצרים

יצירת מוצר

יצירה או עדכון של מוצרים בכמות גדולה (array body)

רשימת מוצרים

קבלת קטגוריות

קבלת מותגים

סטטיסטיקות קטלוג

הזמנות

יצירת הזמנה

סימון הזמנה כנשלחה

ביטול הזמנה

החזר כספי להזמנה

סטטיסטיקות הזמנות

מעקב עגלות

עדכון עגלה

הוספה לעגלה

קבלת עגלות נטושות

סטטיסטיקות עגלות

ניתוח RFM

קבלת נתוני RFM של משתמש

קבלת התפלגות RFM

פלחי RFM

Webhooks

חיפוש לפי המזהים שלכם

קבלת מוצר לפי מזהה המוצר שלך

קבלת הזמנה לפי מזהה ההזמנה שלך

תגובות שגיאה