مرجع واجهة API

كل مسار تقدّمه واجهة API، ومن يحق له استدعاؤه، وكيف تعمل تسجيلات الدخول والصلاحيات والأخطاء والقوائم والحدود.

لحزمة الحزمة الكاملة

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

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

مسارات الموقع عامة؛ أما مسارات لوحة التحكم فتحتاج إلى رمز Bearer لمسؤول، ومعظمها يحتاج أيضًا إلى صلاحية. أجسام الطلبات JSON، عدا رفع الملفات. تأتي كل إجابة في الغلاف نفسه:

الغلاف

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

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

فحص السلامة لا يحتاج إلى رمز:

الطرفية

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

الاستجابة

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

عندما يتعذر قراءة قاعدة البيانات يجيب أيضًا بـ 200، مع "status":"degraded" و"database":"down". يقرأ فحص السلامة في صورة Docker هذا الحقل.

الأخطاء

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

الخطأ

{
  "success": false,
  "data": null,
  "message": "…",
  "errors": { "email": ["…"] }
}

message جملة بلغة الطلب.
يظهر errors عند فشل التحقق، مع المشكلات لكل حقل، مفهرسة بالمسار الذي أرسله العميل (مثل title.en). ويُرفض أي حقل غير معروف في الجسم.
المسار المحمي من دون رمز، أو برمز منتهي، يجيب بـ 401؛ والرمز الذي ينقصه الصلاحية يجيب بـ 403.
الطلب الذي يتجاوز حدًّا يُجاب بـ 429.

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

قائمة

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

تُقسَّم العقارات والاستفسارات والمعاينات إلى صفحات بـ page وpage_size: 12 في الصفحة افتراضيًا في الموقع (وأقصاه 24)، و10 في لوحة التحكم (وأقصاه 50). وتعيد قوائم لوحة التحكم أيضًا أعدادها لكل حالة.
يُقسَّم المسؤولون والأدوار والإعدادات إلى صفحات بـ page وpage_count.
ما لم يكن للمسار ترتيبه الخاص، تأتي الصفوف بالأحدث تحديثًا أولًا، مع المعرّف لكسر التعادل، فيكون الترقيم مستقرًا.
يُتحقق من مرشحات عقارات الموقع: تُرفض القيمة غير المعروفة بالرمز 400 بدل تجاهلها، بينما يُتجاهل المفتاح الذي لا تقرؤه واجهة API، فيعمل الرابط المشارَك ذو المعاملات الإضافية.

اللغة

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

01
تسجيل دخول مسؤول
الطرفية
```
curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@velra.example","password":"Admin@123"}'
```
data.access_token هو الرمز، مع token_type بالقيمة Bearer والمسؤول بأدواره وصلاحياته. يدوم الرمز JWT_EXPIRATION، وهو 7d افتراضيًا، ويبلّغ expires_in عن تلك القيمة كما كُتبت. ويعيد GET /api/auth/me المسؤول المسجّل بأدواره وصلاحياته.

استدعِ مسارًا محميًا

الطرفية

curl http://localhost:8000/api/leads -H "Authorization: Bearer YOUR_TOKEN"

البريد غير المعروف وكلمة المرور الخاطئة يجيبان كلاهما بـ 401 مع الرسالة نفسها.
عشر محاولات دخول فاشلة من عنوان واحد خلال 15 دقيقة تُجاب بـ 429 حتى يمضي 15 دقيقة على أقدم محاولة فاشلة (RATE_LIMIT_LOGIN). ولا تُحتسب عمليات الدخول الناجحة.
لا يوجد مسار تسجيل ولا مسار تسجيل خروج: الحسابات تأتي من البيانات الأولية أو من إدارة المسؤولين، ويسجّل العميل الخروج بنسيان رمزه.

الطريقة	المسار	من يحق له استدعاؤه	وظيفته
`POST`	`/api/auth/login`	أي شخص	تسجيل دخول المسؤول: `email` و`password`
`GET`	`/api/auth/me`	أي مسؤول مسجّل دخوله	المسؤول المسجّل وأدواره وصلاحياته

الصلاحيات

تفحص مسارات لوحة التحكم صلاحية اسمها <area>.<action>. يملك المسؤول كل صلاحية من كل دور لديه، والمسار الذي يسمّي عدة صلاحيات يقبل أيًّا منها. الصلاحيات الـ 31 والدوران الأوليان مسرودة في المسؤولون والأدوار والصلاحيات.

