مرجع واجهة API

العنوان الأساسي وصيغة الاستجابة

يُقدَّم كل مسار تحت البادئة /api. محليًا، العنوان الأساسي هو http://localhost:8000/api. وعلى الخادم، هو عنوان واجهة API الخاصة بك متبوعًا بـ /api، وهي القيمة نفسها التي تقرؤها الواجهتان الأماميتان من NEXT_PUBLIC_API_BASE_URL (متغيرات البيئة).

تخدم واجهة API فئتين لا تتشاركان أي رمز أبدًا: العملاء، الذين يستخدمون مسارات المتجر، والموظفين، الذين يستخدمون مسارات لوحة الإدارة. أجسام الطلبات بصيغة JSON، باستثناء رفع الملفات. وتأتي كل إجابة في الغلاف نفسه:

{
  "success": true,
  "data": { },
  "message": ""
}

يحتوي data على النتيجة. وmessage جملة قصيرة تملؤها بعض عمليات الكتابة، مترجمة إلى لغة الطلب، وتكون فارغة في غير ذلك.

فحص السلامة هو المسار الوحيد خارج الغلاف. لا يحتاج إلى رمز:

curl http://localhost:8000/api/health

{"status":"ok"}

يُجيب بـ 503 مع {"status":"unavailable"} ما دامت قاعدة البيانات غير قابلة للوصول أو لا تحتوي على جداول، فيمكن لموازن الأحمال استخدامه كفحص للجاهزية.

الأخطاء

يُجيب الطلب الفاشل برمز حالة HTTP المطابق وبالغلاف نفسه، مع success: false وdata: null، ومع المشكلات لكل حقل عند فشل التحقق:

{
  "success": false,
  "data": null,
  "message": "<the first field's problem>",
  "errors": {
    "email": ["<the problem with email>"]
  }
}

تجيب عمليات الكتابة الناجحة بـ 201 مع POST وبـ 200 مع الطرق الأخرى.

التقسيم إلى صفحات والترتيب

تأخذ القوائم page، بدءًا من 1، وpage_count، وهو حجم الصفحة. تحتوي الصفحة على 100 صف كحد أقصى: الحجم الأكبر يُقرأ 100، والأصغر يُقرأ 1، والحجم المفقود أو غير المقروء يعود إلى القيمة الافتراضية للقائمة. وتجيب القائمة بشكل واحد:

{
  "success": true,
  "data": { "data": [ ], "page": 1, "limit": 15, "total": 35, "totalPages": 3 },
  "message": ""
}

• يحدد order=asc أو order=desc الاتجاه في المنتجات والفئات والعملاء والطلبات. الفئات تصاعدية افتراضيًا، والبقية من الأحدث إلى الأقدم.
• تُرتَّب المنتجات أيضًا بـ sort: created_at أو updated_at أو price أو rating أو best_selling. والقيمة غير المعروفة تعود إلى الافتراضي، أي الأحدث تحديثًا أولًا مع حسم التعادل بـ id. ويضع order_by_featured=true المنتجات المميزة والأكثر مبيعًا أولًا.
• تُصفّى قائمة المنتجات حسب search (الاسم بأي من اللغتين، أو SKU)، وcategory_id، وis_active، وis_featured، وis_best_seller، وmin_price، وmax_price، وtag، وon_sale.

اللغة

أرسل لغة القارئ في الترويسة Accept-Language: en أو ar كما هو مرفق. تُعامَل ar-SA كعربية، وأي لغة لا تملكها واجهة API يُجاب عنها بالإنجليزية. لا يوجد معامل استعلام للغة.

• تُترجم رسائل الخطأ وmessage الخاصة بعمليات الكتابة الناجحة.
• النص المحفوظ باللغتين، مثل أسماء المنتجات والفئات، يعود بالشكل { "en": "...", "ar": "..." } ويختار العميل إحداهما.

المصادقة

يسجّل العملاء والموظفون الدخول عبر نقاط نهاية مختلفة، مقابل جداول مختلفة، ويتلقون رموزًا لا تقبلها إلا مساراتهم الخاصة.

• كلاهما رمز JWT موقّع بـ JWT_SECRET. أرسلهما بالشكل Authorization: Bearer <token>.
• يبقى الرمز صالحًا لمدة JWT_EXPIRATION، وهي 7d افتراضيًا (متغيرات البيئة). ويُبلغ تسجيل دخول الموظفين بالقيمة نفسها في expires_in.
• لا توجد نقطة نهاية للتجديد. عندما تنتهي صلاحية الرمز، يجيب الطلب التالي بـ 401 ويسجّل العميل الدخول من جديد.
• يُرفض رمز العميل على مسارات الإدارة، ورمز الموظف على مسارات العملاء، مع أن كليهما يستخدم السر نفسه.
• يُجيب تسجيل الدخول الفاشل بـ 401 مع رسالة واحدة، سواء لم يكن للبريد حساب أو كانت كلمة المرور خاطئة.
• تقبل مسارات تسجيل الدخول والتسجيل وكلمة المرور وتتبّع الطلب 10 محاولات في الدقيقة من العنوان الواحد، تُحتسب لكل مسار. وبعد ذلك تُجيب بـ 429 مع ترويسة Retry-After. يُحفظ العدّ في ذاكرة واجهة API، فيبدأ من جديد عند إعادة التشغيل ويُحتسب منفصلًا في كل نسخة عاملة. وخلف خادم وكيل، راجع TRUST_PROXY (حل المشكلات).

