كل النقاط تحت /api، وتستقبل JSON وترد به، وتوجد في src/app/api. المبالغ في المحتوى المرسل والردود دائماً بأصغر وحدة (البيسة للريال)، ولا يستقبل الأسعار بالريال إلا البحث العام في عنوانه.
الأعراف
- الأخطاء بشكل واحد:
{"error": {"code": "validation", "message": "..."}}مع رمز HTTP المناسب.
| الرمز | الأكواد |
|---|---|
| 400 | bad_json وbad_form |
| 401 | unauthorized وinvalid_credentials |
| 403 | forbidden (الدور) وdemo_mode |
| 404 | not_found وproperty_not_found (وكذلك لسجلات وسيط آخر) |
| 409 | bad_transition وemail_taken وslug_taken وhas_listings |
| 413 / 415 | too_large وunsupported_type |
| 422 | validation وinvalid_phone وpast_date وtoo_far وoutside_hours وunknown_area وunknown_agent وwrong_password وbad_image |
| 429 | rate_limited |
| 502 / 503 | ai_failed وai_not_configured |
- نقاط اللوحة تحتاج ملف الجلسة الذي يضعه
POST /api/auth/login، والنقاط التي تغيّر البيانات تُرفض في وضع العرض التجريبي. - نقاط PATCH لا تغيّر إلا الحقول الموجودة في المحتوى المرسل.
- النطاق: القوائم لا تحتوي للوسيط إلا سجلاته، والسجل المنفرد لغيره يرد بـ 404.
العامة
| الطريقة والمسار | الوظيفة | ملاحظات |
|---|---|---|
GET /api/properties |
البحث | المعاملات: purpose وtype وarea (slug) وgovernorate وminPrice وmaxPrice (بالريال) وbeds وbaths وfurnished وamenities (قائمة بفواصل) وq وfeatured=1 وids وagent (slug) وsort (newest وprice_asc وprice_desc وsize_desc) وpage وperPage (حتى 48). الرد {items, total, page, pages, currency, currencyDecimals}. 120 طلباً في الدقيقة لكل IP. |
GET /api/properties/{slug} |
عقار واحد | {property, similar, currency, currencyDecimals}، وفي property.around كل من places وmoments وlifeAr/lifeEn. يرد بـ 404 إلا إن كان «منشوراً» أو «عليه عرض». |
GET /api/compare?ids=a,b,c |
المقارنة والمحفوظات | حتى ثلاثة عقارات بتفاصيلها، أو خمسون بطاقة مع cards=1. وفي missing المعرّفات التي لم تعد معروضة. |
GET /api/areas |
المناطق | المناطق الظاهرة مع أماكنها وعدد عقاراتها المعروضة. |
GET /api/agents وGET /api/agents/{slug} |
الوسطاء | الموظفون الظاهرون على الموقع، ووسيط واحد مع عقاراته المعروضة. |
GET /api/agency |
بيانات الوكالة | الأسماء والتواصل والعملة. |
POST /api/inquiries |
إرسال سؤال | {name, phone, email?, message, propertyId?, locale} ← 201 {code}. خمسة طلبات في الدقيقة لكل IP. |
POST /api/viewings |
طلب معاينة | {name, phone, email?, propertyId, preferredDate: "YYYY-MM-DD", preferredTime: "HH:MM", message?, locale} ← 201 {code}. من اليوم حتى ٦٠ يوماً، بين 08:00 و20:00. |
الجلسة
| الطريقة والمسار | الوظيفة |
|---|---|
POST /api/auth/login |
{email, password} ← يضع ملف الجلسة ويرد بـ {user}. عشر محاولات في الدقيقة لكل IP، وثماني في ربع ساعة لكل بريد. |
POST /api/auth/logout |
يحذف ملف الجلسة. |
GET /api/auth/me |
{user, demoMode}. |
اللوحة
| الطريقة والمسار | لمن | الوظيفة |
|---|---|---|
GET /api/dashboard/stats |
الجميع | النظرة العامة: الأعداد وrecentLeads وupcomingViewings وbyArea وrecentlyUpdated. |
GET /api/dashboard/properties |
الجميع | المعاملات status وpurpose وtype وarea (معرّف) وagent (معرّف أو unassigned) وq وpage، و٢٥ في الصفحة. |
POST /api/dashboard/properties |
الجميع | إنشاء عقار. الحقول: titleAr وtitleEn وdescAr وdescEn وpurpose وtype وstatus (DRAFT أو PUBLISHED) وprice وbedrooms وbathrooms وareaM2 وplotM2 وfurnished وyearBuilt وamenities[] وaddressAr وaddressEn وareaId وagentId (للمديرين) وfeatured (للمديرين) وimages: [{url, virtual}]. |
GET/PATCH/DELETE /api/dashboard/properties/{id} |
صاحبه أو المديرون | القراءة، وتغيير أي مجموعة من الحقول (مع مسار الحالات)، والحذف (للوسيط: مسوداته). |
POST /api/dashboard/upload |
الجميع | multipart بحقل file واحد أو أكثر ← 201 {urls}. |
GET /api/dashboard/leads |
صاحبها أو المديرون | المعاملات kind وstatus وagent وproperty وq وpage. |
GET/PATCH /api/dashboard/leads/{id} |
صاحبه أو المديرون | القراءة مع الملاحظات والمعاينات، وتغيير status (المسار) وagentId (للمديرين). |
POST /api/dashboard/leads/{id}/notes |
صاحبه أو المديرون | {body} يضيف ملاحظة. |
GET /api/dashboard/viewings |
صاحبها أو المديرون | المعاملات from وto وstatus وagent. |
POST /api/dashboard/viewings |
لعقاراته أو المديرون | {propertyId, leadId?, name, phone, date, time, status?, note?, agentId?}. |
PATCH /api/dashboard/viewings/{id} |
صاحبها أو المديرون | status (مسار المعاينة) وdate وtime وnote وagentId (للمديرين). |
POST /api/dashboard/ai/listing |
الجميع | كاتب الإعلانات. انظر المساعد الذكي. |
POST /api/dashboard/ai/ask |
الجميع | أسئلة عن العقارات. |
POST /api/dashboard/ai/staging |
الجميع | انظر استوديو التأثيث. |
GET/POST /api/dashboard/areas وPATCH/DELETE /api/dashboard/areas/{id} |
القراءة للجميع والتغيير للمديرين | المناطق مع places: [{kind, nameAr, nameEn, minutes}]. |
GET/POST /api/dashboard/agents وPATCH/DELETE /api/dashboard/agents/{id} |
القراءة للجميع والتغيير للمديرين | حسابات الفريق. المالك يدير المديرين والوسطاء، والمدير يدير الوسطاء. |
GET /api/dashboard/roles |
الجميع | الأدوار وجدول الصلاحيات. |
GET/PATCH /api/dashboard/settings |
القراءة للجميع والتغيير للمالك | إعدادات الوكالة. |
GET/PATCH /api/dashboard/me |
الجميع | الملف الشخصي، وكلمة المرور الجديدة تحتاج currentPassword. |
مثال
# الدخول وحفظ ملف الجلسة
curl -c jar -H "Content-Type: application/json" \
-d '{"email":"owner@dar.test","password":"dar-demo-2026"}' http://localhost:3303/api/auth/login
# تغيير حالة عقار إلى «عليه عرض» دون أن يتغير شيء آخر
curl -b jar -X PATCH -H "Content-Type: application/json" \
-d '{"status":"UNDER_OFFER"}' http://localhost:3303/api/dashboard/properties/<id>