واجهة الإدارة — الواجهة البرمجية

الحالة: قيد التطوير. هذه هي الواجهات التي تعمل عليها لوحة تحكم matgrk نفسها اليوم. الوصول العام عبر الواجهة — ببيانات اعتماد وصلاحيات خاصة — مخطط له؛ وحتى يصدر، تصف الأشكال في هذه الصفحة الخدمات كما تعمل وقد تتغير.

كل مورد يخص متجرًا واحدًا؛ لا شيء هنا يقرأ أو يكتب عبر المتاجر.
الكتابة مضبوطة بصلاحية لكل مورد — الصلاحيات نفسها التي تُبنى منها أدوار لوحة التحكم. الشارة على السطر تسمّي الصلاحية التي يتحقق منها المسار؛ والسطر بلا شارة إمّا بين الخدمات فقط وإمّا لم يُثبَّت هنا بعد.
كل خدمة تعلن صلاحياتها وتجمعها المنصة في أدوار تسقفها خطة المتجر — الاسم غير المعلَن مرفوض لا مقبول.
تغييرات الكتالوج تصل واجهة المتجر عبر النشر: تعديل المنتج لا يظهر حتى يُنشَر.
السطور ذات السهم تتوسع إلى نموذج طلب أو استجابة.

المنتجات

GET/productsقائمة المنتجاتcatalog.products.view

POST/productsإنشاء منتجcatalog.products.create

الطلب

{
  "sku": "TSHIRT-001",
  "base_price_minor": 11500,
  "currency": "SAR",
  "tax_class": "standard",
  "compare_at_minor": null,
  "weight_grams": 250,
  "brand_id": null,
  "status": "draft",
  "enabled_locales": ["ar", "en"],
  "translations": { "ar": { … }, "en": { … } },
  "on_hand": 100
}

GET/products/{id}منتج واحد بتشكيلاته وخياراته وسماته ووسائطهcatalog.products.view
PATCH/products/{id}تعديل منتج — أرسل ما تغيّر فقطcatalog.products.update
DELETE/products/{id}حذف منتج؛ الطلبات القائمة تحتفظ بهcatalog.products.delete
POST/products/{id}/publishنشر؛ يرفض ويسمّي اللغات الناقصةcatalog.products.publish
POST/products/{id}/unpublishإخفاؤه من واجهة المتجرcatalog.products.publish
GET/products/by-sku/{sku}إيجاد منتج برمز SKUcatalog.products.view
POST/products/{id}/optionsإضافة خيارcatalog.products.update
PATCH/options/{id}تعديل خيارcatalog.products.update
DELETE/options/{id}حذف خيارcatalog.products.update
POST/products/{id}/variantsتوليد التشكيلات من الخياراتcatalog.products.update

PATCH/variants/{id}تعديل تشكيلةcatalog.products.update

الطلب

{
  "sku": "TSHIRT-001-L",
  "price_minor": 12500,
  "compare_at_minor": null,
  "weight_grams": 260,
  "primary_media_id": null,
  "on_hand": 40
}

الاستجابة

{
  "variant": { … },
  "effective_price_minor": 12500
}

التصنيفات والعلامات والسمات

GET/categoriesقائمة التصنيفاتcatalog.categories.manage
POST/categoriesإنشاء تصنيفcatalog.categories.manage
PATCH/categories/{id}تعديل تصنيفcatalog.categories.manage
DELETE/categories/{id}حذف تصنيفcatalog.categories.manage
GET/brandsقائمة العلاماتcatalog.brands.manage
POST/brandsإنشاء علامةcatalog.brands.manage
PATCH/brands/{id}تعديل علامةcatalog.brands.manage
DELETE/brands/{id}حذف علامةcatalog.brands.manage
GET/attributesقائمة السماتcatalog.attributes.manage
POST/attributesإنشاء سمةcatalog.attributes.manage
PATCH/attributes/{id}تعديل سمةcatalog.attributes.manage
DELETE/attributes/{id}حذف سمةcatalog.attributes.manage

المخزون والوسائط

GET/stockأرصدة المخزونcatalog.products.view
POST/stock/availabilityتوافر مجموعة تشكيلاتcatalog.products.view
GET/mediaوسائط منتج
POST/media/attachإرفاق صورcatalog.media.manage
POST/media/reorderإعادة ترتيب الصورcatalog.media.manage
POST/media/detachفصل صورcatalog.media.manage

استيراد الكتالوج وتصديره

POST/imports/previewمعاينة استيراد للكتالوج — لا تكتب شيئًاcatalog.import.run
POST/imports/{id}/applyتطبيق الاستيراد المُعايَنcatalog.import.run
GET/imports/{id}حالة الاستيرادcatalog.import.run
GET/imports/{id}/failuresالصفوف التي فشلتcatalog.import.run
GET/exportsقائمة التصديراتcatalog.export.run

الطلبات والفواتير

GET/ordersقائمة طلبات المتجرcommerce.orders.view
GET/orders/{id}طلب واحدcommerce.orders.view
POST/orders/{id}/transitionsنقل الطلب عبر حالاته — الانتقالات المعلَنة فقطcommerce.orders.transition
الطلب
```
{
  "dimension": "fulfilment",
  "to_state": "shipped",
  "cause": "Shipped with SMSA, AWB 12345"
}
```
الاستجابة
```
{
  "data": { … }
}
```
GET/invoicesقائمة الفواتيرcommerce.orders.view
GET/invoices/{id}فاتورة واحدةcommerce.orders.view
POST/invoices/{id}/resubmitإعادة تقديم فاتورة إلكترونية

العروض والحملات الترويجية

GET/offersشارات العروض لمجموعة تشكيلات
GET/promotionsقائمة الحملات مع حدّ الخطةcommerce.promotions.manage

POST/promotionsإنشاء حملةcommerce.promotions.manage

الطلب

{
  "name_ar": "خصم الافتتاح",
  "name_en": "Opening discount",
  "scope": "lines",
  "targets": [{ "kind": "category", "ref": "01J8…" }],
  "type": "percentage",
  "percent_bps": 1500,
  "application": "coupon",
  "code": "WELCOME15",
  "starts_at": "2026-10-01",
  "ends_at": "2026-10-15",
  "minimum_cart_minor": 10000,
  "usage_limit_total": 1000,
  "usage_limit_per_shopper": 1,
  "position": 1,
  "stackable": false,
  "is_active": true
}

الاستجابة

{
  "data": { …the promotion, with its coupons and targets… }
}

PATCH/promotions/{id}تعديل حملةcommerce.promotions.manage
DELETE/promotions/{id}حذف حملة — المستعملة تُعطَّل بدلًا من الحذفcommerce.promotions.manage
POST/promotions/importsاستيراد الحملات دفعة واحدة

بيانات اعتماد API

GET/api-credentialsقائمة مفاتيح API للمتجرcommerce.api_keys.manage

POST/api-credentialsإصدار مفتاح — يظهر مرة واحدةcommerce.api_keys.manage

الطلب

{
  "name": "Mobile app",
  "rate_limit_per_minute": 300
}

الاستجابة

{
  "data": { …the credential… },
  "key": "mk_live_…",
  "key_shown_once": true
}

DELETE/api-credentials/{id}إلغاء مفتاح — تنتهي جلساته عند أول تحديث تالٍcommerce.api_keys.manage