سجلّ التغييرات

الواجهة العامّة عقد. يُعلن التغيير الكاسر هنا أولًا، ويبقى السلوك القديم يعمل مدّة معلنة، ثم يُحذف بعدها. ولا يُسحب شيء دون أن يظهر في هذه الصفحة بتاريخ.

راقب هذه الصفحة — فهي المكان الوحيد الذي يُعلن فيه الحذف.

١٩ سبتمبر ٢٠٢٦

تغيّر — عروض المُلّاك

• POST /public/owner-listings يتطلّب زائرًا مسجّل الدخول ومؤكَّد الحساب. أرسل رمز الزائر في Authorization: Bearer <token>. والنداء المجهول يحصل على 401؛ ولا يسجّل الدخول إلا حساب مؤكَّد، فالرمز وحده دليل كافٍ. ويُسجَّل العرض باسم ذلك الحساب — ولم تعد الواجهة تطابق المالك بهاتف أو بريد مكتوب.
• name وphone اختياريّان؛ ويُسمّى المالك باسم الحساب عند غيابهما. و**email يُقبل ويُتجاهل** — فعنوان الحساب معروف أصلًا. وسيُحذف من جسم الطلب بإعلان هنا.
• أُزيل mediaUrls. الجسم الذي ما زال يرسله يحصل على 400. تُرفع الصور إلى العرض نفسه، فصار المسار ثلاثة نداءات:
  1. POST /public/owner-listings مع draft: true — ينشئ مسوّدة.
  2. POST /public/owner-listings/:id/media — ارفع الصور (multipart، حتى 20 صورة، 8 ميغابايت لكلٍّ منها، JPEG/PNG/WebP).
  3. POST /public/owner-listings/:id/submit — يرسله للمراجعة.
