XML feed для импорта объявлений

Как подготовить XML feed для импорта объявлений в Realistimo. Для on-demand sync см. REST API.

Overview

Обзор

XML (эта страница)

Что публиковать в feed и как импорт читает поля.

REST

API-ключ, POST /start, POST /latest-log, ограничения и опциональный callback.

Tutorial

Начало работы

Скопируйте минимальный пример ниже или скачайте более полный образец XML.
Укажите в agency_uid source id, который Realistimo выдал вашему агентству, а в broker_id — source id агентов, уже связанных в Realistimo.
Добавьте объявления со стабильным offer_uid, category/subcategory, локацией (internal_id), images, price, description, currency=eur.
Разместите feed на публичном HTTPS URL и отправьте его на [email protected].
Для ручного sync: REST tutorial.

Файлы geo lookup: CSV · PostgreSQL dump

Explanation

Как работает синхронизация

Уровень feed: <updated> — версия feed. Если она не изменилась с последнего успешного sync, импорт пропускается.
Устаревший feed: если <updated> парсится как дата старше 30 дней, обработка останавливается.
Уровень объявления: для опубликованного объявления, если <last_update> присутствует и не новее последнего импортированного изменения, большинство полей пропускаются (цена, назначение агента и описание всё равно обновляются). Пустой/отсутствующий <last_update> не вызывает этот skip.
Отсутствующие объявления: объявления, которых нет в feed, снимаются/архивируются при обычном запуске импорта.
Отсутствующие необязательные XML-теги считаются пустыми — не нужно включать каждый необязательный тег.

«Обязательно» ниже означает: без значения импорт/публикация обычно завершается ошибкой или объявление остаётся неопубликованным. У многих атрибутов есть значения по умолчанию.

How-to

Как подготовить feed

Root <feed>, брокеры в <Brokers>, объявления в <offers>.
Локация: internal_id города, села или района из geo-файлов. Без него локация ищется в описании; если не найдена, объявление остаётся неопубликованным.
Валюта: отправляйте eur.
При каждом реальном изменении обновляйте <updated> feed и <last_update> у затронутых объявлений.
URL должен быть доступен серверным клиентам (без интерактивного Cloudflare challenge).

Reference

Минимальный пример

Скопируйте этот skeleton, замените placeholders и укажите актуальные timestamps (YYYY-MM-DD HH:MM:SS, не старше 30 дней).

<?xml version="1.0" encoding="UTF-8"?>
<feed>
  <updated>YYYY-MM-DD HH:MM:SS</updated>
  <agency_uid>YOUR_AGENCY_SOURCE_ID</agency_uid>
  <Brokers>
    <Broker>
      <BrokerID>YOUR_AGENT_SOURCE_ID</BrokerID>
      <BrokerName>Ivan Ivanov</BrokerName>
      <BrokerPhone>0888000000</BrokerPhone>
      <BrokerEmail>[email protected]</BrokerEmail>
    </Broker>
  </Brokers>
  <offers>
    <offer>
      <offer_uid>offer-1</offer_uid>
      <last_update>YYYY-MM-DD HH:MM:SS</last_update>
      <description>Test listing</description>
      <images>https://example.com/a.jpg</images>
      <price>100000</price>
      <surface>70</surface>
      <currency>eur</currency>
      <category>продажби</category>
      <subcategory>2-СТАЕН</subcategory>
      <internal_id>8545</internal_id>
      <broker_id>YOUR_AGENT_SOURCE_ID</broker_id>
    </offer>
  </offers>
</feed>

Скачать более полный образец XML (эталон формы — всё равно замените ids, timestamps и содержимое на свои).

Agency

Тег	Описание	Примечания
`<updated>`	Версия / дата feed	Обязательно Должна меняться при изменении содержимого; не старше 30 дней
`<agency_uid>`	Source id агентства	Обязательно Должен совпадать с id, настроенным для вашего агентства
`<agency_name>`, `<agency_phone>`, `<agency_email>`	Метаданные	Необязательно Импортом не используются; безопасно для совместимости
`<result_url>`	Callback после импорта	Необязательно Realistimo отправляет POST с JSON-телом в форме latest-log; см. REST

Brokers

<Brokers>/<Broker> задаёт контактные данные брокера для feed. broker_id объявления должен совпадать с source id агента, уже связанным с вашим агентством в Realistimo (настраивается при интеграции). Значения XML BrokerID должны использовать те же ids. Объявление, чей broker_id не совпадает со связанным агентом, не импортируется, если для агентства не настроен резервный агент.

Тег	Примечания
`<BrokerID>`	Обязательно Source id агента (предпочтительно ≠ `agency_uid`)
`<BrokerName>`	Обязательно Имя (+ фамилия)
`<BrokerPhone>`, `<BrokerEmail>`, `<BrokerPhoto>`	Необязательно

