فید XML برای پروژه‌ها و پلان‌ها

1. هدف فید

فید XML داده‌های ساختاریافته درباره پروژه‌های املاک و تیپ‌های معمول واحدها را منتقل می‌کند. هدف آن این است که سیستم دریافت‌کننده بتواند به‌صورت خودکار کارت پروژه‌ها را ایجاد و به‌روزرسانی کند، قیمت‌ها، وضعیت‌ها، گالری‌ها، امکانات، شرایط پرداخت، EOI و محتوای تبلیغاتی بازاریابی ارائه‌شده از سوی سازندگان را نمایش دهد.

فید، پلان‌ها را به‌صورت تجمیعی منتقل می‌کند: هر رکورد پلان، یک تیپ معمول و تعداد واحدهای موجود از همان نوع را توصیف می‌کند. این فید فهرستی از آپارتمان‌ها، دفاتر یا قطعات مشخص نیست.

• realty-feed: کانتینر ریشه برای کل فید XML. شناسه اصلی: —
• offers: یک پروژه یا مجتمع. شناسه اصلی: complex-id
• layouts: پلان معمول داخل یک پروژه. شناسه اصلی: id
• payment_plans: یک گزینه پرداخت پروژه. شناسه اصلی: id
• eoi_item: یک شرط EOI. شناسه اصلی: —
• stock: کمپین بازاریابی، خبر، یا پیام تبلیغاتی از طرف سازنده. شناسه اصلی: —

1.1 فید XML چیست

فید XML یک فایل ساختاریافته است که داده‌های مربوط به پروژه‌های املاک و پلان‌های معمول را در خود دارد. این فایل شامل توضیحات، تصاویر، قیمت‌ها، آدرس‌ها، وضعیت‌ها، مشخصات، امکانات و سایر داده‌های موردنیاز برای نمایش ملک در وب‌سایت آژانس یا کاتالوگ است.

به زبان ساده، فید XML یک جریان داده درباره املاک است که سیستم دریافت‌کننده آن را به‌طور منظم دانلود، خوانده و برای به‌روزرسانی خودکار کارت‌های ملک استفاده می‌کند.

Alnair داده‌ها را ارائه می‌دهد. توسعه وب‌سایت، توسعه کاتالوگ، یکپارچه‌سازی CRM و منطق ایمپورت توسط مشتری یا تیم فنی مشتری انجام می‌شود.

1.2 آژانس به چه چیزی نیاز دارد

برای استفاده از فید XML، آژانس به زیرساخت فنی خود نیاز دارد که بتواند به‌صورت منظم XML را دانلود کند، ساختار آن را تحلیل کند و داده‌ها را در سیستم خود به‌روزرسانی نماید.

• وب‌سایت یا کاتالوگ ملک: محلی که پروژه‌ها و پلان‌های موجود در فید نمایش داده می‌شوند.
• تیم فنی یا توسعه‌دهنده: راه‌اندازی دانلود XML، پارس کردن و ایمپورت.
• XML parser: خواندن ساختار XML و تبدیل آن به مدل داده داخلی.
• Import module: ایجاد، به‌روزرسانی و غیرفعال‌سازی پروژه‌ها و پلان‌ها.
• Task scheduler: اجرای منظم ایمپورت طبق زمان‌بندی، برای مثال از طریق cron یا scheduler.
• Error logging: پایش مقادیر enum ناشناخته، فیلدهای خالی و خطاهای بارگذاری.

1.3 آژانس چگونه از فید XML استفاده می‌کند

یک گردش‌کار معمول به این صورت است:

1. سیستم آژانس XML را از یک لینک وب شخصی دانلود می‌کند.
2. XML به‌عنوان یک snapshot خام برای عیب‌یابی و پردازش مجدد ذخیره می‌شود.
3. parser ساختار realty-feed، offers، layouts و بلوک‌های تو‌در‌تو را می‌خواند.
4. ماژول ایمپورت پروژه‌ها و پلان‌های جدید را ایجاد می‌کند یا موارد موجود را به‌روزرسانی می‌نماید.
5. مواردی که از فید جدید حذف شده‌اند، به‌عنوان غیرفعال علامت‌گذاری می‌شوند.
6. وب‌سایت آژانس کارت‌های پروژه، قیمت‌ها، گالری‌ها و وضعیت‌های به‌روز را نمایش می‌دهد.

