21 մայիս

Նախագծերի և պլանների XML Feed

1. Feed Purpose

XML feed-ը փոխանցում է կառուցապատման նախագծերի և տիպային պլանավորումների կառուցվածքային տվյալները։ Դրա նպատակը ստացող համակարգին թույլ տալն է ավտոմատ կերպով ստեղծել և թարմացնել project քարտերը, ցուցադրել գները, կարգավիճակները, պատկերասրահները, հարմարությունները, վճարման պայմանները, EOI-ն և մշակողների մարքեթինգային promo նյութերը։

Feed-ը պլանավորումները փոխանցում է ագրեգացված ձևաչափով՝ մեկ layout գրառում նկարագրում է տիպային պլանավորումը և այդ տեսակի հասանելի միավորների քանակը։ Սա կոնկրետ բնակարանների, գրասենյակների կամ հողամասերի ցանկ չէ։

realty-feed: ամբողջ XML feed-ի root container։ Main ID: —
offers: մեկ project կամ complex։ Main ID: complex-id
layouts: project-ի ներսում տիպային պլանավորում։ Main ID: id
payment_plans: project-ի մեկ վճարման տարբերակ։ Main ID: id
eoi_item: EOI-ի մեկ պայման։ Main ID: —
stock: մարքեթինգային արշավ, նորություն կամ մշակողի promo հաղորդագրություն։ Main ID: —

1.1 What Is an XML Feed

XML feed-ը կառուցվածքային ֆայլ է, որը պարունակում է տվյալներ անշարժ գույքի նախագծերի և տիպային պլանավորումների մասին։ Այն ներառում է նկարագրություններ, լուսանկարներ, գներ, հասցեներ, կարգավիճակներ, տեխնիկական բնութագրեր, հարմարություններ և այլ տվյալներ, որոնք անհրաժեշտ են անշարժ գույքը գործակալության կայքում կամ կատալոգում ցուցադրելու համար։

Պարզ ասած՝ XML feed-ը անշարժ գույքի տվյալների հոսք է, որը ստացող համակարգը պարբերաբար ներբեռնում է, կարդում և օգտագործում՝ property քարտերը ավտոմատ թարմացնելու համար։

Alnair-ը տրամադրում է տվյալները։ Կայքի մշակումը, կատալոգի ստեղծումը, CRM ինտեգրացիան և import-ի տրամաբանությունը իրականացնում է հաճախորդը կամ հաճախորդի տեխնիկական թիմը։

1.2 What The Agency Needs

XML feed-ը օգտագործելու համար գործակալությանը անհրաժեշտ է սեփական տեխնիկական ենթակառուցվածք, որը կարող է պարբերաբար ներբեռնել XML-ը, վերլուծել դրա կառուցվածքը և թարմացնել տվյալները իր համակարգում։

Website or property catalog: տեղը, որտեղ կցուցադրվեն feed-ի նախագծերն ու պլանավորումները։
Technical team or developer: XML-ի ներբեռնում, parsing և import-ի կարգավորում։
XML parser: XML կառուցվածքի ընթերցում և ներքին տվյալային մոդելի փոխակերպում։
Import module: նախագծերի և պլանավորումների ստեղծում, թարմացում և ապաակտիվացում։
Task scheduler: import-ի կանոնավոր կատարում ըստ ժամանակացույցի, օրինակ՝ cron կամ scheduler միջոցով։
Error logging: unknown enum արժեքների, դատարկ դաշտերի և բեռնման սխալների վերահսկում։

1.3 How The Agency Uses The XML Feed

Տիպային աշխատանքային գործընթացը հետևյալն է․

Գործակալության համակարգը XML-ը ներբեռնում է անձնական web link-ից։
XML-ը պահպանվում է որպես raw snapshot՝ ախտորոշման և վերամշակման համար։
Parser-ը կարդում է realty-feed, offers, layouts կառուցվածքը և ներքին բլոկները։
Import module-ը ստեղծում է նոր նախագծեր ու պլանավորումներ կամ թարմացնում է գոյություն ունեցողները։
Նոր feed-ից անհետացած օբյեկտները նշվում են որպես inactive։
Գործակալության կայքում ցուցադրվում են արդիական project քարտեր, գներ, պատկերասրահներ և կարգավիճակներ։

Main integration capabilities:

