الواجهة البرمجية تحت /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 على أغلب هذه النقاط، وهو مكان جيد لرؤية طلبات وإجابات حقيقية.