عقارات الموقع

الطريقة	المسار	من يحق له استدعاؤه	وظيفته
`GET`	`/api/properties`	أي شخص	المنازل المنشورة. `purpose` (`sale` و`rent`)، و`type` (`apartment` و`villa` و`townhouse`)، و`neighborhood` (المعرّف النصي)، و`min_price` و`max_price`، و`bedrooms` (`0` للاستوديوهات، وإلا حد أدنى)، و`amenities` (معرّفات نصية مفصولة بفواصل، كلها مطلوبة)، و`q` (العنوان أو المرجع)، و`sort` (`newest` و`price_asc` و`price_desc`)، و`page` و`page_size`
`GET`	`/api/properties/featured`	أي شخص	المنازل المميزة في الصفحة الرئيسية: المراجع في إعداد `home_featured_references` بالترتيب، أو المنازل المنشورة المعلَّمة بأنها مميزة عندما لا ينشر أي منها
`GET`	`/api/properties/facets`	أي شخص	المنازل المنشورة معدودة حسب الغرض والنوع والحي، للمرشحات والصفحة الرئيسية
`GET`	`/api/properties/lookup`	أي شخص	المنازل المنشورة بالمعرّف، للمنازل المحفوظة والمقارنة: `?ids=1,2,3`، وأقصاه 12
`GET`	`/api/properties/:slug/similar`	أي شخص	حتى ثلاثة منازل منشورة مشابهة
`GET`	`/api/properties/:slug`	أي شخص	منزل منشور واحد كاملًا، مع معرضه وحيّه وغرفته المؤثثة العامة

الأحياء وإعدادات الوكالة

الطريقة	المسار	من يحق له استدعاؤه	وظيفته
`GET`	`/api/neighborhoods`	أي شخص	الأحياء المعلَّمة بأنها ظاهرة، بترتيب فرزها
`GET`	`/api/settings/public`	أي شخص	الإعدادات التي يعرضها الموقع: `agency_name` والعبارات التعريفية والأوصاف باللغتين، و`contact_email` و`agency_city` و`currency` و`timezone` و`home_featured_references` و`home_staging_property_slug`

نموذج التواصل وطلبات المعاينة

الطريقة	المسار	من يحق له استدعاؤه	وظيفته
`POST`	`/api/leads`	أي شخص	نموذج التواصل: `name` و`email` و`intent` (`buy` و`rent` و`other`) و`client_token` (UUID v4)، واختياريًا `phone` و`preferred_areas` (معرّفات نصية) و`budget` و`message` (1000 حرف) و`property_id`. يردّ `201` مع `{ id, received_at }`
`POST`	`/api/viewings`	أي شخص	طلب معاينة: `property_id` (منزل منشور) و`name` و`email` و`preferred_date` (`YYYY-MM-DD`) و`preferred_time` (`HH:MM`، بتوقيت الوكالة) و`client_token`، واختياريًا `phone` و`message`. يردّ `201` مع `{ reference, status, preferred_at, timezone }`

يعيد client_token المكرر إيصال الإرسال الأول بدل تخزين إرسال ثانٍ.
يُعامل الحقل company المملوء كأنه روبوت: يبدو الرد نفسه، ولا يُخزَّن شيء.
يجب أن تبدأ المعاينة بعد ساعة على الأقل، بتوقيت Asia/Dubai؛ وما كان أبكر يُجاب بـ 400 مع preferred_time_too_soon على preferred_at.
يمكن لكل عنوان إرسال خمسة من كل منهما في عشر دقائق؛ والتالي يُجاب بـ 429.

إدارة العقارات