Automatic updates: նախագծերն ու պլանավորումները թարմացվում են առանց ձեռքով միջամտության։
Property page creation: feed-ի տվյալները օգտագործվում են project և layout քարտերի համար։
Up-to-date prices and statuses: կայքը ստանում է XML թարմացումները ըստ ժամանակացույցի։
Filters and search: district, price, property type, room count և area դաշտերը կարող են օգտագործվել ֆիլտրավորման համար։
Media galleries: project լուսանկարները, թեմատիկ պատկերասրահները և layout պատկերները կարող են ցուցադրվել ինտերֆեյսում։

2. General XML Structure

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

realty-feed: object. Root feed block.
generation-date: datetime. XML generation date and time. Used to check data freshness.
offers: object[]. List of projects or complexes. Each offers block contains project data and its layouts.

2.1 Feed Access and Download Limits

Feed-ը հաճախորդին տրամադրվում է անձնական web link-ով։ Այդ link-ը եզակի է հաճախորդի համար և օգտագործվում է ստացող համակարգի կողմից XML-ը ավտոմատ ներբեռնելու համար։

Անձնական link-ը հասանելի է Alnair հաշվում administrator-ին։ Administrator-ը կարող է այդ link-ը փոխանցել հաճախորդի տեխնիկական թիմին՝ import-ի կարգավորման համար։

Access type: personal web link. Individual XML feed URL for the client.
Where to get the link: Alnair account. The link is available to the client administrator.
Feed update frequency: every 4 hours. XML data is updated on the Alnair side once every 4 hours.
Minimum download interval: no more than once per hour. The receiving system must not access the feed more than once per hour.
Limit exceeded: access blocking. If requests are too frequent, feed access may be temporarily blocked.

Առաջարկվող ինտեգրման տրամաբանությունը՝ ներբեռնումը կարգավորել cron կամ scheduler միջոցով, պահպանել վերջին ստացված XML-ը և feed-ին չդիմել կայքի յուրաքանչյուր էջի բեռնման ժամանակ։ Օպտիմալ ռեժիմն է feed-ը ներբեռնել ոչ ավելի, քան մեկ անգամ մեկ ժամում՝ հաշվի առնելով, որ նոր տվյալները մոտավորապես յուրաքանչյուր 4 ժամում են հայտնվում։

3. Project: <offers>

offers-ը feed-ի հիմնական entity-ն է։ Այն պարունակում է project-ի նկարագրությունը, developer-ին, location-ը, կառուցման և վաճառքի կարգավիճակը, գները, media-ն, amenities-ը, payment plans-ը, EOI-ն, marketing promo-ներն ու տիպային պլանավորումները։

<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. Unique project ID in Alnair. Use as the external project ID for upsert.
type: enum. Top-level entity type: project or compound. Store the raw value and import as a top-level project.
logo: url. Project logo. Show in branding, do not use as cover.
photo: url. Main project image / cover. Use as cover image and hero image.
title: localized object. Project name in en/ru/ar. Display according to interface language.
description: localized HTML. Project description in en/ru/ar. Render safely; HTML is inside CDATA.
price_on_request: 0/1. Price hiding flag. If 1, show “Price on request”.
status: object. Construction status. Do not confuse with sales_status.
construction_start_at: datetime. Construction start date. Display if filled.
construction_progress: decimal. Construction completion percentage. Display as a percentage.
planned_completion_at: datetime. Planned project completion date. Use as the handover date.
predicted_completion_at: datetime. Predicted completion date. Can be used as an updated completion date.
amenities: object. Project amenities and features. Map by key.
developer: object. Project developer. Store name and logo.
city / address: string. Project city and address. Use in location data.
latitude / longitude: decimal. Coordinates. Use for the map.
districts: object. Project districts. Use for filters and the project card.
album: object. Main uncategorized project gallery. Show as the general gallery.
albums: object. Themed project galleries. Group by title.
for_sale_count: integer. Number of available units in the project. Can be displayed as availability.
price: object. General project price range. Hide when price_on_request=1.
br_prices: object[]. Prices by bedroom count or category. Use for filters and listings.
updated_at: datetime. Project update date. Use for synchronization.
is_sold_out: 0/1. Sold-out flag. Use together with sales_status.
payment_plans: object[]. Payment options from the developer. Display as payment options.
sales_status: localized object. Project sales status. Defines the sales stage.
stocks: object. Marketing campaigns and promotional messages from the developer. Display as promo blocks.
eoi: object. Expression of Interest. Display only for Presale (EOI).
service_charge: object. Service charge. Display if value is filled.
assignment: decimal. Assignment condition. Empty means not specified.
is_limited_publication: 0/1. Publication restriction. If 1, do not publish publicly without permission.
layouts: object[]. Typical project layouts. Import as child entities of the project.

