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 файловете. Без него локацията се търси в описанието; ако не бъде открита, офертата остава непубликувана.
Валута: изпращайте 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. Оферта, чийто broker_id не съвпада със свързан агент, не се импортира, освен ако за агенцията не е настроен резервен агент.

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

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

Таг	Описание	Бележки
`<last_update>`	Промяна на офертата	Препоръчително Дата/час или unix timestamp. Ако е попълнено и не е по-ново от последната импортирана промяна, повечето полета на публикувана оферта се пропускат
`<offer_uid>`	Стабилен ID	Задължително Не променяйте при редакции
`<offer_code>`	Референтен код	По избор
`<title>`	Заглавие	По избор Отделно от описанието
`<description>`	Описание	Препоръчително Силно желателно за публикация
`<images>`	URL-и	Задължително Разделител `;`
`<price>`	Цена	Задължително Само цифри, без разделител за хилядите: всичко след първата запетая или точка се отрязва (`100,000` се импортира като 100). Интервалите не пречат. `0` или `1` = „Цена при запитване“. При parent construction/complex цената се нулира
`<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>`	Етаж / етажи	По избор Стойност `0` за `floor` се игнорира
`<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>`	IDs през `,`	По избор 4, 6 и 18 = твърдо гориво, 35 = климатик, 44 = електричество, 46 = централно парно, 80 = газ. Другите ids се игнорират
`<parking_ids>`	52, 93	По избор 52 = гараж, 93 = паркомясто. Другите ids се игнорират
`<rooms_count>`, `<bedroom_count>`, `<bath_count>`	Броеве	По избор Виж стойности по подразбиране
`<exterior_ids>`	IDs през `,`	По избор 42 = асансьор, 10 = асфалтов път. Другите ids се игнорират
`<broker_id>`	Source id на агент	Задължително Трябва да съвпада със свързан агент в Realistimo
`<construction_id>`	Parent offer_uid	По избор Виж сграда/комплекс
`<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 няма значение. Празен tag маха връзката. 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>