قابلیت‌های اصلی یکپارچه‌سازی:

• به‌روزرسانی خودکار: پروژه‌ها و پلان‌ها بدون دخالت دستی به‌روزرسانی می‌شوند.
• ایجاد صفحه ملک: داده‌های فید برای کارت‌های پروژه و پلان استفاده می‌شود.
• قیمت‌ها و وضعیت‌های به‌روز: وب‌سایت طبق زمان‌بندی XML را دریافت می‌کند.
• فیلترها و جست‌وجو: منطقه، قیمت، نوع ملک، تعداد اتاق و متراژ برای فیلتر قابل استفاده هستند.
• گالری‌های رسانه‌ای: تصاویر پروژه، گالری‌های موضوعی و تصاویر پلان در رابط کاربری نمایش داده می‌شوند.

2. ساختار کلی XML

<realty-feed>
  <generation-date>2026-06-17T12:06:39+04:00</generation-date>
  <offers>...</offers>
  <offers>...</offers>
</realty-feed>

• realty-feed: object. بلوک ریشه فید.
• generation-date: datetime. تاریخ و ساعت تولید XML. برای بررسی تازگی داده‌ها استفاده می‌شود.
• offers: object[]. فهرست پروژه‌ها یا مجتمع‌ها. هر بلوک offers شامل داده‌های پروژه و پلان‌های آن است.

2.1 دسترسی به فید و محدودیت‌های دانلود

فید از طریق یک لینک وب شخصی در اختیار مشتری قرار می‌گیرد. این لینک مخصوص همان مشتری است و توسط سیستم دریافت‌کننده برای دانلود خودکار XML استفاده می‌شود.

لینک شخصی در حساب Alnair برای مدیر سیستم در دسترس است. مدیر می‌تواند این لینک را برای راه‌اندازی ایمپورت در اختیار تیم فنی مشتری قرار دهد.

• نوع دسترسی: لینک وب شخصی. URL اختصاصی فید XML برای مشتری.
• محل دریافت لینک: حساب Alnair. این لینک در اختیار مدیر مشتری است.
• فاصله به‌روزرسانی فید: هر 4 ساعت. داده‌های XML در سمت Alnair هر 4 ساعت یک‌بار به‌روزرسانی می‌شوند.
• حداقل فاصله دانلود: حداکثر یک‌بار در ساعت. سیستم دریافت‌کننده نباید بیش از یک‌بار در ساعت به فید دسترسی داشته باشد.
• عبور از حد مجاز: مسدود شدن دسترسی. اگر درخواست‌ها بیش از حد مکرر باشند، ممکن است دسترسی فید به‌طور موقت مسدود شود.

منطق پیشنهادی یکپارچه‌سازی: دانلود زمان‌بندی‌شده را از طریق cron یا scheduler تنظیم کنید، آخرین XML دریافت‌شده را ذخیره کنید و در هر بار بارگذاری صفحه وب‌سایت، فید را درخواست نکنید. حالت بهینه این است که فید حداکثر هر 1 ساعت یک‌بار دانلود شود، با در نظر گرفتن اینکه داده‌های جدید تقریباً هر 4 ساعت یک‌بار ظاهر می‌شوند.

3. پروژه: <offers>

offers موجودیت اصلی فید است. این بخش شامل توضیحات پروژه، سازنده، موقعیت مکانی، وضعیت ساخت و فروش، قیمت‌ها، رسانه، امکانات، طرح‌های پرداخت، EOI، پروموشن‌های بازاریابی و پلان‌های معمول است.