4. Localized Fields

Localized fields ունեն նույն կառուցվածքը՝ արժեքները English, Russian և Arabic լեզուներով փոխանցվում են tag-ի ներսում։

<title>
  <en>Project Name</en>
  <ru>Название проекта</ru>
  <ar>اسم المشروع</ar>
</title>

en: English value. Recommended fallback.
ru: Russian value.
ar: Arabic value.

Fallback rule:

Use the interface language if it is filled.
If the required language is empty, use en.
If en is empty, use ru.
If ru is empty, use ar.
If all values are empty, do not display the field.

5. Statuses

5.1 Construction Status: <status>

Կառուցման կարգավիճակը ցույց է տալիս project-ի ֆիզիկական վիճակը։ Այն չի արտահայտում վաճառքի հասանելիությունը։

<status>
  <key>development_stage_progress</key>
  <en>In Progress</en>
  <ru>Строится</ru>
  <ar>قيد الإنشاء</ar>
</status>

Scheduled: նախագիծը պլանավորված է։
In Progress: կառուցումը ընթացքի մեջ է։
Ready: նախագիծն ավարտված է։
Stopped: կառուցումը դադարեցված է։

5.2 Sales Status: <sales_status>

Վաճառքի կարգավիճակը ցույց է տալիս project-ի կոմերցիոն փուլը՝ հայտարարում, presale, launch, active sales կամ sold out։

Preliminary Info: project-ի նախնական տեղեկություններ։
Announcement: project-ը հայտարարված է։
Presale (EOI): EOI-ի հավաքագրումը ընթացքի մեջ է։
Launch: վաճառքի մեկնարկ։
On Sale: project-ը հասանելի է գնման համար։
Sold Out: project-ը սպառված է։
Pending: կարգավիճակը սպասում է թարմացման։

6. Developer and Location

Այս բլոկները անհրաժեշտ են developer-ի բրենդը և project-ի աշխարհագրական location-ը ցուցադրելու համար։

<developer>
  <title>
    <en>Developer Name</en>
    <ru>Developer Name</ru>
    <ar>Developer Name</ar>
  </title>
  <logo>https://...</logo>
</developer>
<city>Dubai</city>
<address>Project Address, Dubai</address>
<latitude>25.01809076</latitude>
<longitude>55.13354525</longitude>
<districts>
  <district>Jumeirah Village Triangle (JVT)</district>
</districts>

developer.title: localized object. Developer name.
developer.logo: url. Developer logo.
city: string. City.
address: string. Address.
latitude / longitude: decimal. Coordinates for the map.
districts.district: string[]. Project districts.

7. Prices

7.1 Project Price: <price>

Project-ի մակարդակով գինը ցույց է տալիս project-ում առկա առաջարկների ընդհանուր price range-ը։

min: decimal. Minimum price.
max: decimal. Maximum price.
min_usd: decimal. Minimum price in USD.
max_usd: decimal. Maximum price in USD.
currency: enum. Main currency, usually AED.

If price_on_request = 1, exact prices are not displayed publicly, even if price is filled.

7.2 Prices by Category: <br_prices>

br_prices-ը խմբավորում է գներն ու մակերեսները bedroom count-ի կամ property type-ի ըստ։ Սա օգտակար է filters-ի և կարճ project քարտերի համար։

<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: studio բնակարաններ։
1-6: bedroom-ների քանակը։
villa: villas։
townhouse: townhouses։
n: ոչ կիրառելի / ոչ բնակելի կատեգորիա / այլ։

8. Media

Feed-ի media-ն բաժանված է մի քանի տեսակի։ Դրանք չպետք է միավորվեն մեկ պատկերասրահում՝ առանց նպատակը հաշվի առնելու․ մեկ image-ը կարող է լինել project-ի cover-ը, մյուսը՝ logo-ն, մեկ այլը՝ promo image, իսկ մյուսը՝ floor plan։

