عقود API

يولد FORGE واجهة RESTful API تتبع عقوداً صارمة لصيغة الطلب/الاستجابة، والمصادقة، ومعالجة الأخطاء، والتصفح. هذه الصفحة هي المرجع الكامل لكل نقطة نهاية في التطبيق المولّد.

الرابط الأساسي

جميع نقاط نهاية API تُقدم تحت مسار أساسي بإصدار:

https://api.{app-name}.test/api/v1

المصادقة

نقاط النهاية المحمية تتطلب رمز JWT صالح في ترويسة Authorization:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

TIP

للتطبيقات المعتمدة على المتصفح، يدعم FORGE أيضاً تسليم الكوكيز HttpOnly. يُرسل الرمز تلقائياً مع كل طلب عند استخدام الكوكيز -- لا حاجة لترويسة Authorization.

صيغة الاستجابة

كل استجابة API تتبع هيكل غلاف متسق.

استجابة ناجحة

json

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "أحمد محمد",
    "email": "ahmed@example.com"
  }
}

استجابة مع تصفح

json

{
  "success": true,
  "data": [
    { "id": "...", "name": "..." },
    { "id": "...", "name": "..." }
  ],
  "meta": {
    "page": 1,
    "per_page": 15,
    "total": 42,
    "last_page": 3
  }
}

استجابة خطأ

json

{
  "success": false,
  "message": "فشل التحقق",
  "errors": {
    "email": ["حقل البريد الإلكتروني مطلوب"],
    "password": ["يجب أن يكون 8 أحرف على الأقل"]
  }
}

رموز حالة HTTP

الرمز	المعنى	متى
`200`	نجاح	GET, PUT ناجح
`201`	تم الإنشاء	POST ناجح (تم إنشاء مورد)
`204`	بدون محتوى	DELETE ناجح
`401`	غير مصرح	رمز مفقود أو غير صالح
`403`	ممنوع	رمز صالح لكن صلاحيات غير كافية
`404`	غير موجود	المورد غير موجود
`422`	كيان غير قابل للمعالجة	أخطاء التحقق
`429`	طلبات كثيرة جداً	تم تجاوز حد المعدل
`500`	خطأ خادم داخلي	خطأ خادم غير متوقع

التصفح

جميع نقاط نهاية القوائم تقبل معلمات استعلام التصفح:

GET /api/v1/admin/users?page=2&per_page=25

المعلمة	النوع	الافتراضي	الوصف
`page`	integer	`1`	رقم الصفحة
`per_page`	integer	`15`	العناصر لكل صفحة (الحد الأقصى 100)
`search`	string	--	مصطلح البحث (حيث مدعوم)
`sort`	string	`created_at`	حقل الفرز
`order`	string	`desc`	اتجاه الفرز (`asc` أو `desc`)

نقاط نهاية المصادقة

نقاط نهاية المصادقة عامة (لا تتطلب رمز) ما لم يُذكر خلاف ذلك.

مصادقة المستخدم واستلام رموز JWT.

الطلباستجابة 200خطأ 401

bash

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "securepassword"
}

json

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 900,
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "أحمد محمد",
      "email": "user@example.com",
      "avatar": null,
      "roles": ["user"],
      "permissions": []
    }
  }
}

json

{
  "success": false,
  "message": "بيانات الاعتماد غير صحيحة"
}

POST /auth/register

إنشاء حساب مستخدم جديد.

الطلباستجابة 201

bash

POST /api/v1/auth/register
Content-Type: application/json

{
  "name": "سارة أحمد",
  "email": "sara@example.com",
  "password": "securepassword",
  "password_confirmation": "securepassword"
}

json

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 900,
    "user": {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "سارة أحمد",
      "email": "sara@example.com",
      "roles": ["user"],
      "permissions": []
    }
  }
}

POST /auth/refresh

استبدال رمز تجديد صالح بزوج رموز جديد.

الطلباستجابة 200

bash

POST /api/v1/auth/refresh
Content-Type: application/json

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

json

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 900
  }
}

WARNING

