يخص: الحزمة الكاملة · واجهة API

مرجع الـ API

كل نقاط واجهة «سوق» البرمجية، مع ما تستقبله وما تعيده ومن يحق له استخدامها.

الواجهة البرمجية تحت /api، وتستقبل JSON وتعيده. يستخدمها المتجر واللوحة، ويمكنك استخدامها من تطبيق جوال أو نظام آخر.

أعراف عامة

  • المبالغ دائمًا أعداد صحيحة بأصغر وحدة للعملة: 12500 تعني 12.500 ر.ع.
  • الأخطاء تعود برمز HTTP وبالصيغة {"error": {"code": "...", "message": "..."}}. أشهر الرموز: validation (422، والرسالة تذكر كل مشكلة)، وunauthorized (401)، وforbidden (403)، وnot_found (404)، وconflict (409، رابط أو SKU أو رمز أو بريد مكرر)، وrate_limited (429).
  • الجلسات ملفات تعريف httpOnly: souq_session للوحة (12 ساعة) وsouq_customer للعملاء (30 يومًا). أعد إرسال الملف مع الطلبات اللاحقة.
  • PATCH يغيّر الحقول المرسلة فقط، وما لم تُرسله يبقى كما هو. أما PUT فيستبدل السجل كاملًا.
  • حدود الطلبات لكل عنوان IP: إتمام الطلب 20 في الدقيقة، والتسعير 120، والتحقق من الكوبون 20، والبحث عن طلب 10، وتسجيل الدخول 10 (و8 محاولات خاطئة كل 15 دقيقة لكل بريد)، وإنشاء الحساب 5، ونموذج التواصل 5 كل 10 دقائق.

المتجر (عام)

الطريقة والمسار الوظيفة
GET /api/store اسم المتجر والعملة والضريبة وطرق الدفع المتاحة وطرق التوصيل والمحافظات
GET /api/categories الأقسام الظاهرة مع عدد منتجاتها
GET /api/collections التشكيلات الظاهرة مع عدد منتجاتها
GET /api/products قائمة المنتجات. المعاملات: category وcollection وq وcat وnew وsale وfeatured وsize وcolor وmin وmax وstock وsort وpage وperPage (حتى 60). تعيد {products, page, pages, total, facets}
GET /api/products/{slug} منتج واحد بكل خياراته (id وsku وsize واللون وprice وstock) مع منتجات مشابهة

الحقيبة والطلبات (عام)

POST /api/cart/quote يسعّر الحقيبة دون حفظ أي شيء:

{ "items": [{ "variantId": "...", "quantity": 2 }], "couponCode": "WELCOME10", "governorate": "muscat", "shippingMethod": "muscat-standard" }

يعيد: lines (لكل سطر unitPrice وlineTotal وstock، وissue إن تعذّر شراؤه)، وcoupon (ok مع discount أو reason)، وshipping.options للمحافظة، وsubtotal وdiscount وshippingFee وtax وtotal، وok.

POST /api/coupons/validate يستقبل {code, items} ويعيد {valid, discount} أو {valid: false, reason, message}.

POST /api/orders يسجّل طلبًا:

{
  "items": [{ "variantId": "...", "quantity": 1 }],
  "couponCode": "",
  "customerName": "عائشة البلوشية", "phone": "+968 9123 4567", "email": "",
  "governorate": "muscat", "city": "الخوير", "addressLine": "سكة 2601، مبنى 12", "notes": "",
  "shippingMethod": "muscat-standard", "paymentMethod": "COD", "locale": "ar"
}

يعيد 201 {code, total}، ومعه payUrl إذا كان "paymentMethod": "CARD" (وجّه العميل إليه). الأخطاء: out_of_stock (409)، وcoupon_invalid وshipping_unavailable وpayment_disabled وinvalid_phone (422)، وnot_accepting (409)، وpayment_unavailable (502). وإن كان العميل مسجّل الدخول يُربط الطلب بحسابه.

الطريقة والمسار الوظيفة
GET /api/orders/{code} حالة الطلب للعميل: القطع والإجماليات والسجل، مع إخفاء جزء من الهاتف
POST /api/orders/lookup {code, phone}: النتيجة نفسها، بشرط تطابق الهاتف مع الطلب
GET /api/payments/thawani/return?order=CODE حيث تعيد «ثواني» العميل؛ يتحقق من الدفع لدى «ثواني» ثم يحوّل إلى صفحة الطلب
POST /api/contact {name, email, phone?, subject?, message}: يحفظ رسالة للوحة

حسابات العملاء