الطريقة	المسار	من يحق له استدعاؤه	وظيفته
`GET`	`/api/properties/manage`	المسؤولون الذين لديهم `properties.view`	كل عقار، بما فيها المسودات. `purpose` و`type` و`status` و`q` و`page` و`page_size`؛ ويعيد `counts` للكل والمنشورة والمسودات
`GET`	`/api/properties/manage/:id`	المسؤولون الذين لديهم `properties.view`	عقار واحد كاملًا، مع معرضه وأزواج التأثيث
`POST`	`/api/properties/manage`	المسؤولون الذين لديهم `properties.create`	أنشئ مسودة. المطلوب: `title` (`en` و`ar`) و`purpose` و`type` و`price` و`bedrooms` و`bathrooms` و`area_sqm`
`PUT`	`/api/properties/manage/:id`	المسؤولون الذين لديهم `properties.edit`	غيّر أي حقل، بما فيه المعرض (`media`، حتى 40 عنصرًا)
`PATCH`	`/api/properties/manage/:id/status`	المسؤولون الذين لديهم `properties.publish`	اضبط `status`: `draft` أو `published` أو `sold` أو `rented` أو `archived`
`PUT`	`/api/properties/manage/:id/media`	المسؤولون الذين لديهم `properties.edit`	استبدل المعرض، بالترتيب، مع عنصر واحد معلَّم بـ `is_cover`
`DELETE`	`/api/properties/manage/:id`	المسؤولون الذين لديهم `properties.delete`	احذف العقار

الاستفسارات والمعاينات

الطريقة	المسار	من يحق له استدعاؤه	وظيفته
`GET`	`/api/leads`	المسؤولون الذين لديهم `leads.view`	الاستفسارات. `status` و`q` و`received_within_days` و`page` و`page_size`؛ مع أعداد لكل حالة
`GET`	`/api/leads/:id`	المسؤولون الذين لديهم `leads.view`	استفسار واحد مع عقاره وملاحظاته ومعاينته
`PATCH`	`/api/leads/:id`	المسؤولون الذين لديهم `leads.edit`	اضبط `status` (`new` و`contacted` و`qualified` و`closed`) و`notes`
`GET`	`/api/viewings`	المسؤولون الذين لديهم `viewings.view`	المعاينات. `status` و`q` و`scheduled_from` و`scheduled_to` و`page` و`page_size`؛ مع أعداد لكل حالة
`GET`	`/api/viewings/:id`	المسؤولون الذين لديهم `viewings.view`	معاينة واحدة مع استفسارها وعقارها
`PATCH`	`/api/viewings/:id`	المسؤولون الذين لديهم `viewings.edit`	`action` (`confirm` و`complete` و`cancel`) و`confirmed_at` (ISO 8601) و`admin_notes`. الإجراء من حالة غير مناسبة يُجاب بـ `400`
`GET`	`/api/overview`	المسؤولون الذين لديهم `overview.view`	النظرة العامة: الأعداد المنشورة، والاستفسارات الجديدة، والمعاينات بانتظار التأكيد والقادمة، وآخر الصفوف، والمنازل المميزة، ونقاط الخريطة

الأحياء والإعدادات

الطريقة	المسار	من يحق له استدعاؤه	وظيفته
`GET`	`/api/neighborhoods/manage`	المسؤولون الذين لديهم `neighborhoods.view`	كل حي، بما فيها المخفية
`POST`	`/api/neighborhoods/manage`	المسؤولون الذين لديهم `neighborhoods.create`	أضف واحدًا: `name` (`en` و`ar`)، واختياريًا `slug` و`short_description` و`city` و`is_featured` و`sort_order` و`is_active` و`cover_url` و`cover_alt`
`PUT`	`/api/neighborhoods/manage/:id`	المسؤولون الذين لديهم `neighborhoods.edit`	غيّر واحدًا
`DELETE`	`/api/neighborhoods/manage/:id`	المسؤولون الذين لديهم `neighborhoods.delete`	احذف واحدًا؛ وتبقى منازله موجودة بلا حي
`GET`	`/api/settings`	المشرفون الذين لديهم `settings.view`	كل إعداد. `search` و`category` و`page` و`page_count`
`GET`	`/api/settings/:key`	المشرفون الذين لديهم `settings.view`	إعداد واحد بالمفتاح
`PATCH`	`/api/settings/:key`	المشرفون الذين لديهم `settings.edit`	غيّر قيمة إعداد واحد
`DELETE`	`/api/settings/:key`	المشرفون الذين لديهم `settings.edit`	احذف إعدادًا واحدًا

المسؤولون والأدوار