رموز التجديد للاستخدام مرة واحدة. كل استدعاء يبطل الرمز السابق ويصدر زوجاً جديداً. إذا أُعيد استخدام رمز تجديد، تُلغى جميع الرموز لذلك المستخدم كإجراء أمني (تدوير رمز التجديد).

POST /auth/logout

إبطال الجلسة الحالية. يتطلب المصادقة.

bash

POST /api/v1/auth/logout
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

استجابة (200):

json

{
  "success": true,
  "message": "تم تسجيل الخروج بنجاح"
}

POST /auth/password/forgot

إرسال رابط إعادة تعيين كلمة المرور إلى بريد المستخدم.

bash

POST /api/v1/auth/password/forgot
Content-Type: application/json

{
  "email": "user@example.com"
}

استجابة (200):

json

{
  "success": true,
  "message": "تم إرسال رابط إعادة تعيين كلمة المرور"
}

POST /auth/password/reset

إعادة تعيين كلمة المرور باستخدام رمز من البريد.

bash

POST /api/v1/auth/password/reset
Content-Type: application/json

{
  "token": "reset-token-from-email",
  "password": "newsecurepassword",
  "password_confirmation": "newsecurepassword"
}

POST /auth/otp/send

طلب كلمة مرور لمرة واحدة للمصادقة عبر الهاتف.

bash

POST /api/v1/auth/otp/send
Content-Type: application/json

{
  "mobile": "+966500000000"
}

استجابة (200):

json

{
  "success": true,
  "message": "تم إرسال OTP بنجاح"
}

POST /auth/otp/verify

التحقق من OTP ومصادقة المستخدم.

الطلباستجابة 200

bash

POST /api/v1/auth/otp/verify
Content-Type: application/json

{
  "mobile": "+966500000000",
  "otp": "123456"
}

json

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 900,
    "user": {
      "id": "...",
      "name": "...",
      "mobile": "+966500000000"
    }
  }
}

نقاط نهاية الملف الشخصي

جميع نقاط نهاية الملف الشخصي تتطلب المصادقة.

GET /profile

استرجاع الملف الشخصي للمستخدم المصادق.

bash

GET /api/v1/profile
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

استجابة (200):

json

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "أحمد محمد",
    "email": "ahmed@example.com",
    "mobile": null,
    "avatar": "/media/avatars/ahmed.jpg",
    "roles": ["user"],
    "permissions": [],
    "email_verified_at": "2026-01-15T10:30:00Z",
    "created_at": "2026-01-01T00:00:00Z"
  }
}

PUT /profile

تحديث معلومات الملف الشخصي للمستخدم المصادق.

bash

PUT /api/v1/profile
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

{
  "name": "أحمد علي",
  "email": "ahmed.ali@example.com"
}

POST /profile/avatar

رفع أو استبدال صورة المستخدم الرمزية.

bash

POST /api/v1/profile/avatar
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: multipart/form-data

avatar: (binary file)

PUT /profile/password

تغيير كلمة مرور المستخدم المصادق.

bash

PUT /api/v1/profile/password
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

{
  "current_password": "oldsecurepassword",
  "password": "newsecurepassword",
  "password_confirmation": "newsecurepassword"
}

نقاط نهاية الإدارة

جميع نقاط نهاية الإدارة تتطلب المصادقة و الصلاحية المناسبة. الطلبات بدون الصلاحية المطلوبة تتلقى استجابة 403 Forbidden.

المستخدمون

الطريقة	النقطة	الصلاحية	الوصف
`GET`	`/admin/users`	`users.view`	قائمة جميع المستخدمين (مع تصفح)
`POST`	`/admin/users`	`users.create`	إنشاء مستخدم جديد
`GET`	`/admin/users/:id`	`users.view`	الحصول على مستخدم واحد
`PUT`	`/admin/users/:id`	`users.edit`	تحديث مستخدم
`DELETE`	`/admin/users/:id`	`users.delete`	حذف ناعم لمستخدم

قائمة المستخدمينإنشاء مستخدمتحديث مستخدم

bash

GET /api/v1/admin/users?page=1&per_page=15&search=ahmed
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

bash

POST /api/v1/admin/users
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

{
  "name": "مستخدم جديد",
  "email": "new@example.com",
  "password": "securepassword",
  "is_active": true,
  "roles": ["user"]
}