<offers>
  <complex-id>5646</complex-id>
  <type>project</type>
  <logo>https://...</logo>
  <photo>https://...</photo>
  <title>...</title>
  <description>...</description>
  <price_on_request>1</price_on_request>
  <status>...</status>
  <construction_start_at>2025-01-01T00:00:00+04:00</construction_start_at>
  <construction_progress>15</construction_progress>
  <planned_completion_at>2027-12-31T00:00:00+04:00</planned_completion_at>
  <predicted_completion_at>2027-12-31T00:00:00+04:00</predicted_completion_at>
  <amenities>...</amenities>
  <developer>...</developer>
  <city>Dubai</city>
  <address>...</address>
  <latitude>25.000000</latitude>
  <longitude>55.000000</longitude>
  <districts>...</districts>
  <album>...</album>
  <albums>...</albums>
  <constructions_count>1</constructions_count>
  <for_sale_count>10</for_sale_count>
  <price>...</price>
  <br_prices>...</br_prices>
  <updated_at>2026-06-17T10:53:20+04:00</updated_at>
  <is_sold_out>0</is_sold_out>
  <payment_plans>...</payment_plans>
  <sales_status>...</sales_status>
  <stocks>...</stocks>
  <eoi>...</eoi>
  <service_charge>...</service_charge>
  <assignment>...</assignment>
  <is_limited_publication>0</is_limited_publication>
  <layouts>...</layouts>
</offers>

• complex-id: integer. شناسه یکتای پروژه در Alnair. به‌عنوان شناسه خارجی پروژه برای upsert استفاده شود.
• type: enum. نوع موجودیت سطح بالا: project یا compound. مقدار خام را ذخیره کنید و به‌صورت یک پروژه سطح بالا ایمپورت کنید.
• logo: url. لوگوی پروژه. در برندینگ نمایش داده شود، نه به‌عنوان کاور.
• photo: url. تصویر اصلی پروژه / کاور. به‌عنوان تصویر کاور و hero استفاده شود.
• title: localized object. نام پروژه به en/ru/ar. مطابق زبان رابط کاربری نمایش داده شود.
• description: localized HTML. توضیحات پروژه به en/ru/ar. به‌صورت ایمن رندر شود؛ HTML داخل CDATA است.
• price_on_request: 0/1. پرچم مخفی‌سازی قیمت. اگر 1 باشد، «قیمت با درخواست» نمایش داده شود.
• status: object. وضعیت ساخت‌وساز. با sales_status اشتباه نشود.
• construction_start_at: datetime. تاریخ شروع ساخت. در صورت وجود نمایش داده شود.
• construction_progress: decimal. درصد پیشرفت ساخت. به‌صورت درصد نمایش داده شود.
• planned_completion_at: datetime. تاریخ برنامه‌ریزی‌شده تکمیل پروژه. به‌عنوان تاریخ تحویل استفاده شود.
• predicted_completion_at: datetime. تاریخ پیش‌بینی‌شده تکمیل. می‌تواند به‌عنوان تاریخ به‌روزشده تکمیل استفاده شود.
• amenities: object. امکانات و ویژگی‌های پروژه. بر اساس key نگاشت شود.
• developer: object. سازنده پروژه. نام و لوگو ذخیره شود.
• city / address: string. شهر و آدرس پروژه. در داده‌های موقعیت مکانی استفاده شود.
• latitude / longitude: decimal. مختصات. برای نقشه استفاده شود.
• districts: object. نواحی پروژه. برای فیلترها و کارت پروژه استفاده شود.
• album: object. گالری اصلی و بدون دسته‌بندی پروژه. به‌عنوان گالری عمومی نمایش داده شود.
• albums: object. گالری‌های موضوعی پروژه. بر اساس عنوان گروه‌بندی شوند.
• for_sale_count: integer. تعداد واحدهای قابل فروش در پروژه. می‌تواند به‌عنوان موجودی نمایش داده شود.
• price: object. بازه قیمت کلی پروژه. وقتی price_on_request=1 است مخفی شود.
• br_prices: object[]. قیمت‌ها بر اساس تعداد اتاق یا دسته‌بندی. برای فیلترها و لیست‌ها استفاده شود.
• updated_at: datetime. تاریخ به‌روزرسانی پروژه. برای همگام‌سازی استفاده شود.
• is_sold_out: 0/1. پرچم اتمام فروش. همراه با sales_status استفاده شود.
• payment_plans: object[]. گزینه‌های پرداخت از سوی سازنده. به‌عنوان گزینه‌های پرداخت نمایش داده شود.
• sales_status: localized object. وضعیت فروش پروژه. مرحله فروش را مشخص می‌کند.
• stocks: object. کمپین‌های بازاریابی و پیام‌های تبلیغاتی از سوی سازنده. به‌صورت بلوک‌های تبلیغاتی نمایش داده شود.
• eoi: object. Expression of Interest. فقط برای Presale (EOI) نمایش داده شود.
• service_charge: object. شارژ خدمات. در صورت تکمیل بودن مقدار نمایش داده شود.
• assignment: decimal. شرط assignment. خالی بودن یعنی مشخص نشده است.
• is_limited_publication: 0/1. محدودیت انتشار. اگر 1 باشد، بدون اجازه به‌صورت عمومی منتشر نشود.
• layouts: object[]. پلان‌های معمول پروژه. به‌عنوان موجودیت‌های فرزند پروژه ایمپورت شوند.