• الإرسال يتطلّب خمس صور على الأقل. الإرسال وإعادة الإرسال والإنشاء بغير مسوّدة تجيب بـ400 PHOTOS_TOO_FEW مع details: { min, count } تحت هذا الحدّ. ولا تُمنع المسوّدات ولا PATCH بسببه أبدًا.
• PATCH /public/owner-listings/:id يقبل name وphone، و**GET /public/owner-listings/:id يعيدهما**، فيملأ نموذج التعديل ما حُفظ لا ما في الملف الشخصي.
• mine و:id يعيدان listing: { slug, status } بعد أن يوافق فريق العمل على الطلب ويُنشأ العقار. ولا يظهر slug إلا ما دام الإعلان منشورًا — اربط به حين يوجد، ولا تربط حين يغيب.
• مسارات عروض المُلّاك تتطلّب وحدة realestate.secondary. المؤسّسة التي لا تملكها تجيب بـ403 MODULE_NOT_ENABLED على كل مسارات /public/owner-listings/*. اقرأ features.ownerListings (أدناه) وأخفِ مداخل «بِع وحدتك» حين تكون false.

تغيّر — جلسات الزائر

• صار إلغاء الرموز ممكنًا. تسجيل الخروج وتغيير كلمة المرور واستعادتها وحذف الحساب وتعطيل فريق العمل له — كلّها تنهي كل جلسات الحساب. والرمز الملغى يحصل على 401 VISITOR_SESSION_EXPIRED: امسحه ووجّه الزائر إلى تسجيل الدخول. والحساب المعطّل يحصل على 403 VISITOR_DISABLED عند الدخول وعلى أي نداء بعده.
• POST /public/me/password يعيد token جديدًا. التغيير يلغي الرمز الذي أجرى النداء، فاحفظ الجديد وإلّا كان الطلب التالي 401 VISITOR_SESSION_EXPIRED. وكلمة المرور الحالية الخاطئة 401 لا تنهي الجلسة.
• تسجيل الخروج يقرأ رمز Bearer من Authorization مثل كل نداء لمسجّل دخول — بلا جسم.
• resend-otp صار محميًّا من الروبوتات ومحدودًا لكل حساب. أرسل X-Turnstile-Token كما في عمليات الكتابة المحميّة الأخرى؛ وإعادة الإرسال خلال مهلة الانتظار تحصل على 429 RESEND_TOO_SOON مع details.retryAfterSeconds — اعرض عدًّا تنازليًّا بدل إعادة المحاولة.
• تسجيل الدخول لحساب غير مؤكَّد يعيد details.visitorId مع 401 VISITOR_EMAIL_NOT_VERIFIED، فتنتقل مباشرة إلى شاشة رمز التحقّق وتنادي resend-otp دون أن تطلب من الزائر التسجيل من جديد.
• روابط الاستعادة تحمل الرمز بصيغة <visitorId>.<secret>. مرّره كما هو. والرمز المشوّه أو القديم الصيغة أو المستخدم أو المنتهي يحصل على 400 RESET_TOKEN_INVALID.

أُضيف

• التسجيل يقبل intent وacceptTerms. intent اختياري، BUYER أو SELLER — تلميح يُسجَّل للنظام ولا يمنح أي صلاحية. وacceptTerms اختياري لكنه يجب أن يكون true حين يُرسل؛ أرسله حين يحوي نموذجك مربّع الموافقة على الشروط.
• GET /public/company-profile يكتسب features.ownerListings (منطقي — هل عروض المُلّاك مفتوحة في هذا الموقع) وsite.ownerReviewSlaHours (رقم أو null — المدّة التي يستهدفها فريق العمل للمراجعة، لنصوص «نردّ خلال …»).
• النطاق المُضاف وحده يعرّف الموقع على كل المسارات العامّة. النداء من المتصفّح على أحد نطاقات الموقع لا يحتاج ترويسة: Origin تكفي، بما فيها المسارات المقيّدة بوحدة، التي كانت ما زالت تطلب X-Subdomain. وما زالت X-Site وX-Subdomain تعملان. انظر تعريف موقعك.

رموز الأخطاء

١٤ سبتمبر ٢٠٢٦

أُضيف

• X-Site — تعريف الموقع بمفتاحه بدل تعريفه بمؤسّسته. صار بإمكان المؤسّسة أن تدير عدّة مواقع عامّة (عقارات، إقامات، ملف شركة)، وصار الطلب يعرّف موقعًا لا مستأجرًا فقط. والنطاق المُضاف يعرّف الموقع بلا ترويسة أصلًا. انظر تعريف موقعك.
• X-Api-Key — مفاتيح قابلة للنشر (pk_…) وسرّية (sk_…) لكل موقع، تُنشأ في النظام من الإعدادات ← المواقع ← اربط موقعك. المفتاح القابل للنشر لا يصلح إلا من نطاقات الموقع نفسه، والسرّي لخادمك وله خمسة أضعاف حدود المعدّل. والحالة الآن وضع المراقبة: يُخدَم النداء بلا مفتاح ويُسجَّل الرفض. وسيُعلن الإلزام هنا قبل تشغيله. انظر المفاتيح وCORS.
• X-Turnstile-Token — رمز Cloudflare Turnstile على عمليات الكتابة الخمس التي يستغلّها الروبوتات: العملاء المحتملون وطلبات المعاينة وتسجيل الزائر واستعادة كلمة المرور والنشرة البريدية. مطلوب مع المفتاح القابل للنشر، ومتجاوَز مع السرّي، ومعطّل حيث لا Turnstile مضبوط للموقع. انظر الحماية من الروبوتات.
• GET /public-openapi.json — وثيقة OpenAPI 3 قابلة للقراءة آليًّا تحتوي /api/public/* وحدها، وفيها الترويسات أعلاه معلنة على كل عملية. وهي مصدر مرجع الواجهة في هذه الوثائق، وهي ما تُوجّه إليه مولّد عميل.
• النصوص القانونية في ملف الشركة — تصل legal.privacy وlegal.terms نصًّا منسّقًا بصيغة { en, ar } بجوار privacyUrl وtermsUrl القائمين. صار بإمكان الموقع أن يرسم صفحتَي /privacy-policy و/terms من النظام بدل تثبيت النصّ في الكود: إن كان الرابط مضبوطًا فحوِّل إليه، وإلّا فاعرض النصّ إن وُجد، وإلّا فاعرض صفحتك الثابتة.
• أخطاء التحقّق في المعاينات — VIEWING_SLOT_INVALID وVIEWING_DAY_CLOSED وVIEWING_SLOT_TOO_SOON (400) وVIEWING_SLOT_TAKEN (409). صار الحجز يحترم أيام عمل الموقع وقائمة مواعيده ومنطقته الزمنية ومهلة الإشعار الدنيا، ولا يحمل الموعد الواحد إلا طلبًا حيًّا واحدًا. وقبل ذلك كان الحجز خارج القواعد يُقبل وكان بإمكان زائرَين أخذ الموعد نفسه. انظر الأخطاء.

هُجر

• X-Subdomain — ما زالت محترمة وما زالت تعرّف الموقع الافتراضي للمؤسّسة، فتبقى المواقع القائمة تعمل كما هي. لكنها لا تستطيع تسمية موقع بعينه من عدّة مواقع، ولهذا حلّت X-Site محلّها. تاريخ الحذف: سيُعلن هنا مع مهلة، بعد انتقال المواقع الحيّة. والانتقال سطر واحد: أرسل X-Site: <مفتاح الموقع> (من تبويب «اربط موقعك») بدلًا من X-Subdomain أو إلى جانبها.

أُزيل

• /api/public/promotion/* — اختفى مسار «روّج وحدتك» للمُلّاك وخططه من الواجهة ومن النظام. ولا بديل له. والموقع الذي ما زال ينادي تلك المسارات يحصل على 404؛ احذف النداءات وأي واجهة كانت تعرض الترويج.