API المنتجات الخارجية
هيّئ كتالوجاً خارجياً وزامنه بأمثلة طلبات مطابقة للمصدر.
المصادقة والعنوان
استخدم أصل API لبيئتك مع /api/v1. تستخدم المسارات الخارجية مصادقة التكامل لا JWT لوحة التحكم. هيّئ تكامل PRODUCT_SYNC أو CUSTOM_API نشطاً للنشاط واستخدم طريقته المحددة. في وضع المفتاح أرسل x-api-key وفي وضع HMAC اتبع التوقيع.
| الطريقة | المسار النسبي تحت /api/v1 | العملية |
|---|---|---|
| POST | /businesses/:businessId/integrations/products/bootstrap | تهيئة أو تحديث |
| POST | /businesses/:businessId/integrations/products/sync | تحديث مستمر |
طلب التهيئة
يلزم external_id وname للمنتج ومصفوفة variants غير فارغة وSKU للمتغير. سعر المتغير رقم. حدد العملة ومعرّفات المتغيرات الثابتة.
{
"products": [{
"external_id": "catalog-100",
"name": "Reusable bottle",
"nameAr": "زجاجة قابلة لإعادة الاستخدام",
"isAIVisible": true,
"variants": [{
"external_id": "catalog-100-blue",
"sku": "BOTTLE-BLUE",
"price": 49,
"currency": "SAR",
"availability": true,
"stock_quantity": 12
}]
}]
}
تحدّث التهيئة المنتج بمعرّفه الخارجي داخل النشاط أو تنشئه. عند غياب معرّف المتغير يُستخدم SKU؛ أدخله صراحة عندما يملكه المصدر. تتضمن الاستجابة success وimported وupdated وfailed. لكل فشل external_id وreason. افحص failed حتى عند نجاح HTTP لأن المعالجة لكل سجل مستقلة.
تحديث متغير
{
"event": "variant.updated",
"variant": {
"external_id": "catalog-100-blue",
"price": 45,
"currency": "SAR",
"availability": true,
"stock_quantity": 8
}
}
استخدم product.updated مع product.external_id لحقول المنتج. تعالج الخدمة أيضاً product.deleted لتعطيل المنتج وvariant.deleted وproduct.hard_deleted. أحداث الحذف مؤثرة؛ اختبر بسجل قابل للاستغناء وأكد المعنى قبل ربط حذف المصدر. تتضمن استجابة المزامنة success وevent وmessage وupdatedAt عند إعادته.
معالجة الفشل
تُرفض المعرّفات الناقصة والأحداث غير المدعومة ويُعاد خطأ عدم وجود للسجلات المجهولة. افحص الفشل الجزئي والسجل الحالي قبل الإعادة. لا يوجد ترقيم لهذه الطلبات؛ لا تخمّن مسار قوائم. التحقق من المصدر لا يغني عن الاختبار على الخادم المنشور.