4. فیلدهای محلی‌سازی‌شده

فیلدهای محلی‌سازی‌شده ساختار یکسانی دارند: مقادیر انگلیسی، روسی و عربی داخل تگ منتقل می‌شوند.

<title>
  <en>نام پروژه</en>
  <ru>نام پروژه</ru>
  <ar>نام پروژه</ar>
</title>

• en: مقدار انگلیسی. گزینه پیشنهادی جایگزین.
• ru: مقدار روسی.
• ar: مقدار عربی.

قاعده جایگزینی:

1. اگر زبان رابط کاربری موجود باشد، از همان استفاده کنید.
2. اگر زبان موردنیاز خالی باشد، از en استفاده کنید.
3. اگر en خالی باشد، از ru استفاده کنید.
4. اگر ru خالی باشد، از ar استفاده کنید.
5. اگر همه مقادیر خالی باشند، فیلد نمایش داده نشود.

5. وضعیت‌ها

5.1 وضعیت ساخت: <status>

وضعیت ساخت، وضعیت فیزیکی پروژه را نشان می‌دهد. این بخش به در دسترس بودن برای فروش اشاره نمی‌کند.

<status>
  <key>development_stage_progress</key>
  <en>در حال ساخت</en>
  <ru>در حال ساخت</ru>
  <ar>قيد الإنشاء</ar>
</status>

• Scheduled: پروژه برنامه‌ریزی شده است.
• In Progress: ساخت در حال انجام است.
• Ready: پروژه تکمیل شده است.
• Stopped: ساخت متوقف شده است.

5.2 وضعیت فروش: <sales_status>

وضعیت فروش، مرحله تجاری پروژه را نشان می‌دهد: معرفی، پیش‌فروش، لانچ، فروش فعال یا اتمام فروش.

• Preliminary Info: اطلاعات اولیه پروژه.
• Announcement: پروژه اعلام شده است.
• Presale (EOI): جمع‌آوری EOI در حال انجام است.
• Launch: آغاز فروش.
• On Sale: پروژه برای خرید در دسترس است.
• Sold Out: پروژه به‌طور کامل فروخته شده است.
• Pending: وضعیت در انتظار به‌روزرسانی است.

6. سازنده و موقعیت مکانی

این بلوک‌ها برای نمایش برند سازنده و موقعیت جغرافیایی پروژه موردنیاز هستند.

<developer>
  <title>
    <en>نام سازنده</en>
    <ru>نام سازنده</ru>
    <ar>نام سازنده</ar>
  </title>
  <logo>https://...</logo>
</developer>
<city>Dubai</city>
<address>آدرس پروژه، Dubai</address>
<latitude>25.01809076</latitude>
<longitude>55.13354525</longitude>
<districts>
  <district>Jumeirah Village Triangle (JVT)</district>
</districts>

• developer.title: object محلی‌سازی‌شده. نام سازنده.
• developer.logo: url. لوگوی سازنده.
• city: string. شهر.
• address: string. آدرس.
• latitude / longitude: decimal. مختصات برای نقشه.
• districts.district: string[]. نواحی پروژه.

7. قیمت‌ها

7.1 قیمت پروژه: <price>

