مرجع واجهة API

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

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

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

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

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

{"success":true,"data":{"status":"ok","database":"up"},"message":""}

إلى أن تجيب قاعدة البيانات وتحتوي جداولها، يجيب بـ 503 مع "status":"unavailable" و"database":"down". ويقرؤه فحص الصحة في صورة Docker.

الأخطاء

يحتفظ الفشل بالغلاف، مع success: false وحالة HTTP:

{
  "success": false,
  "data": null,
  "message": "That email and password combination didn't work. Please try again.",
  "errors": { "email": ["Enter a valid email address (example@domain.com)."] }
}

• message جملة بلغة الطلب.
• يُملأ errors عند فشل التحقق، بالمشكلات لكل حقل. ويُرفض أي حقل في الجسم لا يعرفه المسار.
• المسار المحمي من دون رمز، أو برمز منتهي، يجيب بـ 401؛ والرمز الذي ينقصه الصلاحية يجيب بـ 403.

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

تقبل مسارات القوائم page وpage_count (أو limit). وpage_count محدود بـ 100؛ والقيمة المفقودة أو غير الصالحة تعود إلى افتراضي المسار، 15 للمستخدمين و10 لغيرهم.

{ "data": [ ], "page": 1, "limit": 15, "total": 15, "totalPages": 1 }

المستخدمون بالأحدث أولًا افتراضيًا (order=asc يعكس الترتيب)؛ والمشاريع بالأحدث تحديثًا أولًا؛ والمشرفون بالأحدث أولًا؛ والإعدادات حسب الفئة؛ والأدوار حسب الاسم.

اللغة

أرسل Accept-Language: ar لتصلك الرسائل بالعربية؛ وأي قيمة أخرى تُجاب بالإنجليزية. وتحمل الدول والصلاحيات والإعدادات وأسماء المشاريع اللغتين على شكل { "en": "…", "ar": "…" } مهما كانت الترويسة، ويختار العميل إحداهما.

تسجيل الدخول

1. 01

   احصل على رمز

   أرسل بريد مشرف وكلمة مروره. تقبل واجهة API التي مُلئت بالـ seed حساب Super Admin المذكور في دليل التثبيت.

   الطرفيةنسخ

   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": "eyJ…",
       "token_type": "Bearer",
       "expires_in": "7d",
       "admin": { "id": 1, "email": "admin@example.com", "username": "…", "roles": [ ], "permissions": [ ] }
     },
     "message": "Signed in successfully."
   }
2. 02

   أرسله مع كل استدعاء

   الطرفيةنسخ

   curl http://localhost:8000/api/auth/me -H "Authorization: Bearer eyJ…"

   النتيجة المتوقعة: يعيد /api/auth/me المشرف المسجّل دخوله مع أدواره وصلاحياته.

• يبقى الرمز صالحًا مدة JWT_EXPIRATION، وهي 7d افتراضيًا. لا يوجد مسار تجديد: سجّل الدخول مرة أخرى.
• البريد الخاطئ وكلمة المرور الخاطئة يحصلان على رسالة 401 نفسها.
• بعد RATE_LIMIT_LOGIN محاولة تسجيل دخول فاشلة (10 افتراضيًا) من عنوان واحد خلال 15 دقيقة، يجيب POST /api/auth/login بـ 429 إلى أن يبلغ عمر أقدم فشل 15 دقيقة. والعدّاد محفوظ في الذاكرة، فإعادة التشغيل تمسحه.

الصلاحيات

كل مسار أدناه يحتاج إلى Authorization: Bearer مع رمز، عدا المسارات الموسومة بـ «أي شخص». ومعظمها يحتاج أيضًا إلى صلاحية، اسمها module.action؛ ويملك المشرف صلاحيات كل أدواره. والصلاحيات الـ 25 مدرجة في «الشاشات والأدوار والصلاحيات».

• الأدوار والصلاحيات

المستخدمين

الأشخاص الذين يخدمهم منتجك، يُخاطَبون بـ username. الحذف حذف ناعم.

المشاريع

تحمل المشاريع name وdescription وenvironment وstatus (in-progress أو ready أو blocked) وversion، واختياريًا image وicon_name، وtranslations مع اسم ووصف بـ en وar.

المهام السريعة

قائمة مهام النظرة العامة. لكل مشرف قائمته الخاصة، ولا يحتاج إلى صلاحية: فكل مسار يقرأ مهام المستدعي وحده ويكتبها. المهمة هي text وcompleted.

المشرفون وملفك الشخصي

الحسابات التي تسجّل الدخول إلى لوحة التحكم. يقبل :id معرّفًا أو اسم مستخدم.

الأدوار

إعدادات التطبيق

أزواج مفتاح وقيمة لها اسم عرض ووصف ونوع وفئة، مثل site_name وsupport_email وmaintenance_mode.

الدول والرفع

يقبل الرفع صورة واحدة بحجم 10 MB على الأكثر، ويخزنها في حاوية R2 الخاصة بك بصيغة JPEG بعرض 1920 بكسل على الأكثر، مع نسخة بحجم مختلف لقيمة for، ويعيد عنوانيهما: original وعنوانًا مثل 250x250. ومن دون متغيرات R2 يجيب بـ 503 مع «لم يتم إعداد رفع الصور على هذا الخادم بعد. أضف إعدادات Cloudflare R2 إلى بيئة الواجهة البرمجية لتفعيله.»

المساعد الذكي ومحادثاته

خادم MCP

التحديث الفوري للصلاحيات

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