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 DB; альтернатива — subregion_id.
Валюта: отправляйте 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.

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

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

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

Значения

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

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

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

building_condition

Completed, UnderConstruction, PreConstruction, SemiCompleted, NotCompleted.

construction_type

епк, панел, тухла, гредоред, метална конструкция.

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

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