bash

PUT /api/v1/admin/users/550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

{
  "name": "اسم محدث",
  "is_active": false
}

الأدوار

الطريقة	النقطة	الصلاحية	الوصف
`GET`	`/admin/roles`	`roles.view`	قائمة جميع الأدوار (مع تصفح)
`POST`	`/admin/roles`	`roles.create`	إنشاء دور جديد
`GET`	`/admin/roles/:id`	`roles.view`	الحصول على دور واحد مع الصلاحيات
`PUT`	`/admin/roles/:id`	`roles.edit`	تحديث الدور والصلاحيات
`DELETE`	`/admin/roles/:id`	`roles.delete`	حذف دور

DANGER

أدوار النظام (admin، user) لا يمكن حذفها. محاولة حذف دور نظام تُرجع 403 Forbidden.

الصلاحيات

الطريقة	النقطة	الصلاحية	الوصف
`GET`	`/admin/permissions`	`permissions.view`	قائمة جميع الصلاحيات (مجمعة)

الصلاحيات للقراءة فقط. يتم إنشاؤها بواسطة البيانات الأولية وملفات manifest القوالب، وليس من قبل مستخدمي الإدارة.

المحتويات

الطريقة	النقطة	الصلاحية	الوصف
`GET`	`/admin/contents`	`contents.view`	قائمة صفحات المحتوى (مع تصفح)
`POST`	`/admin/contents`	`contents.create`	إنشاء صفحة محتوى
`GET`	`/admin/contents/:id`	`contents.view`	الحصول على صفحة محتوى واحدة
`PUT`	`/admin/contents/:id`	`contents.edit`	تحديث صفحة محتوى
`DELETE`	`/admin/contents/:id`	`contents.delete`	حذف ناعم لصفحة محتوى

إنشاء محتوىاستجابة 201

bash

POST /api/v1/admin/contents
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: multipart/form-data

title: About Us
slug: about-us
summary: Learn more about our company
details: <p>Full HTML content here...</p>
seo: {"title":"About Us","description":"Company info"}
translations: {"ar":{"title":"من نحن","summary":"تعرف على شركتنا"}}
is_active: true
publish_at: 2026-02-01T00:00:00Z
featured_image: (binary file, optional)

json

{
  "success": true,
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "title": "About Us",
    "slug": "about-us",
    "summary": "Learn more about our company",
    "details": "<p>Full HTML content here...</p>",
    "seo": { "title": "About Us", "description": "Company info" },
    "translations": { "ar": { "title": "من نحن" } },
    "is_active": true,
    "publish_at": "2026-02-01T00:00:00Z",
    "featured_image": {
      "id": "...",
      "url": "/media/contents/about-hero.jpg"
    },
    "created_at": "2026-01-27T12:00:00Z"
  }
}

القوائم

الطريقة	النقطة	الصلاحية	الوصف
`GET`	`/admin/menus`	`menus.view`	قائمة جميع عناصر القائمة (مع تصفح)
`POST`	`/admin/menus`	`menus.create`	إنشاء عنصر قائمة
`GET`	`/admin/menus/:id`	`menus.view`	الحصول على عنصر قائمة واحد
`PUT`	`/admin/menus/:id`	`menus.edit`	تحديث عنصر قائمة
`DELETE`	`/admin/menus/:id`	`menus.delete`	حذف ناعم لعنصر قائمة

bash

POST /api/v1/admin/menus
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

{
  "title": "Home",
  "url": "/",
  "icon": "home",
  "target": "_self",
  "visibility": "public",
  "parent_id": null,
  "sort_order": 1,
  "is_active": true,
  "translations": {
    "ar": { "title": "الرئيسية" }
  }
}

جداول البحث

الطريقة	النقطة	الصلاحية	الوصف
`GET`	`/admin/lookups`	`lookups.view`	قائمة البحث (قابلة للتصفية حسب النوع)
`POST`	`/admin/lookups`	`lookups.create`	إنشاء إدخال بحث
`GET`	`/admin/lookups/:id`	`lookups.view`	الحصول على بحث واحد
`PUT`	`/admin/lookups/:id`	`lookups.edit`	تحديث بحث
`DELETE`	`/admin/lookups/:id`	`lookups.delete`	حذف بحث

