E-Commerce API

أدر كتالوج المنتجات وتتبّع الطلبات وراقب نشاط السلات وحلل شرائح عملاء RFM.

كل نقاط النهاية في هذه الصفحة نسبية إلى عنوان الأساس https://api-eu1.joryio.com. راجع نظرة عامة على API.

اصطلاح تسمية المعرّفات

يستخدم Joryio اصطلاحاً واضحاً للمعرّفات.

معرّفاتك، استخدمها عند إنشاء البيانات أو تتبعها

الحقل	الوصف	المثال
productId	معرّف منتجك، SKU أو معرّف منصة التجارة الإلكترونية	"SKU-12345"
orderId	معرّف طلبك، رقم الطلب من منصتك	"ORD-2024-001"
userId	معرّف المستخدم لديك	"user-123"

معرّفات Joryio، تعاد في استجابات API

الحقل	الوصف	متى تستخدمه
id	معرّف Joryio الداخلي للمنتجات أو الطلبات	يُعاد في استجابات API؛ استخدمه للتحديث أو الحذف
joryioUserId	معرّف المستخدم الداخلي في Joryio، id سداسي من 24 حرفاً في استجابات Users 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	نعم	معرّف منتجك الفريد، SKU أو معرّف المنتج
name	string	نعم	اسم المنتج
price	number	نعم	سعر المنتج
description	string	لا	وصف المنتج
compareAtPrice	number	لا	السعر الأصلي للخصومات
currency	string	لا	رمز العملة، الافتراضي USD
categories	string[]	لا	فئات المنتج
tags	string[]	لا	وسوم المنتج
brand	string	لا	اسم العلامة التجارية
imageUrl	string	لا	URL لصورة المنتج الرئيسية
url	string	لا	URL لصفحة المنتج
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": "prod_abc123",
  "productId": "SKU-12345",
  "name": "Classic Blue T-Shirt",
  "price": 29.99,
  "createdAt": "2024-01-20T10:00:00.000Z"
}

Upsert جماعي للمنتجات، نص مصفوفة

لا توجد نقطة نهاية جماعية منفصلة: يقبل POST /catalog/products كائن منتج واحداً أو مصفوفة JSON مجردة من المنتجات، بلا كائن غلاف. ينشئ شكل المصفوفة أو يحدّث حتى 500 منتج في الطلب الواحد، وفق productId.

POST /catalog/products

المصفوفة بحد أقصى 500 عنصر؛ تعيد المصفوفة الفارغة أو ما يزيد على 500 رمز 400. يتبع كل عنصر تنسيق كائن المنتج الواحد، بما فيه الحقل الاختياري source لكل منتج.

يتحقق النظام من كل عنصر بالكامل. يُبلغ عن العنصر غير الصالح في failed بفهرسه ولا يُقبل بصمت، بينما تستمر عملية upsert للعناصر الصالحة.

[
  { "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	بحث بالاسم أو الوصف أو SKU
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

---

الطلبات

إنشاء طلب

تتبّع طلباً جديداً.

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	لا	Campaign الإسناد
canvasId	string	لا	Canvas الإسناد
source	string	لا	مصدر الطلب، مثل email أو sms أو direct
utmSource	string	لا	مصدر UTM
utmMedium	string	لا	وسيط UTM
utmCampaign	string	لا	Campaign UTM

تعريف المستخدم

يلزم تقديم userId أو joryioUserId. استخدم userId مع معرّفات مستخدميك، وهو الأكثر شيوعاً. واستخدم joryioUserId عندما تملك id الداخلي لـ Joryio من استجابات Users 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 }
    ],
    "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 يمكن أن تشغّل مسارات Canvas:

الحدث	الوصف
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	خطأ داخلي في الخادم