logo: offers.logo. Project-ի logo։ Ցուցադրել project branding-ում, չօգտագործել որպես cover։
photo: offers.photo. Project-ի հիմնական image / cover։ Օգտագործել որպես քարտի cover և project էջի hero image։
album.image: offers.album.image. Project-ի հիմնական, չդասակարգված պատկերասրահ։ Ցուցադրել ընդհանուր gallery-ում։
albums.album.images.image: offers.albums.album.images.image. Թեմատիկ project gallery։ Խմբավորել ըստ albums.album.title-ի։
developer.logo: offers.developer.logo. Developer-ի logo։ Ցուցադրել developer բլոկում։
stocks.stock.logo: offers.stocks.stock.logo. Մարքեթինգային արշավի image։ Ցուցադրել promo բլոկի ներսում։
layouts.album.image: offers.layouts.album.image. Տվյալ տիպային layout-ի պատկերասրահ։ Ցուցադրել layout մակարդակով։
levels_photos.level_photo.image: offers.layouts.levels_photos.level_photo.image. Layout-ի image՝ ըստ մակարդակի։ Օգտագործել որպես floor plan։

<photo>https://...</photo>
<album>
  <image>https://...</image>
</album>
<albums>
  <album>
    <title><en>Infrastructure</en><ru>Инфраструктура</ru><ar>...</ar></title>
    <images>
      <image>https://...</image>
    </images>
  </album>
</albums>

Project presentation: project-ի ներկայացման պատկերներ։
Construction progress: կառուցման ընթացքի լուսանկարներ։
Finishing examples: հարդարման օրինակներ։
Infrastructure: project-ի ենթակառուցվածք։
View: տեսարաններ և շրջակայք։

Ամեն project-ում պարտադիր չէ, որ բոլոր category-ները լինեն։ Եթե category-ի title-ը դատարկ է, images-ը կարող են ներմուծվել որպես չդասակարգված կամ տեղադրվել ընդհանուր gallery-ում։

Ներկայիս կառուցվածքում history/story-ի համար առանձին XML tag չկա։ Նորությունները, promo հաղորդագրությունները և project-ի marketing նյութերը փոխանցվում են stocks միջոցով։ Կառուցման պատմության համար կարելի է օգտագործել Construction progress category-ն, եթե այն կա albums-ում։

9. Amenities

amenities-ը նկարագրում է project-ի հարմարություններն ու առանձնահատկությունները։ Ինտեգրման համար ավելի ճիշտ է օգտագործել key-ը, իսկ ցուցադրման համար՝ localized արժեքները։

<amenities>
  <amenity>
    <key>project_facilities_gym</key>
    <en>Gym</en>
    <ru>Тренажёрный зал</ru>
    <ar>صالة رياضية</ar>
  </amenity>
</amenities>

amenities: object. Amenities container.
amenity: object. One amenity.
key: enum. Technical key.
en / ru / ar: string. Amenity name in three languages.

The key projecet_hotel_license contains a typo, but it must be mapped as Hotel License. It is recommended to support the alias and not break the import.

10. Marketing Promotions: <stocks>

stocks-ը մարքեթինգային արշավների, նորությունների և մշակողների promo հաղորդագրությունների համար է։ Դրանք կարող են ներառել հատուկ գներ, զեղչեր, launch-ի պայմաններ, EOI հայտարարություններ, ժամանակավոր վճարման առաջարկներ և գովազդային նյութեր։ Այս բլոկը inventory stock չէ և չի սահմանում միավորների հասանելիությունը։

<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. Marketing messages container.
stock: object. One campaign, news item, or promotional announcement.
title: localized object. Promotion title.
description: localized HTML. Promotion description.
start_at: datetime. Start date.
end_at: datetime. End date; may be empty.
logo: url. Promotion image.

Property availability-ի համար օգտագործեք 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 amount for 2 Bedrooms</en>
        <ru>Сумма EOI для 2-комнатных</ru>
        <ar>...</ar>
      </description>
    </eoi_item>
  </eoi_items>
</eoi>

is_eoi_return: 0/1/empty. 0 = non-refundable, 1 = refundable, empty = not specified.
eoi_items: object. EOI terms container.
eoi_item: object. One EOI condition.
price: decimal. Fixed EOI amount.
percent: decimal. EOI percentage, if used.
description: localized object. Condition description.