Offers (поддерживаемые поля)

Тег	Описание	Примечания
`<last_update>`	Время изменения объявления	Рекомендуется Дата/время или unix timestamp. Если присутствует и не новее последнего импортированного изменения, большинство полей у опубликованных объявлений пропускаются
`<offer_uid>`	Стабильный id	Обязательно Не меняйте при правках
`<offer_code>`	Код ссылки	Необязательно
`<title>`	Фрагмент заголовка	Необязательно Отдельно от описания
`<description>`	Описание	Рекомендуется Настоятельно желательно для публикации
`<images>`	URL	Обязательно Разделитель `;`
`<price>`	Цена	Обязательно Только цифры, без разделителя тысяч: всё после первой запятой или точки отбрасывается (`100,000` импортируется как 100). Пробелы не мешают. `0` или `1` = «Цена договорная». Для parent здания/комплекса цена обнуляется
`<surface>`	Площадь м²	Обязательно Требуется для большинства типов. Для гаража и парковочного места без площади записывается 18 м². Про землю см. участок и земля
`<surface_parcel>`	Участок/двор	Необязательно Площадь двора в м². Если `surface` отсутствует, используется и как площадь объекта
`<currency>`	Валюта	Обязательно `eur`. Если его нет, цена отображается почти вдвое ниже.
`<category>`	`продажби` / `наеми`	Обязательно
`<subcategory>`	Тип объекта	Обязательно Должно быть точным поддерживаемым значением (см. ниже)
`<internal_id>`	Geo internal id	Обязательно id города, села или района из geo-файлов. Если отсутствует или неверен, локация ищется в описании; если не найдена, объявление остаётся неопубликованным
`<subregion_id>`	Mapped location id	Необязательно Используется только некоторыми старыми интеграциями. Не полагайтесь на него — отправляйте `internal_id`
`<construction_type>`	епк / панел / тухла / гредоред	Необязательно Только строчными буквами, см. значения
`<floor>`, `<floorAll>`	Этаж / этажи	Необязательно Значение `floor` `0` игнорируется
`<building_condition>`	Этап строительства	Необязательно См. значения
`<build_year>`	YYYY-MM-DD / YYYY	Необязательно Полная дата или только год (`2005`). Год без даты принимается с 1800 до 10 лет вперёд, иначе игнорируется. Более старые здания показываются как период («До 1989» или «Между 1990 и 2004»)
`<furnished>`	0 / 14 / 23 / 65	Необязательно `14` = мебелированный, `65` = частично мебелированный, `0` и `23` = без мебели. Отсутствующее или другое значение записывается как «Я не уверен», даже если в описании написано «мебелированный» — поэтому отправляйте тег всегда
`<heating_ids>`	ID через `,`	Необязательно 4, 6 и 18 = твёрдое топливо, 35 = кондиционер, 44 = электричество, 46 = центральное отопление, 80 = газ. Остальные ids игнорируются
`<parking_ids>`	52, 93	Необязательно 52 = гараж, 93 = парковочное место. Остальные ids игнорируются
`<rooms_count>`, `<bedroom_count>`, `<bath_count>`	Количество	Необязательно См. значения по умолчанию
`<exterior_ids>`	ID через `,`	Необязательно 42 = лифт, 10 = асфальтированная дорога. Остальные ids игнорируются
`<broker_id>`	Source id агента	Обязательно Должен совпадать с агентом, связанным в Realistimo
`<construction_id>`	Parent offer_uid	Необязательно См. how-to здания/комплекса
`<youtube_link>` / `<youTube_link>`	YouTube	Необязательно
`<virtual_panorama_link>`	Виртуальная экскурсия	Необязательно Распознаются ссылки Matterport, Giraffe360, CloudPano, Panoee, imot360, Zelanos, Renderimo, Webobook и Kuula (короткая ссылка bit.ly). Остальные ссылки пропускаются, не блокируя публикацию
`<Exclusive>`	0/1	Необязательно

Значения

subcategory (поддерживаемые значения)