الطريقة	المسار	من يحق له استدعاؤه	وظيفته
`GET`	`/api/admins`	المشرفون الذين لديهم `admins.view`	المسؤولون. `email` و`name` و`phone` و`page` و`page_count`
`GET`	`/api/admins/statistics`	المشرفون الذين لديهم `admins.view`	أعداد لقائمة المسؤولين
`GET`	`/api/admins/:id`	المشرفون الذين لديهم `admins.view`	مسؤول واحد، بالمعرّف أو اسم المستخدم
`POST`	`/api/admins`	المشرفون الذين لديهم `admins.create`	أضف مسؤولًا: `first_name` و`last_name` و`email` و`password` و`password_confirmation` (6 خانات أو أكثر)، واختياريًا `phone`
`PATCH`	`/api/admins/:id`	المشرفون الذين لديهم `admins.edit`	غيّر مسؤولًا
`PATCH`	`/api/admins/:id/roles`	المشرفون الذين لديهم `admins.assign_roles`	اضبط أدوار مسؤول: `role_ids`
`DELETE`	`/api/admins/:id`	المشرفون الذين لديهم `admins.delete`	احذف مسؤولًا
`PATCH`	`/api/admins/profile`	أي مسؤول مسجّل دخوله	غيّر `first_name` أو `last_name` أو `email` أو `phone` أو `profile_picture` أو `country_id` للمسؤول المسجّل نفسه. وجود `password` أو `role_ids` في الجسم يُجاب بـ `400`: فلبيانات الدخول مسارها الخاص
`PATCH`	`/api/admins/profile/password`	أي مسؤول مسجّل دخوله	غيّر بيانات دخول المسؤول المسجّل نفسه: `current_password` و`password` و`password_confirmation`
`GET`	`/api/roles`	المشرفون الذين لديهم `roles.view`	الأدوار. `name` و`guard_name` و`created_from` و`created_to` و`page` و`page_count`
`GET`	`/api/roles/statistics`	المشرفون الذين لديهم `roles.view`	أعداد لقائمة الأدوار
`GET`	`/api/roles/select`	المشرفون الذين لديهم `roles.view`	معرّف كل دور واسمه، لقائمة الاختيار
`GET`	`/api/roles/permissions`	المشرفون الذين لديهم `roles.view`	كل صلاحية، مجمعة حسب المنطقة
`GET`	`/api/roles/:id`	المشرفون الذين لديهم `roles.view`	دور واحد بصلاحياته
`POST`	`/api/roles`	المشرفون الذين لديهم `roles.create`	أضف دورًا
`PUT`	`/api/roles/:id`	المشرفون الذين لديهم `roles.edit`	أعد تسمية دور أو صفه
`POST`	`/api/roles/:id/permissions`	المشرفون الذين لديهم `roles.assign_permissions`	تعيين صلاحيات دور
`DELETE`	`/api/roles/:id`	المشرفون الذين لديهم `roles.delete`	حذف دور

الإشعارات والملفات المرفوعة

الطريقة	المسار	من يحق له استدعاؤه	وظيفته
`GET`	`/api/notifications`	أي مسؤول مسجّل دخوله	أحدث 30 إشعارًا للمسؤول المسجّل
`PATCH`	`/api/notifications/read-all`	أي مسؤول مسجّل دخوله	حدّدها كلها كمقروءة
`PATCH`	`/api/notifications/:id/read`	أي مسؤول مسجّل دخوله	تعليم إشعار واحد كمقروء
`DELETE`	`/api/notifications/:id`	أي مسؤول مسجّل دخوله	حذف إشعار واحد
`POST`	`/api/helpers/upload`	أي مسؤول مسجّل دخوله	خزّن ملفًا (`file` متعدد الأجزاء، مع `path` للمجلد و`for` لمقاس الحجم المسبق مثل `property` و`type`). تُعاد ترميز الصور، بعرض لا يتجاوز 1920 بكسل؛ وتُقبل مقاطع الفيديو بصيغة MP4 أو WebM أو MOV أو M4V؛ و150 ميغابايت على الأكثر. يردّ بعنوان الملف المخزَّن

ليس للملف المرفوع صلاحية خاصة به: يفحص المسار الذي يحفظه ما يصير إليه الملف. تُحفظ الإشعارات 30 يومًا.

الحدود لكل عنوان

المسار	الحد	المتغير
`POST /api/auth/login`	10 محاولات دخول فاشلة كل 15 دقيقة	`RATE_LIMIT_LOGIN`
`POST /api/leads`	5 كل 10 دقائق	لا شيء
`POST /api/viewings`	5 كل 10 دقائق	لا شيء

الطلب الذي يتجاوز حدًّا يُجاب بـ 429. العدّادات محفوظة في ذاكرة واجهة API، لذلك يمسحها إعادة التشغيل. خلف وكيل عكسي، اضبط TRUST_PROXY ليُحسب كل زائر على عنوانه.