sales_status.en = Presale (EOI) and eoi_items is filled: show EOI.
Any other sales_status: hide EOI.

12. Service Charge and 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 amount. If empty, do not show the block.
service_charge.unit: calculation unit, usually sq. m. May be empty.
service_charge.currency: currency, usually AED. May be empty.
assignment: percentage after which assignment is possible. Empty = information not specified, not a restriction.

13. Payment Plans: <payment_plans>

payment_plans-ը նկարագրում է մշակողի կողմից property-ի համար առաջարկվող վճարման տարբերակները։ Մեկ project-ը կարող է ունենալ մի քանի payment plan։ Յուրաքանչյուր plan-ը վճարումը բաժանում է փուլերով՝ booking, construction, handover և post-handover։ Վճարներն ու հավելյալ վճարները փոխանցվում են առանձին, ուստի ընդհանուր տոկոսը կարող է գերազանցել 100%։ Օրինակ՝ 104% կարող է նշանակել property-ի գնի 100% + 4% DLD fee։

Basic: id, title, currency. Plan-ի նույնացուցիչ, title և currency։ title-ը ազատ տեքստ է, ոչ թե enum։
Booking: on_booking_percent, on_booking_fix, on_booking_payments_count, on_booking_fees. Վճարներ և fee-ներ booking փուլում։
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. Վճարումներ property-ի հանձնման պահին։
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. Plan-ի ընդհանուր գումարները և ներառված fee-ները։

14. Layouts: <layouts>

layouts-ը նկարագրում է project-ի ներսում տիպային պլանավորումը։ Դա ագրեգացված unit type է, ոչ թե կոնկրետ բնակարան կամ գրասենյակ։

id: integer. Unique layout ID. Use as the external layout ID.
title: localized object. Layout name. Display according to interface language.
project_id: integer. Parent project ID. Link with offers.complex-id.
building_name: localized object. Building name. Do not display if empty.
price_on_request: 0/1. Price hiding flag. If 1, do not show the price.
area_min / area_max: object. Area range. m2 and ft2.
area_balcony_min / area_balcony_max: object. Balcony area range. May be empty.
type: localized object. Property type. See Unit type reference.
sale_units_count: integer. Number of available units of this type. It is not a list of lots.
album: object. Layout gallery. Show at layout level.
levels_photos: object. Images by level. Use as floor plans.
floors_count: integer. Number of levels. 1, 2, 3, etc.
rooms_count: localized object. Room count. See Rooms count reference.
price: object. Layout price range. Hide when price_on_request=1.
is_limited_publication: 0/1. Publication restriction. If 1, hide publicly.

15. Enum Value References

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; empty is allowed for some fields.

If the feed contains a value that is not in the reference list, the import must not fail. The value must be stored as a raw value, mapped as unknown, and logged for review.

16. Empty Values

Դատարկ արժեքը նշանակում է «նշված չէ», ոչ թե 0։ Դատարկ tag-երը կարող են լինել <field/> կամ <field></field>։

assignment: assignment condition is not specified.
service_charge.value: service charge is not specified.
eoi.is_eoi_return: EOI refundability is not specified.
area_balcony_min.m2: balcony area is not specified.
description.en: description is missing.

17. Display Rules

Price hidden: price_on_request = 1. Show “Price on request”.
Price visible: price_on_request = 0. Show price min/max.
EOI: sales_status.en = Presale (EOI) and EOI is filled. Show EOI.
EOI not relevant: sales_status.en != Presale (EOI). Hide EOI.
Sold out: is_sold_out = 1 or sales_status.en = Sold Out. Show “Sold out” or hide from listing.
Limited publication: is_limited_publication = 1. Do not publish publicly.
Assignment empty: assignment empty. Do not show the assignment block.
Service charge empty: service_charge.value empty. Do not show service charge.

18. Import Rules

Project: search by complex-id; if found, update; if not found, create.
Layout: search by layouts.id; link to project by project_id.
Deletion: if an object disappears from the new feed, mark it inactive instead of deleting it immediately.
Unknown enum: store raw value, map as unknown, and log.
Empty values: do not convert to 0 without an explicit field-specific rule.

19. Recommended Data Structure

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.