قیمت در سطح پروژه، بازه کلی قیمت برای پیشنهادهای موجود در پروژه را نشان می‌دهد.

<price>
  <min>815462</min>
  <max>2089780</max>
  <min_usd>222009</min_usd>
  <max_usd>568942</max_usd>
  <currency>AED</currency>
</price>

• min: decimal. حداقل قیمت.
• max: decimal. حداکثر قیمت.
• min_usd: decimal. حداقل قیمت به USD.
• max_usd: decimal. حداکثر قیمت به USD.
• currency: enum. ارز اصلی، معمولاً AED.

اگر price_on_request = 1 باشد، قیمت‌های دقیق به‌صورت عمومی نمایش داده نمی‌شوند، حتی اگر price تکمیل شده باشد.

7.2 قیمت‌ها بر اساس دسته‌بندی: <br_prices>

br_prices قیمت‌ها و متراژها را بر اساس تعداد اتاق یا نوع ملک گروه‌بندی می‌کند. این بخش برای فیلترها و کارت‌های کوتاه پروژه بسیار مفید است.

<br_prices>
  <key>1</key>
  <count>7</count>
  <min_price>1070564</min_price>
  <max_price>1289674</max_price>
  <min_price_m2>17204</min_price_m2>
  <max_price_m2>18483</max_price_m2>
  <currency>AED</currency>
  <min_area><m2>57.92</m2><ft2>623.45</ft2></min_area>
  <max_area><m2>74.17</m2><ft2>798.36</ft2></max_area>
</br_prices>

• studio: استودیوها.
• 1-6: تعداد اتاق خواب.
• villa: ویلاها.
• townhouse: تاون‌هاوس‌ها.
• n: نامرتبط / دسته غیرمسکونی / سایر.

8. رسانه

رسانه در فید به چند نوع تقسیم می‌شود. این موارد نباید بدون توجه به کاربردشان در یک گالری ادغام شوند: یک تصویر ممکن است کاور پروژه باشد، دیگری لوگو، دیگری تصویر پروموشن و دیگری پلان طبقه.

• logo: offers.logo. لوگوی پروژه. در برندینگ پروژه نمایش داده شود؛ به‌عنوان کاور استفاده نشود.
• photo: offers.photo. تصویر اصلی پروژه / کاور. به‌عنوان تصویر کاور در کارت و تصویر hero در صفحه پروژه استفاده شود.
• album.image: offers.album.image. گالری اصلی و بدون دسته‌بندی پروژه. در گالری عمومی پروژه نمایش داده شود.
• albums.album.images.image: offers.albums.album.images.image. گالری موضوعی پروژه. بر اساس albums.album.title گروه‌بندی شود.
• developer.logo: offers.developer.logo. لوگوی سازنده. در بلوک سازنده نمایش داده شود.
• stocks.stock.logo: offers.stocks.stock.logo. تصویر کمپین بازاریابی. داخل بلوک تبلیغاتی نمایش داده شود.
• layouts.album.image: offers.layouts.album.image. گالری یک پلان معمول مشخص. در سطح پلان نمایش داده شود.
• levels_photos.level_photo.image: offers.layouts.levels_photos.level_photo.image. تصویر پلان بر اساس طبقه. به‌عنوان نقشه طبقه استفاده شود.

<photo>https://...</photo>
<album>
  <image>https://...</image>
</album>
<albums>
  <album>
    <title><en>زیرساخت</en><ru>زیرساخت</ru><ar>...</ar></title>
    <images>
      <image>https://...</image>
    </images>
  </album>
</albums>

• Project presentation: تصاویر معرفی پروژه.
• Construction progress: عکس‌های پیشرفت ساخت.
• Finishing examples: نمونه‌های نازک‌کاری.
• Infrastructure: زیرساخت‌های پروژه.
• View: نماها و اطراف.

لازم نیست همه دسته‌ها در هر پروژه وجود داشته باشند. اگر عنوان دسته خالی باشد، تصاویر می‌توانند بدون دسته‌بندی وارد شوند یا در گالری عمومی قرار گیرند.

