XML feed за импорт на обяви

Как да подготвите XML feed за импорт на обяви в Realistimo. За ръчен 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 на вече свързани агенти.
Добавете оферти със стабилен offer_uid, category/subcategory, локация (internal_id е предпочитан), images, price, description, currency=eur.
Хостнете на публичен HTTPS URL → [email protected].
За ръчен sync: REST tutorial.

Geo файлове: CSV · PostgreSQL dump

Explanation

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

Feed ниво: <updated> е версията на feed-а. Ако е непроменена след последния успешен sync — импортът се пропуска.
Стар feed: ако <updated> се парсира като дата по-стара от 30 дни, обработката се спира.
Оферта ниво: при публикувана оферта, ако <last_update> е попълнено и не е по-ново от последната импортирана промяна, повечето полета се пропускат (цена, агент и описание пак се обновяват). Празно/липсващо <last_update> не включва този skip.
Липсващи оферти: оферти, които ги няма във feed-а, се свалят/архивират при нормален импорт.
Липсващи опционални тагове се четат като празни.

„Задължително“ по-долу означава: без стойност импортът/публикуването обикновено се чупи или офертата остава непубликувана. Много атрибути имат стойности по подразбиране.

How-to

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

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

Reference

Минимален пример

Копирайте скелета, заменете placeholders и сложете текущи дати (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, дати и съдържание).

Агенция

Таг	Описание	Бележки
`<updated>`	Версия / дата на feed-а	Задължително Трябва да се променя при промяна на съдържанието; max 30 дни назад
`<agency_uid>`	Source id на агенцията	Задължително Трябва да съвпада с конфигурирания id
`<agency_name>`, `<agency_phone>`, `<agency_email>`	Метаданни	По избор Не се използват от импорта; безопасни за съвместимост
`<result_url>`	Callback след импорт	По избор Realistimo праща POST с JSON като latest-log; виж REST

Брокери

<Brokers>/<Broker> дава контактни данни. broker_id на офертата трябва да съвпада с source id на агент, вече свързан към агенцията в Realistimo. Стойностите на BrokerID в XML трябва да са същите ids.

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

Оферти (поддържани полета)

Таг	Описание	Бележки
`<last_update>`	Промяна на офертата	Препоръчително Дата/час или unix timestamp. Ако е попълнено и не е по-ново от последната импортирана промяна, повечето полета на публикувана оферта се пропускат
`<offer_uid>`	Стабилен ID	Задължително Не променяйте при редакции
`<offer_code>`	Референтен код	По избор
`<title>`	Заглавие	По избор Отделно от описанието
`<description>`	Описание	Препоръчително Силно желателно за публикация
`<images>`	URL-и	Задължително Разделител `;`
`<price>`	Цена	Задължително Цяла част; при parent construction/complex се нулира
`<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` липсва/не е numeric
`<construction_type>`	епк / панел / тухла / гредоред / метална конструкция	По избор
`<floor>`, `<floorAll>`	Етаж / етажи	По избор Стойност `0` за `floor` се игнорира
`<building_condition>`	Completed / …	По избор
`<build_year>`	YYYY-MM-DD	По избор
`<furnished>`	0/14/23/65	По избор 0 и 23 = необзаведен
`<heating_ids>`	IDs през `,`	По избор 4/6/18 пелети, 35 климатик, 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	По избор Виж сграда/комплекс
`<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.