bash

GET /api/v1/admin/lookups?type=country&page=1

الإعدادات

الطريقة	النقطة	الصلاحية	الوصف
`GET`	`/admin/settings`	`settings.view`	الحصول على جميع الإعدادات (مجمعة)
`PUT`	`/admin/settings`	`settings.edit`	تحديث الإعدادات (دفعة)

bash

PUT /api/v1/admin/settings
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

{
  "general.app_name": "تطبيقي",
  "general.timezone": "Asia/Riyadh",
  "auth.allow_registration": "true"
}

اللغات

الطريقة	النقطة	الصلاحية	الوصف
`GET`	`/admin/languages`	`settings.view`	قائمة جميع اللغات
`POST`	`/admin/languages`	`settings.edit`	إضافة لغة
`PUT`	`/admin/languages/:id`	`settings.edit`	تحديث لغة
`DELETE`	`/admin/languages/:id`	`settings.edit`	إزالة لغة

الترجمات

الطريقة	النقطة	الصلاحية	الوصف
`GET`	`/admin/translations`	`translations.view`	قائمة الترجمات (حسب المجموعة)
`PUT`	`/admin/translations`	`translations.edit`	تحديث الترجمات (دفعة)

bash

GET /api/v1/admin/translations?group=auth

مفاتيح API

الطريقة	النقطة	الصلاحية	الوصف
`GET`	`/admin/api-keys`	`api_keys.view`	قائمة مفاتيح API
`POST`	`/admin/api-keys`	`api_keys.create`	إنشاء مفتاح API
`DELETE`	`/admin/api-keys/:id`	`api_keys.revoke`	إلغاء مفتاح API

WARNING

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

سجلات التدقيق

الطريقة	النقطة	الصلاحية	الوصف
`GET`	`/admin/audit-logs`	`audit.view`	قائمة سجلات التدقيق (مع تصفح، قابلة للتصفية)

bash

GET /api/v1/admin/audit-logs?resource_type=user&action=updated&page=1

النقاط العامة

النقاط العامة لا تتطلب مصادقة.

GET /contents/:slug

استرجاع صفحة محتوى منشورة بمعرفها slug. يقبل معلمة استعلام locale اختيارية للمحتوى المترجم.

bash

GET /api/v1/contents/about-us?locale=ar

استجابة (200):

json

{
  "success": true,
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "title": "من نحن",
    "slug": "about-us",
    "summary": "تعرف على شركتنا",
    "details": "<p>محتوى الصفحة...</p>",
    "seo": { "title": "من نحن", "description": "..." },
    "featured_image": {
      "url": "/media/contents/about-hero.jpg"
    }
  }
}

TIP

عند توفير معلمة locale، تدمج API ترجمات اللغة المطلوبة فوق حقول اللغة الافتراضية. إذا كانت ترجمة مفقودة لحقل معين، تُستخدم قيمة اللغة الافتراضية كبديل.

GET /menus

استرجاع عناصر قائمة التنقل النشطة كشجرة متداخلة. يدعم تصفية اللغة والرؤية الواعية بالمصادقة.

bash

GET /api/v1/menus?locale=ar

استجابة (200):

json

{
  "success": true,
  "data": [
    {
      "id": "...",
      "title": "الرئيسية",
      "url": "/",
      "icon": "home",
      "target": "_self",
      "children": []
    },
    {
      "id": "...",
      "title": "من نحن",
      "url": "/about-us",
      "icon": null,
      "target": "_self",
      "children": [
        {
          "id": "...",
          "title": "فريقنا",
          "url": "/our-team",
          "icon": null,
          "target": "_self",
          "children": []
        }
      ]
    }
  ]
}

GET /lookups

استرجاع إدخالات البحث النشطة حسب النوع.

bash

GET /api/v1/lookups?type=country&locale=ar

GET /languages

استرجاع قائمة اللغات النشطة.

bash

GET /api/v1/languages

استجابة (200):

json

{
  "success": true,
  "data": [
    { "code": "en", "name": "English", "native_name": "English", "direction": "ltr", "is_default": true },
    { "code": "ar", "name": "Arabic", "native_name": "العربية", "direction": "rtl", "is_default": false }
  ]
}