1. 01

   سجّل الدخول بحساب المدير العام التجريبي

   الطرفيةنسخ

   curl -X POST http://localhost:8000/api/auth/login \
     -H "Content-Type: application/json" \
     -d '{"email":"admin@example.com","password":"Admin@123"}'

   الاستجابةنسخ

   {
     "success": true,
     "data": {
       "access_token": "eyJhbGciOiJIUzI1NiIs...",
       "token_type": "Bearer",
       "expires_in": "7d",
       "admin": {
         "id": 1,
         "email": "admin@example.com",
         "roles": [{ "id": 1, "name": "Super Admin", "guard_name": "web" }],
         "permissions": ["admins.view", "admins.create", "..."]
       }
     },
     "message": "..."
   }
2. 02

   استدعِ مسارًا محميًا بالرمز

   الطرفيةنسخ

   curl "http://localhost:8000/api/orders?page=1&page_count=5" \
     -H "Authorization: Bearer <access_token>"

   النتيجة المتوقعة: أحدث خمسة طلبات، بشكل القائمة.
3. 03

   سجّل الدخول بحساب عميل تجريبي

   يحتوي المتجر التجريبي أيضًا على عملاء، مثل john.doe@example.com بكلمة المرور password123:

   الطرفيةنسخ

   curl -X POST http://localhost:8000/api/auth/customer/login \
     -H "Content-Type: application/json" \
     -d '{"email":"john.doe@example.com","password":"password123"}'

   ثم مرّر data.token بالطريقة نفسها، مثلًا إلى GET /api/orders/my.

الصلاحيات

يتحقق كل مسار إداري من الرمز أولًا، ثم من الصلاحية التي يحددها. يملك المسؤول كل صلاحيات كل دور لديه؛ وحيث يحدد المسار عدة صلاحيات، تكفي أي واحدة منها. في جداول الإدارة أدناه، يعني اسم الصلاحية في عمود من يحق له استدعاؤه مسؤولًا تمنحه أدواره تلك الصلاحية.

تستخدم أقسام الصفحة الرئيسية واستوديو الذكاء الاصطناعي صلاحيات المنتجات. ليس للتقييمات صلاحية خاصة بها: تقرؤها لوحة الإدارة عبر المنتجات.

تشغيل البيانات التجريبية مرة أخرى ينشئ ما هو ناقص ويُبقي صلاحيات الأدوار الموجودة كما ضبطتها.

الكتالوج العام

لا حاجة إلى رمز. لا يرى المتسوّقون إلا المنتجات النشطة: من دون رمز مسؤول، المنتج غير النشط أو المحذوف غير موجود.

تسجيل العملاء وحساباتهم

تتوفر أيضًا سلة على الخادم للعملاء المسجّلين. يحفظ المتجر المرفق سلته في المتصفح ولا يستدعيها.

الطلبات وإتمام الشراء والتتبّع

مع payment_method: "stripe" وإعداد Stripe، تحمل الإجابة client_secret يؤكده المتجر مع Stripe. الشحن مجاني ابتداءً من مجموع فرعي قدره 75، و9.99 لما دون ذلك؛ والضريبة 0. يُحفظ promo_code على الطلب لكنه لا يُطبَّق.

• المدفوعات

تسجيل دخول الموظفين وحساباتهم

الأدوار

العملاء

يُشار إلى العملاء باسم المستخدم الخاص بهم. تُصفّى القائمة حسب search وemail وphone وcountry_id وusername وfirst_name وlast_name وverified وfrom_date وto_date.

المنتجات والفئات

مفاتيح الأقسام هي style-pillars وeditorial-split وnew-drops وbest-sellers وspotlight وlux-difference وeditorial-slider.

الطلبات

تقبل واجهة API أي تغيير في الحالة؛ أما لوحة الإدارة فلا تعرض إلا الخطوة التالية أو الإلغاء.

الإعدادات

لا يوجد مسار لإنشاء إعداد: البيانات التجريبية هي التي تنشئها. لا شيء في الكود المرفق يقرأ قيمها.

رفع الوسائط

• نموذج متعدد الأجزاء (multipart): الملف في file، والمجلد في path (uploads افتراضيًا)، واختياريًا إعداد مسبق للحجم في for.
• حتى 150 ميغابايت. تُحفظ مقاطع الفيديو (MP4 و WebM و MOV و M4V) كما هي وتُجيب بـ { "original": url }.
• يُعاد ترميز الصور إلى JPEG، بعرض 1920 بكسل كحد أقصى، إضافة إلى حجم الإعداد المسبق، وتُجيب بكل عنوان URL، مثل { "original": url, "250x250": url }.
• من دون متغيرات R2_* الخمسة يُجيب بـ 503: "File uploads are not set up yet."

الإشعارات

• تستخدم الإشعارات المباشرة Socket.IO على مساحة الأسماء /notifications، على عنوان واجهة API من دون /api. أرسل رمز الموظف في auth.token أثناء المصافحة؛ ورموز العملاء يُقطع اتصالها.
• يصل كل إشعار جديد كـ notification:created. الأنواع هي order_created، لكل مسؤول يستطيع عرض الطلبات، وstudio_generation_completed وstudio_generation_failed، للمسؤول الذي بدأ عملية الإنشاء.
• ترسل مساحة أسماء ثانية، /auth، الحدث permissions-updated عندما تتغير أدوار المسؤول أو صلاحياته.
• لا يقبل الاتصال إلا من FRONTEND_URL.

المساعد الذكي

استوديو الذكاء الاصطناعي

غرفة القياس

مسارات وضع العرض التجريبي