در ساختار فعلی، تگ جداگانه‌ای برای history/story XML وجود ندارد. اخبار، پیام‌های تبلیغاتی و مواد بازاریابی پروژه از طریق stocks منتقل می‌شوند. برای تاریخچه ساخت، اگر در albums وجود داشته باشد، می‌توان از دسته Construction progress استفاده کرد.

9. امکانات

amenities امکانات و ویژگی‌های پروژه را توصیف می‌کند. برای یکپارچه‌سازی، بهتر است از key استفاده شود و برای نمایش از مقادیر محلی‌سازی‌شده بهره ببرید.

<amenities>
  <amenity>
    <key>project_facilities_gym</key>
    <en>باشگاه ورزشی</en>
    <ru>باشگاه ورزشی</ru>
    <ar>صالة رياضية</ar>
  </amenity>
</amenities>

• amenities: object. کانتینر امکانات.
• amenity: object. یک امکان.
• key: enum. کلید فنی.
• en / ru / ar: string. نام امکان در سه زبان.

کلید projecet_hotel_license دارای یک تایپو است، اما باید به‌عنوان Hotel License نگاشت شود. توصیه می‌شود alias پشتیبانی شود تا ایمپورت دچار اختلال نشود.

10. پروموشن‌های بازاریابی: <stocks>

stocks کمپین‌های بازاریابی، اخبار و پیام‌های تبلیغاتی سازندگان هستند. این بخش می‌تواند شامل قیمت‌های ویژه، تخفیف‌ها، شرایط لانچ، اطلاعیه‌های EOI، پیشنهادهای موقت پرداخت و مواد تبلیغاتی باشد. این بلوک موجودی انبار نیست و دسترس‌پذیری واحدها را مشخص نمی‌کند.

<stocks>
  <stock>
    <title>...</title>
    <description>...</description>
    <start_at>2025-06-26T00:00:00+04:00</start_at>
    <end_at/>
    <logo>https://...</logo>
  </stock>
</stocks>

• stocks: object. کانتینر پیام‌های بازاریابی.
• stock: object. یک کمپین، خبر، یا اطلاعیه تبلیغاتی.
• title: object محلی‌سازی‌شده. عنوان پروموشن.
• description: HTML محلی‌سازی‌شده. توضیحات پروموشن.
• start_at: datetime. تاریخ شروع.
• end_at: datetime. تاریخ پایان؛ ممکن است خالی باشد.
• logo: url. تصویر پروموشن.

برای نمایش موجودی ملک از for_sale_count، layouts.sale_units_count و sales_status استفاده کنید، نه stocks.

11. EOI

EOI مخفف Expression of Interest است. این بخش، شرایط علاقه‌مندی اولیه یا ودیعه برای پروژه‌هایی با وضعیت Presale (EOI) را توصیف می‌کند.

<eoi>
  <is_eoi_return>0</is_eoi_return>
  <eoi_items>
    <eoi_item>
      <price>100000</price>
      <percent/>
      <description>
        <en>مبلغ EOI برای 2 Bedrooms</en>
        <ru>مبلغ EOI برای 2 Bedrooms</ru>
        <ar>...</ar>
      </description>
    </eoi_item>
  </eoi_items>
</eoi>

• is_eoi_return: 0/1/empty. 0 = غیرقابل‌استرداد، 1 = قابل‌استرداد، خالی = مشخص نشده.
• eoi_items: object. کانتینر شرایط EOI.
• eoi_item: object. یک شرط EOI.
• price: decimal. مبلغ ثابت EOI.
• percent: decimal. درصد EOI، در صورت استفاده.
• description: object محلی‌سازی‌شده. توضیح شرط.

• sales_status.en = Presale (EOI) و eoi_items تکمیل باشد: EOI نمایش داده شود.
• هر sales_status دیگری: EOI مخفی شود.

12. شارژ خدمات و assignment

<service_charge>
  <value>172.22</value>
  <unit>sq. m</unit>
  <currency>AED</currency>
</service_charge>
<assignment>40.00</assignment>