الطريقة والمسار الوظيفة
POST /api/account/register {name, email, password (8 أحرف فأكثر), phone?}: ينشئ الحساب ويسجّل الدخول، وemail_taken (409) إن وُجد
POST /api/account/login {email, password}
POST /api/account/logout تسجيل الخروج
GET /api/account/me {customer, orders, wishlist} (401 لغير المسجّل)
PATCH /api/account/me {name?, phone?}
GET /api/account/wishlist {customer, productIds}، وcustomer قيمته null لغير المسجّل
POST /api/account/wishlist {productId} إضافة
DELETE /api/account/wishlist {productId} إزالة

اللوحة

تحتاج كل نقاط اللوحة إلى ملف souq_session. والصلاحية بين القوسين يجب أن تكون مسموحة لدور الحساب (أدوار المشرفين)، والمالك مسموح له دائمًا.

الطريقة والمسار الصلاحية الوظيفة
POST /api/auth/login {email, password}: الدخول، ويعيد {user: {name, email, role}}
POST /api/auth/logout الخروج
GET /api/auth/me مسجّل الدخول الحساب الحالي
GET /api/dashboard/stats مسجّل الدخول كل بيانات النظرة العامة
GET /api/dashboard/orders orders المعاملات: status (حالة أو OPEN) وq وpage وperPage
GET /api/dashboard/orders/{id} orders الطلب كاملًا مع سجله وnext (الحالات المسموح الانتقال إليها)
PATCH /api/dashboard/orders/{id} orders {status, note?} ينقل الطلب، وbad_transition (409) إن لم يكن مسموحًا
GET, POST /api/dashboard/products products القائمة (?q=&categoryId=) والإنشاء مع الخيارات
GET, PUT, PATCH, DELETE /api/dashboard/products/{id} products PUT يستبدل المنتج وقائمة خياراته (الخيار الذي له id يُحدَّث، والجديد يُنشأ، والغائب يُحذف). PATCH يقبل active وfeatured وprice وcompareAt وsort وcategoryId وstock: [{id, stock}]
POST /api/dashboard/uploads products multipart/form-data بالحقل file: صورة حتى 5 ميغابايت، ويعيد {url}
GET, POST /api/dashboard/categories catalog
PUT, PATCH, DELETE /api/dashboard/categories/{id} catalog لا يُحذف إلا إذا لم يستخدمه أي منتج
GET, POST /api/dashboard/collections catalog
PUT, PATCH, DELETE /api/dashboard/collections/{id} catalog
GET, POST /api/dashboard/coupons coupons {code, type, value, minOrder?, expiresAt?, usageLimit?, active?}، وtype إما PERCENT أو FIXED
PUT, PATCH, DELETE /api/dashboard/coupons/{id} coupons يبقى عدّاد الاستخدام كما هو
GET /api/dashboard/customers customers ?q=؛ الحسابات والضيوف مجمّعين حسب الهاتف
GET /api/dashboard/messages customers ?open=1 لغير المعالَجة فقط
PATCH, DELETE /api/dashboard/messages/{id} customers {handled}
GET, POST /api/dashboard/ai/chat ai GET يعيد {configured, insights}؛ وPOST يستقبل {messages: [{role, content}], locale} ويعيد {reply} (501 دون ذكاء اصطناعي)
GET, POST /api/dashboard/ai/describe ai POST يستقبل {nameAr, nameEn, category?, notes?, tone?} ويعيد {ar, en}
GET /api/dashboard/settings مسجّل الدخول الإعدادات، وهل مفاتيح «ثواني» موجودة
PUT, PATCH /api/dashboard/settings settings
GET, POST /api/dashboard/admins admins {name, email, password (10 أحرف فأكثر), role}؛ ولا ينشئ مالكًا إلا مالك
PATCH, DELETE /api/dashboard/admins/{id} admins {name?, role?, active?, password?}
GET /api/dashboard/roles مسجّل الدخول {permissions, matrix, mine}
PUT /api/dashboard/roles المالك فقط {ADMIN: [...], STAFF: [...]}

مثال

# سجّل الدخول واحتفظ بملف الجلسة
curl -c jar.txt -H "Content-Type: application/json" \
  -d '{"email":"owner@souq.test","password":"souq-demo-2026"}' http://localhost:3302/api/auth/login

# أخفِ منتجًا دون المساس بأي شيء آخر
curl -b jar.txt -X PATCH -H "Content-Type: application/json" \
  -d '{"active":false}' http://localhost:3302/api/dashboard/products/PRODUCT_ID

يمرّ scripts/e2e_api.py على أغلب هذه النقاط، وهو مكان جيد لرؤية طلبات وإجابات حقيقية.