21 мая

XML-лента для проектов и планировок

1. Назначение фида

XML-фид передаёт структурированные данные о проектах недвижимости и типовых планировках. Его задача — позволить принимающей системе автоматически создавать и обновлять карточки проектов, отображать цены, статусы, галереи, удобства, условия оплаты, EOI и маркетинговые промоматериалы от застройщиков.

Фид передаёт планировки в агрегированном виде: одна запись о планировке описывает типовую планировку и количество доступных юнитов этого типа. Это не список конкретных квартир, офисов или лотов.

realty-feed: корневой контейнер всего XML-фида. Основной ID: —
offers: один проект или комплекс. Основной ID: complex-id
layouts: типовая планировка внутри проекта. Основной ID: id
payment_plans: один вариант оплаты проекта. Основной ID: id
eoi_item: одно условие EOI. Основной ID: —
stock: маркетинговая кампания, новость или промо-сообщение от застройщика. Основной ID: —

1.1 Что такое XML-фид

XML-фид — это структурированный файл с данными о проектах недвижимости и типовых планировках. Он включает описания, фото, цены, адреса, статусы, характеристики, удобства и другие данные, необходимые для отображения объектов на сайте агентства или в каталоге.

Проще говоря, XML-фид — это поток данных о недвижимости, который принимающая система регулярно загружает, читает и использует для автоматического обновления карточек объектов.

Alnair предоставляет данные. Разработка сайта, создание каталога, интеграция с CRM и логика импорта выполняются клиентом или его технической командой.

1.2 Что нужно агентству

Чтобы использовать XML-фид, агентству нужна собственная техническая инфраструктура, способная регулярно скачивать XML, разбирать его структуру и обновлять данные в своей системе.

Сайт или каталог недвижимости: место, где будут отображаться проекты и планировки из фида.
Техническая команда или разработчик: настройка скачивания XML, парсинга и импорта.
XML-парсер: чтение структуры XML и преобразование её во внутреннюю модель данных.
Модуль импорта: создание, обновление и деактивация проектов и планировок.
Планировщик задач: регулярный запуск импорта по расписанию, например через cron или scheduler.
Логирование ошибок: контроль неизвестных значений enum, пустых полей и ошибок загрузки.

1.3 Как агентство использует XML-фид

Типичный процесс выглядит так:

Система агентства загружает XML по персональной веб-ссылке.
XML сохраняется как необработанный снимок для диагностики и повторной обработки.
Парсер читает структуру realty-feed, offers, layouts и вложенные блоки.
Модуль импорта создаёт новые проекты и планировки или обновляет существующие.
Объекты, которые исчезли из нового фида, помечаются как неактивные.
Сайт агентства отображает актуальные карточки проектов, цены, галереи и статусы.

Основные возможности интеграции:

Автоматическое обновление: проекты и планировки обновляются без ручного ввода.
Создание страниц объектов: данные фида используются для карточек проектов и планировок.
Актуальные цены и статусы: сайт получает XML-обновления по расписанию.
Фильтры и поиск: для фильтрации можно использовать поля район, цена, тип недвижимости, количество комнат и площадь.
Медиа-галереи: в интерфейсе можно показывать фото проекта, тематические галереи и изображения планировок.

2. Общая структура XML

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

realty-feed: объект. Корневой блок фида.
generation-date: datetime. Дата и время генерации XML. Используется для проверки актуальности данных.
offers: object[]. Список проектов или комплексов. Каждый блок offers содержит данные проекта и его планировки.

2.1 Доступ к фиду и ограничения на загрузку

Фид предоставляется клиенту по персональной веб-ссылке. Ссылка уникальна для клиента и используется принимающей системой для автоматической загрузки XML.

Персональная ссылка доступна администратору в аккаунте Alnair. Администратор может передать её технической команде клиента для настройки импорта.

Тип доступа: персональная веб-ссылка. Индивидуальный URL XML-фида для клиента.
Где получить ссылку: аккаунт Alnair. Ссылка доступна администратору клиента.
Частота обновления фида: каждые 4 часа. Данные XML обновляются на стороне Alnair один раз в 4 часа.
Минимальный интервал загрузки: не чаще 1 раза в час. Принимающая система не должна обращаться к фиду чаще одного раза в час.
Превышение лимита: блокировка доступа. При слишком частых запросах доступ к фиду может быть временно заблокирован.

Рекомендуемая логика интеграции: настроить плановую загрузку через cron или scheduler, сохранять последний полученный XML и не запрашивать фид при каждой загрузке страницы сайта. Оптимальный режим — загружать фид не чаще одного раза в час, учитывая, что новые данные появляются примерно каждые 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. Уникальный ID проекта в Alnair. Используйте как внешний ID проекта для upsert.
type: enum. Тип сущности верхнего уровня: project или compound. Сохраняйте сырое значение и импортируйте как проект верхнего уровня.
logo: url. Логотип проекта. Показывайте в брендинге, не используйте как обложку.
photo: url. Основное изображение проекта / обложка. Используйте как cover image и hero image.
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. Тематические галереи проекта. Группируйте по title.
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. Условие перепродажи. Пустое значение означает, что условие не указано.
is_limited_publication: 0/1. Ограничение публикации. Если 1, не публикуйте публично без разрешения.
layouts: object[]. Типовые планировки проекта. Импортируйте как дочерние сущности проекта.

