خاص بـ: الحزمة الكاملة · الواجهة البرمجية

مرجع الواجهة البرمجية

كل نقطة، ومعاملاتها، وردودها، ومن يحق له استدعاؤها.

كل النقاط تحت /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>