6 نقاط نهاية
المنتجات
كتالوج بسيط بمنتجاتكم وطلباته، للبيع عبر روابط الدفع أو صفحة الدفع دون بناء متجر إلكتروني كامل.
عناوين النقاط وأوصافها تأتي من عقد OpenAPI، بالإنجليزية — فلا يمكن أن تحيد عن الواجهة.
بكلمات بسيطة
كتالوج مصغّر مستضاف: انشروا منتجًا، شاركوا صفحته، بيعوا.
متى تستعملونها
لتاجر يبيع بضعة أصناف ولا موقع تجاري له: يحمل المنتج سعره ومخزونه وصفحة بيعه.
كيف تدمجونها
- 1أنشئوا المنتج بسعره، وبكميته المتاحة عند الحاجة.
- 2شاركوا صفحة بيعه كما تشاركون رابط دفع.
- 3تابعوا طلباته للتحضير والشحن.
- 4عطّلوا المنتج بدل حذفه: يبقى سجل الطلبات مقروءًا.
- GET
/v1/productsعرض المنتجات - POST
/v1/productsإنشاء منتج - GET
/v1/products/{reference}استرجاع منتج - PATCH
/v1/products/{reference}تحديث منتج - DELETE
/v1/products/{reference}تعطيل منتج - GET
/v1/products/{reference}/ordersعرض طلبات منتج
عرض المنتجات
يُرجع منتجات المستدعي لبيئة المفتاح على شكل Page مقسّمة إلى صفحات.
| الحقل | النوع | الموضع | مطلوب | الوصف |
|---|---|---|---|---|
origin | enum | query | اختياري | التصفية حسب مصدر الإنشاء (API أو DASHBOARD).القيم APIDASHBOARD |
pageable | Pageable | query | مطلوب |
إنشاء منتج
تنشئ منتجًا في كتالوج الجهة المستدعية. أرسلوا externalId اختياريًا من إنشائكم (فريدًا لكل تاجر) لجعل عملية الإنشاء idempotent (دون تكرار): يؤدي externalId المكرّر إلى إرجاع المنتج الموجود مع 200 OK.
المخطط · CreateProductRequest
| الحقل | النوع | الموضع | مطلوب | الوصف |
|---|---|---|---|---|
name | string | body | مطلوب | اسم المنتج. |
description | string | body | اختياري | وصف مطوّل اختياري. |
imageUrl | string | body | اختياري | URL صورة المنتج، اختياري. |
price | number | body | مطلوب | سعر الوحدة بالدرهم، معبّرًا عنه بالوحدة الرئيسية. |
currency | string | body | اختياري | العملة بصيغة ISO-4217؛ القيمة الافتراضية MAD. |
stockQuantity | integer (int32) | body | اختياري | مخزون اختياري للتتبّع؛ غير محدود عند حذفه. |
expiresAt | string (date-time) | body | اختياري | طابع زمني اختياري لانتهاء البيع (ISO-8601 UTC)، ويجب أن يكون في المستقبل. |
externalId | string | body | اختياري | معرّف اختياري تقدّمونه أنتم، فريد لكل تاجر. يؤدي إنشاء منتج بـ externalId موجود مسبقًا إلى إعادة المنتج الموجود (إعادة إرسال idempotent). |
metadata | object | body | اختياري | كائن metadata حر اختياري، يُعاد كما هو عند القراءة وفي ويب هوك الدفع الخاص بطلبيات هذا المنتج. |
استرجاع منتج
يجلب منتجًا واحدًا عبر مرجعه.
| الحقل | النوع | الموضع | مطلوب | الوصف |
|---|---|---|---|---|
reference | string | path | مطلوب | مرجع المنتج. |
تحديث منتج
تحدّث منتجًا جزئيًا؛ لا تتغيّر سوى الحقول الموجودة في متن الطلب.
المخطط · UpdateProductRequest
| الحقل | النوع | الموضع | مطلوب | الوصف |
|---|---|---|---|---|
reference | string | path | مطلوب | |
name | string | body | اختياري | اسم المنتج. اختياري؛ لا يُطبَّق إلا عند وجوده. |
description | string | body | اختياري | وصف المنتج. اختياري؛ يُطبَّق فقط عند وجوده. |
imageUrl | string | body | اختياري | رابط صورة المنتج. اختياري؛ يُطبَّق فقط عند وجوده. |
price | number | body | اختياري | سعر الوحدة. اختياري؛ لا يُطبَّق إلا عند وجوده. |
active | boolean | body | اختياري | ما إذا كان المنتج نشطًا. اختياري؛ لا يُطبّق إلا عند وجوده. |
stockQuantity | integer (int32) | body | اختياري | إجمالي كمية المخزون. اختياري؛ لا يُطبّق إلا عند وجوده. |
expiresAt | string (date-time) | body | اختياري | الطابع الزمني لانتهاء صلاحية عرض المنتج. اختياري؛ لا يُطبّق إلا عند وجوده. |
clearExpiration | boolean | body | اختياري | اضبطوه على true لإزالة تاريخ الانتهاء الحالي. اختياري؛ لا يُطبَّق إلا عند وجوده. |
تعطيل منتج
يعطّل المنتج بحيث لا يمكن طلبه بعد ذلك. يُعيد المنتج المحدّث.
| الحقل | النوع | الموضع | مطلوب | الوصف |
|---|---|---|---|---|
reference | string | path | مطلوب |
عرض طلبات منتج
يُعيد الطلبات المقدَّمة لهذا المنتج على شكل Page مرقّمة الصفحات.
| الحقل | النوع | الموضع | مطلوب | الوصف |
|---|---|---|---|---|
reference | string | path | مطلوب | |
pageable | Pageable | query | مطلوب |
سؤال حول الدمج؟
يجيب فريقنا التقني فرق الإدماج، من أول استدعاء في السندبوكس حتى الانتقال إلى الإنتاج.