4. Локализованные поля

Локализованные поля имеют одинаковую структуру: значения на английском, русском и арабском передаются внутри тега.

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

en: английское значение. Рекомендуемый запасной вариант.
ru: русское значение.
ar: арабское значение.

Правило fallback:

Используйте язык интерфейса, если он заполнен.
Если нужный язык пуст, используйте en.
Если en пуст, используйте ru.
Если ru пуст, используйте ar.
Если все значения пусты, не отображайте поле.

5. Статусы

5.1 Статус строительства: <status>

Статус строительства показывает физическое состояние проекта. Он не обозначает доступность для продаж.

<status>
  <key>development_stage_progress</key>
  <en>In Progress</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>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.logo: url. Логотип застройщика.
city: string. Город.
address: string. Адрес.
latitude / longitude: decimal. Координаты для карты.
districts.district: string[]. Районы проекта.

7. Цены

7.1 Цена проекта: <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. Основное изображение проекта / обложка. Используйте как cover image в карточке и hero image на странице проекта.
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>Infrastructure</en><ru>Инфраструктура</ru><ar>...</ar></title>
    <images>
      <image>https://...</image>
    </images>
  </album>
</albums>

Презентация проекта: изображения презентации проекта.
Ход строительства: фото прогресса строительства.
Примеры отделки: примеры отделки.
Инфраструктура: инфраструктура проекта.
Вид: виды и окружение.

Не каждая категория должна присутствовать в каждом проекте. Если название категории пустое, изображения можно импортировать как без категории или поместить в общую галерею.

В текущей структуре нет отдельного тега XML для истории/story. Новости, промо-сообщения и маркетинговые материалы проекта передаются через stocks. Для истории строительства можно использовать категорию Construction progress, если она присутствует в albums.

9. Удобства

amenities описывает удобства и особенности проекта. Для интеграции лучше использовать key, а для отображения — локализованные значения.

<amenities>
  <amenity>
    <key>project_facilities_gym</key>
    <en>Gym</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: localized object. Заголовок промо.
description: localized 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 amount for 2 Bedrooms</en>
        <ru>Сумма EOI для 2-комнатных</ru>
        <ar>...</ar>
      </description>
    </eoi_item>
  </eoi_items>
</eoi>

is_eoi_return: 0/1/empty. 0 = невозвратный, 1 = возвратный, empty = не указано.
eoi_items: object. Контейнер условий EOI.
eoi_item: object. Одно условие EOI.
price: decimal. Фиксированная сумма EOI.
percent: decimal. Процент EOI, если используется.
description: localized 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 fee.

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. Уникальный ID планировки. Используйте как внешний ID планировки.
title: localized object. Название планировки. Отображайте в зависимости от языка интерфейса.
project_id: integer. ID родительского проекта. Связывайте с offers.complex-id.
building_name: localized object. Название здания. Не показывайте, если пусто.
price_on_request: 0/1. Флаг скрытия цены. Если 1, цену не показывайте.
area_min / area_max: object. Диапазон площади. m2 и ft2.
area_balcony_min / area_balcony_max: object. Диапазон площади балкона. Может быть пустым.
type: localized object. Тип объекта. См. справочник Unit type.
sale_units_count: integer. Количество доступных юнитов этого типа. Это не список лотов.
album: object. Галерея планировки. Показывайте на уровне планировки.
levels_photos: object. Изображения по уровню. Используйте как планы этажей.
floors_count: integer. Количество уровней. 1, 2, 3 и т. д.
rooms_count: localized object. Количество комнат. См. справочник Rooms count.
price: object. Диапазон цен планировки. Скрывайте, если price_on_request=1.
is_limited_publication: 0/1. Ограничение публикации. Если 1, скрывайте публично.

15. Справочник значений enum

Тип проекта: project, compound.
Статус продаж: Preliminary Info, Announcement, Presale (EOI), Launch, On Sale, Sold Out, Pending.
Статус строительства: Scheduled, Ready, Stopped, In Progress.
Тип юнита: Apartment, Villa, Townhouse, Duplex, Triplex, Penthouse, Retail, Office, Suite.
Количество комнат: Studio, 1 BR, 2 BR, 3 BR, 4 BR, 5 BR, 6 BR, 7 BR, 8 BR, NA.
Ключ BR price: studio, 1, 2, 3, 4, 5, 6, villa, townhouse, n.
Категория галереи: Project presentation, Construction progress, Finishing examples, Infrastructure, View.
Валюта: AED.
Единица сервисного сбора: sq. m.
Булевы флаги: 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.
Распродано: 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: сохранять сырое значение, сопоставлять как unknown и логировать.
Пустые значения: не преобразовывать в 0 без явного правила для конкретного поля.

19. Рекомендуемая структура данных

Поле проекта → Источник

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.

Поле планировки → Источник

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.