GET /translations

استرجاع ترجمات واجهة المستخدم للواجهة الأمامية.

bash

GET /api/v1/translations?locale=ar&groups=common,auth,web.home

GET /settings/public

استرجاع الإعدادات العامة.

bash

GET /api/v1/settings/public

استجابة (200):

json

{
  "success": true,
  "data": {
    "app_name": "تطبيقي",
    "default_language": "ar",
    "date_format": "YYYY-MM-DD",
    "allow_registration": true
  }
}

لوحة التحكم الإدارية

GET /admin/stats

استرجاع إحصائيات لوحة التحكم. يتطلب صلاحية admin.view.

bash

GET /api/v1/admin/stats
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

استجابة (200):

json

{
  "success": true,
  "data": {
    "users_count": 156,
    "roles_count": 5,
    "contents_count": 23,
    "recent_activity": [
      { "action": "created", "resource_type": "user", "created_at": "..." }
    ]
  }
}

مرجع رموز الأخطاء

رمز الخطأ	حالة HTTP	الوصف
`VALIDATION_ERROR`	422	فشل التحقق من جسم الطلب
`UNAUTHORIZED`	401	رمز مفقود أو منتهي الصلاحية
`FORBIDDEN`	403	صلاحيات غير كافية
`NOT_FOUND`	404	المورد غير موجود
`RATE_LIMITED`	429	طلبات كثيرة جداً
`INTERNAL_ERROR`	500	خطأ خادم غير متوقع

انظر أيضاً

المصادقة -- تفاصيل تنفيذ JWT
الصلاحيات -- وسيط الصلاحيات
المسارات -- كود تسجيل المسارات
المعالجات -- تنفيذات معالجات الطلبات
معالجة الأخطاء -- تنسيق استجابات الأخطاء

عقود API ​

الرابط الأساسي ​

المصادقة ​

صيغة الاستجابة ​

استجابة ناجحة ​

استجابة مع تصفح ​

استجابة خطأ ​

رموز حالة HTTP ​

التصفح ​

نقاط نهاية المصادقة ​

POST /auth/login ​

POST /auth/register ​

POST /auth/refresh ​

POST /auth/logout ​

POST /auth/password/forgot ​

POST /auth/password/reset ​

POST /auth/otp/send ​

POST /auth/otp/verify ​

نقاط نهاية الملف الشخصي ​

GET /profile ​

PUT /profile ​

POST /profile/avatar ​

PUT /profile/password ​

نقاط نهاية الإدارة ​

المستخدمون ​

الأدوار ​

الصلاحيات ​

المحتويات ​

القوائم ​

جداول البحث ​

الإعدادات ​

اللغات ​

الترجمات ​

مفاتيح API ​

سجلات التدقيق ​

النقاط العامة ​

GET /contents/:slug ​

GET /menus ​

GET /lookups ​

GET /languages ​

GET /translations ​

GET /settings/public ​

لوحة التحكم الإدارية ​

GET /admin/stats ​

مرجع رموز الأخطاء ​

انظر أيضاً ​

عقود API

الرابط الأساسي

المصادقة

صيغة الاستجابة

استجابة ناجحة

استجابة مع تصفح

استجابة خطأ

رموز حالة HTTP

التصفح

نقاط نهاية المصادقة

POST /auth/login

POST /auth/register

POST /auth/refresh

POST /auth/logout

POST /auth/password/forgot

POST /auth/password/reset

POST /auth/otp/send

POST /auth/otp/verify

نقاط نهاية الملف الشخصي

GET /profile

PUT /profile

POST /profile/avatar

PUT /profile/password

نقاط نهاية الإدارة

المستخدمون

الأدوار

الصلاحيات

المحتويات

القوائم

جداول البحث

الإعدادات

اللغات

الترجمات

مفاتيح API

سجلات التدقيق

النقاط العامة

GET /contents/:slug

GET /menus

GET /lookups

GET /languages

GET /translations

GET /settings/public

لوحة التحكم الإدارية

GET /admin/stats

مرجع رموز الأخطاء

انظر أيضاً