СТАЯ, АПАРТАМЕНТ, ЕДНОСТАЕН, БОКСИОНЕРА, СТУДИО, 1-СТАЕН, 2-СТАЕН, 3-СТАЕН, 4-СТАЕН, МНОГОСТАЕН, МЕЗОНЕТ, ГАРСОНИЕРА, ГАРСОНИЕРА ЛУКС
АТЕЛИЕ · АТЕЛИЕ, ТАВАН · ТАВАН · ЕТАЖ ОТ КЪЩА · КЪЩА · ВИЛА
ОФИС, МАГАЗИН, ТЪРГОВСКИ ОБЕКТ, ЗАВЕДЕНИЕ, СПОРТ, САЛОН ЗА КРАСОТА, СКЛАД, ГАРАЖ, ПАРКОМЯСТО, ПРОМ. ПОМЕЩЕНИЕ, ХОТЕЛ
БИЗНЕС ИМОТ, ДРУГО — коммерческая недвижимость
ПАРЦЕЛ, ЗЕМЕДЕЛСКА ЗЕМЯ — см. участок и земля
СГРАДИ, СГРАДА — целое здание с ценой (не parent для construction_id)
НОВА СГРАДА, СГРАДА НОВО СТРОИТЕЛСТВО — parent construction
ЗАТВОРЕН КОМПЛЕКС — parent complex

Отправляйте значения точно как в списке, заглавными буквами (кириллица). Неизвестные значения приводят к ошибке импорта объявления.

building_condition

Completed (или bds-completed) — С актом 16
SemiCompleted (или semi_completed) — С актом 15
NotCompleted (или not_completed) — С актом 14
UnderConstruction — В строительстве/с разрешением на строительство
PreConstruction (или pre_construction) — На зелёном (концептуальный проект)

Заглавные и строчные буквы имеют значение.

construction_type

епк — ЕПК (ползучая опалубка)
панел — Панель
тухла — Кирпич (с бетонными плитами)
гредоред — Кирпич (на балке)

Только строчными буквами: Тухла не распознаётся.

Значения по умолчанию

Когда тег отсутствует или пуст, импорт записывает:

Тег	Значение по умолчанию
`<heating_ids>`	Электричество
`<rooms_count>`	Для квартиры — по `subcategory` (`2-СТАЕН` = 2), иначе 1
`<bedroom_count>`	Число комнат минус 1, но не менее 1
`<bath_count>`	1, но не больше числа комнат
`<building_condition>`	С актом 16
`<construction_type>`	Я не уверен (только для продажи)
`<furnished>`	Я не уверен (для всех типов)
`<surface>`	Площадь из описания, если она там указана; для гаража и парковочного места — 18 м²

Отопление, комнаты, спальни, ванные, этап и тип строительства не заполняются для участка, сельскохозяйственной земли, гаража, парковочного места и нового здания.

Игнорируемые теги

Эти теги не применяются при импорте. Они могут присутствовать в feed, но не влияют на объявление: balcony_count, land_category, parcel_in_regulation, new_construction.

How-to

Здание / комплекс → квартиры

Parent: subcategory — одно из НОВА СГРАДА, СГРАДА НОВО СТРОИТЕЛСТВО, ЗАТВОРЕН КОМПЛЕКС.
Child: <construction_id>PARENT_OFFER_UID</construction_id>.
Порядок в XML не важен. Пустой тег снимает связь. Self-ref / недействительный parent игнорируется.

Участок и земля

Для участка нет отдельных тегов — он подаётся как обычное объявление:

<subcategory>ПАРЦЕЛ</subcategory> для участка под застройку или ЗЕМЕДЕЛСКА ЗЕМЯ для сельскохозяйственной земли. Лес, виноградник, пастбище и сад пока подать нельзя.
<surface> — это площадь объекта в м². Значение от 0 до 1 читается как декары: 0.8 = 800 м² (с точкой, не с запятой). Если surface отсутствует, берётся surface_parcel, а затем площадь из описания.
Достаточно <internal_id> города или села — район не обязателен.
Комнаты, этаж, тип строительства и меблировка не нужны.
Асфальтированная дорога: <exterior_ids>10</exterior_ids>. Для электричества и воды тегов нет — напишите в (болгарском) описании точно «ток и вода на граница» (или только «ток на граница» / «вода на граница»). Другие формулировки могут не распознаться.
Назначение также определяется по (болгарскому) описанию. Если там не указано, для ПАРЦЕЛ записываются «Жилая застройка» и «Коммерческое строение», а для ЗЕМЕДЕЛСКА ЗЕМЯ поле остаётся пустым.
land_category и parcel_in_regulation игнорируются.

<offer>
  <offer_uid>parcel-1</offer_uid>
  <last_update>YYYY-MM-DD HH:MM:SS</last_update>
  <title>Парцел в село Лозен</title>
  <description>Равен парцел с лице към улица. Ток и вода на граница.</description>
  <images>https://example.com/p1.jpg;https://example.com/p2.jpg</images>
  <price>85000</price>
  <surface>1200</surface>
  <currency>eur</currency>
  <category>продажби</category>
  <subcategory>ПАРЦЕЛ</subcategory>
  <internal_id>9433</internal_id>
  <exterior_ids>10</exterior_ids>
  <broker_id>YOUR_AGENT_SOURCE_ID</broker_id>
</offer>