• service_charge.value: مبلغ شارژ خدمات. اگر خالی باشد، بلوک نمایش داده نشود.
• service_charge.unit: واحد محاسبه، معمولاً sq. m. ممکن است خالی باشد.
• service_charge.currency: ارز، معمولاً AED. ممکن است خالی باشد.
• assignment: درصدی که پس از آن assignment امکان‌پذیر است. خالی = اطلاعات مشخص نشده، نه محدودیت.

13. طرح‌های پرداخت: <payment_plans>

payment_plans گزینه‌های پرداخت ملک از سوی سازنده را توصیف می‌کند. یک پروژه می‌تواند چندین طرح پرداخت داشته باشد. هر طرح پرداخت را به مراحل مختلف تقسیم می‌کند: رزرو، ساخت، تحویل و پس از تحویل. کارمزدها و هزینه‌های اضافی جداگانه منتقل می‌شوند، بنابراین درصد کل ممکن است از 100% بیشتر شود. برای مثال، 104% می‌تواند به معنی 100% قیمت ملک + 4% کارمزد DLD باشد.

• Basic: id, title, currency. شناسه طرح، عنوان و ارز. title متن آزاد است و enum نیست.
• Booking: on_booking_percent, on_booking_fix, on_booking_payments_count, on_booking_fees. پرداخت‌ها و هزینه‌ها در مرحله رزرو.
• Construction: on_construction_percent, on_construction_fix, on_construction_payments_count, on_construction_fees. پرداخت‌ها در طول ساخت.
• Handover: on_handover_percent, on_handover_fix, on_handover_payments_count, on_handover_fees. پرداخت‌ها هنگام تحویل ملک.
• Post-handover: post_handover_percent, post_handover_fix, on_post_handover_payments_count, on_post_handover_fees. پرداخت‌ها پس از تحویل.
• ROI: roi_percent, roi_fix, roi_payments_count, roi_fees. فیلدهای مربوط به ROI یا طرح‌های درآمد تضمینی.
• Additional fees: additional, additional_percent, additional_fix, additional_fix_m2. پرداخت‌های اضافی، مانند DLD Fee.
• Periods: period_after_handover, period_after_roi. تناوب پرداخت‌های دوره‌ای.
• Totals: price_total, fees_included_total. مجموع مبالغ طرح و هزینه‌های شامل‌شده.

14. پلان‌ها: <layouts>

layouts یک پلان معمول داخل پروژه را توصیف می‌کند. این یک نوع واحد تجمیعی است، نه یک آپارتمان یا دفتر مشخص.

• id: integer. شناسه یکتای پلان. به‌عنوان شناسه خارجی پلان استفاده شود.
• title: object محلی‌سازی‌شده. نام پلان. مطابق زبان رابط کاربری نمایش داده شود.
• project_id: integer. شناسه پروژه والد. با offers.complex-id لینک شود.
• building_name: object محلی‌سازی‌شده. نام ساختمان. اگر خالی باشد نمایش داده نشود.
• price_on_request: 0/1. پرچم مخفی‌سازی قیمت. اگر 1 باشد، قیمت نمایش داده نشود.
• area_min / area_max: object. بازه متراژ. m2 و ft2.
• area_balcony_min / area_balcony_max: object. بازه متراژ بالکن. ممکن است خالی باشد.
• type: object محلی‌سازی‌شده. نوع ملک. به مرجع Unit type مراجعه شود.
• sale_units_count: integer. تعداد واحدهای موجود از این نوع. فهرستی از قطعات نیست.
• album: object. گالری پلان. در سطح پلان نمایش داده شود.
• levels_photos: object. تصاویر بر اساس طبقه. به‌عنوان پلان طبقه استفاده شود.
• floors_count: integer. تعداد طبقات. 1، 2، 3 و غیره.
• rooms_count: object محلی‌سازی‌شده. تعداد اتاق. به مرجع Rooms count مراجعه شود.
• price: object. بازه قیمت پلان. وقتی price_on_request=1 باشد مخفی شود.
• is_limited_publication: 0/1. محدودیت انتشار. اگر 1 باشد، به‌صورت عمومی مخفی شود.

15. مراجع مقادیر enum

• Project type: project, compound.
• Sales status: Preliminary Info, Announcement, Presale (EOI), Launch, On Sale, Sold Out, Pending.
• Construction status: Scheduled, Ready, Stopped, In Progress.
• Unit type: Apartment, Villa, Townhouse, Duplex, Triplex, Penthouse, Retail, Office, Suite.
• Rooms count: Studio, 1 BR, 2 BR, 3 BR, 4 BR, 5 BR, 6 BR, 7 BR, 8 BR, NA.
• BR price key: studio, 1, 2, 3, 4, 5, 6, villa, townhouse, n.
• Gallery category: Project presentation, Construction progress, Finishing examples, Infrastructure, View.
• Currency: AED.
• Service charge unit: sq. m.
• Boolean flags: 0, 1; برای برخی فیلدها مقدار خالی هم مجاز است.

اگر فید مقداری خارج از فهرست مرجع داشته باشد، ایمپورت نباید با شکست مواجه شود. مقدار باید به‌صورت خام ذخیره، به‌عنوان ناشناخته نگاشت و برای بررسی ثبت شود.

16. مقادیر خالی

مقدار خالی یعنی «مشخص نشده»، نه 0. تگ‌های خالی ممکن است به‌صورت <field/> یا <field></field> باشند.

• assignment: شرط assignment مشخص نشده است.
• service_charge.value: شارژ خدمات مشخص نشده است.
• eoi.is_eoi_return: قابل‌استرداد بودن EOI مشخص نشده است.
• area_balcony_min.m2: متراژ بالکن مشخص نشده است.
• description.en: توضیحات موجود نیست.

17. قواعد نمایش

• قیمت مخفی: price_on_request = 1. «قیمت با درخواست» نمایش داده شود.
• قیمت قابل مشاهده: price_on_request = 0. min/max قیمت نمایش داده شود.
• EOI: sales_status.en = Presale (EOI) و EOI تکمیل باشد. EOI نمایش داده شود.
• EOI نامرتبط: sales_status.en != Presale (EOI). EOI مخفی شود.
• Sold out: is_sold_out = 1 یا sales_status.en = Sold Out. «فروخته شد» نمایش داده شود یا از لیست مخفی شود.
• انتشار محدود: is_limited_publication = 1. به‌صورت عمومی منتشر نشود.
• Assignment خالی: assignment خالی است. بلوک assignment نمایش داده نشود.
• شارژ خدمات خالی: service_charge.value خالی است. شارژ خدمات نمایش داده نشود.

18. قواعد ایمپورت

• پروژه: جست‌وجو با complex-id؛ اگر یافت شد، به‌روزرسانی؛ اگر نه، ایجاد شود.
• پلان: جست‌وجو با layouts.id؛ اتصال به پروژه از طریق project_id.
• حذف: اگر یک موجودیت از فید جدید حذف شد، به‌جای حذف فوری، آن را غیرفعال کنید.
• Enum ناشناخته: مقدار خام ذخیره شود، ناشناخته نگاشت شود و ثبت گردد.
• مقادیر خالی: بدون قانون صریح مخصوص هر فیلد، به 0 تبدیل نشوند.

19. ساختار داده پیشنهادی

Project field → Source

• external_project_id: complex-id.
• raw_offer_type: type.
• title_*: title.
• description_*: description.
• developer_name: developer.title.
• developer_logo_url: developer.logo.
• city/address/coordinates: city, address, latitude, longitude.
• districts: districts.district.
• construction_status: status.en.
• sales_status: sales_status.en.
• price_min / price_max: price.
• price_on_request: price_on_request.
• galleries: photo, album, albums.
• payment_plans: payment_plans.
• eoi: eoi.
• stocks: stocks.
• source_updated_at: updated_at.

Layout field → Source

• external_layout_id: layouts.id.
• external_project_id: layouts.project_id.
• title_*: layouts.title.
• building_name_*: building_name.
• unit_type: type.en.
• rooms_count: rooms_count.en.
• sale_units_count: sale_units_count.
• area_min / area_max: area_min, area_max.
• balcony_min / balcony_max: area_balcony_min, area_balcony_max.
• floors_count: floors_count.
• price_min / price_max: price.
• layout_gallery: album.
• levels_photos: levels_photos.
• is_limited_publication: is_limited_publication.