Náš vlastný, čo najjednoduchší formát - jeden XML súbor so všetkými vašimi ponukami na
verejnej (alebo heslom chránenej) adrese vo vašom webe/serveri. Žiadne API, žiadne
prihlasovanie navyše.
Feed vieme aj VYDAŤ, opačným smerom - ak chcete naše inzeráty ukázať na vlastnom webe,
vo svojom účte si zapnite „XML feed mojich inzerátov (vydávanie)" a dostanete adresu tvaru
/api/feed/<názov-napojenia>-<token>.xml (časť pred tokenom je len
kozmetická, overuje sa výhradne token za ňou), ktorú si váš web stiahne sám. Adresu
nájdete na karte feedu kedykoľvek znova, nielen pri vygenerovaní.
Verejná špecifikácia nášho vlastného formátu na import inzerátov (nie formát cudzieho portálu). Realitná
kancelária (slovenská s vlastným softvérom, alebo zahraničná, ktorá nemá prístup k importu pre
Nehnuteľnosti.sk/United Classifieds - ten berie len Slovensko) hostuje na vlastnej URL jeden XML súbor so
VŠETKÝMI svojimi aktuálnymi ponukami. My si ho ťaháme pravidelne (pull, typ napojenia bydo_xml,
Tyrion\Classes\Integrations\Types\BydoXmlType). Je to najjednoduchší spôsob napojenia - na strane
realitky stačí jeden statický/generovaný XML súbor, žiadne API, žiadne prihlasovanie.
Feed vieme aj VYDAŤ - v presne tomto formáte, opačným smerom: realitka, ktorá má svoje inzeráty u
nás a chce ich ukázať na vlastnom webe (alebo inom softvéri), si v účte zapne napojenie typu „XML feed
mojich inzerátov (vydávanie)" a dostane adresu s tokenom (GET /api/feed/{token}.xml), ktorú si jej web
stiahne sám. Typ napojenia xml_feed_out, Tyrion\Classes\Integrations\XmlFeedOutGenerator.
Na stiahnutie: api/docs/bydo-xml.xsd (XSD schéma na overenie súboru),
api/docs/bydo-xml-vzor.xml (vzorový súbor - SK byt, SK dom, SK
pozemok, zahraničná ponuka).
Koreň a opakujúci sa uzol
<?xml version="1.0" encoding="UTF-8"?>
<export portal="bydo" generated="2026-11-16T11:09:51.212Z" count="11">
<listing>...</listing>
<listing>...</listing>
</export>
Súbor vždy nesie kompletný stav (všetky aktuálne ponuky) - žiadne "zmenené od". Ponuka, ktorá zo
súboru zmizne, sa podľa nastavenia napojenia skryje/archivuje (missing_mode), ponuka, ktorá sa do
súboru vráti, sa znova zverejní.
Pole <listing>
| Pole |
Povinné |
Popis |
U nás |
id |
áno |
Jedinečné ID ponuky (UUID alebo vlastný tvar) - podľa neho párujeme pri opakovanom importe. |
integration_external_id |
ref_code |
nie |
Vlastné referenčné číslo kancelárie. |
- (zatiaľ nepoužité) |
status |
áno |
active (zverejniť) alebo reserved (zverejniť + štítok "Rezervované", ak ho web má). Iná hodnota (sold, canceled...) = ponuka sa nepreberá (ak už u nás je, skryje sa) - nie je to chyba, zdroj väčšinou takú ponuku z feedu jednoducho vynechá. |
product.hidden, štítok |
transaction |
áno |
sale alebo rent. Iná/chýbajúca hodnota = chyba importu tejto ponuky (nahlási sa, ostatné ponuky to neovplyvní). |
sale-operation-type (predaj/prenájom) |
type |
nie |
apartment / house / land / commercial / warehouse... (môžu pribudnúť ďalšie) - len orientačné, pozri "Kategória" nižšie. |
- |
subtype |
nie |
Text podtypu - používa sa len keď kategóriu nevie určiť nič presnejšie (pozri "Kategória"). |
- |
category |
nie |
Kategória podľa číselníka Nehnuteľností.sk/United Classifieds (rovnaký, aký používa United Classifieds import aj export) - číselný kód kategórie ako text, napr. 61 (Skladový objekt). Použite, keď disposition/rooms nedáva zmysel (domy, pozemky, komerčné priestory...). |
podkategória produktu |
rooms |
nie |
Počet izieb bytu (celé číslo) - slovenský spôsob, bez českej notácie "+kk"/"+1". Kuchyňa sa do počtu izieb nepočíta. |
podkategória "N izbový byt" |
title |
áno |
Názov ponuky. |
product.title |
description |
nie |
Popis (HTML tagy sa odstránia). |
product.description |
description_en |
nie |
Anglický popis - zatiaľ sa nepreberá (jadro má jeden popis na jazyk mutácie, nie na ponuku). |
- |
price |
nie |
Číslo. Chýba/0 = cena dohodou. |
product.price_sell |
currency |
nie |
ISO kód meny (EUR, CZK...) - predvolené EUR. |
product.currency, product.price_eur (denný kurz ECB) |
price_unit |
nie |
m2, month, year, day, m2_month, m2_year; total alebo chýba = celá cena, pri transaction=rent mesačne (nájom sa udáva za mesiac). |
property-sale-currency |
price_note |
nie |
Text k cene (napr. podmienky nájmu). |
product.price_info |
commission_included |
nie |
zatiaľ sa nepreberá. |
- |
disposition |
nie |
Česká dispozícia bytu (1+kk, 2+1...). Používa sa AJ na kategóriu (pozri nižšie), AJ ako parameter. Má prednosť pred rooms. |
disposition, podkategória "N izbový byt" |
usable_area |
nie |
Základná plocha 1 - obytná (úžitková) plocha v m². |
useful-area |
built_area |
nie |
Základná plocha 2 - zastavaná plocha (pôdorys stavby, napr. domu) v m². |
built-up-area |
land_area |
nie |
Základná plocha 3 - plocha pozemku v m². |
area-of-land |
floor_area |
nie |
Podlahová plocha v m² - len náhrada úžitkovej plochy: použije sa iba vtedy, keď usable_area chýba. Do zastavanej plochy sa nikdy nepreberá. |
useful-area (len bez usable_area) |
balcony_area / terrace_area / cellar_area |
nie |
Doplnkové plochy v m². |
balcony-area / terrace-area / cellar-area |
floor / total_floors / underground_floors |
nie |
Podlažie, počet podlaží, počet podzemných podlaží. |
floor / floors / number-of-sublevels |
building_type |
nie |
brick, panel, mixed... (pozri mapovanie nižšie). |
material |
building_condition |
nie |
new, very_good, after_reconstruction... |
property-state |
ownership |
nie |
personal, cooperative, company, other. |
ownership |
energy_class |
nie |
A-G. |
energy-certificate |
furnished |
nie |
yes/no. |
furnishing (zjednodušené - "no" vlastný rozdiel medzi čiastočne/vôbec nerozlišuje) |
heating_systems.heating_system[] |
nie |
Kúrenie - kódy z číselníka Nehnuteľnosti.sk (UC), obalový <heating_systems> s opakovaným <heating_system> (viac hodnôt, ako images), napr. <heating_systems><heating_system>717</heating_system><heating_system>729</heating_system></heating_systems>. Kódy pozri tabuľku nižšie. |
heating (viac hodnôt) |
year_built / year_reconstructed |
nie |
Roky. |
year-of-construction / year-of-reconstruction |
address.country |
áno |
ISO 3166-1 alpha-2 (napr. SK, CZ). Bez neho sa ponuka neprijme (chyba importu). |
lokalita (pozri nižšie) |
address.region |
nie |
Kraj/provincia - len pre zahraničie (mimo SK). |
kraj v real_location (nový, ak chýba) |
address.district |
nie |
Okres. Pre Slovensko pomáha presne priradiť obec, keď existuje viac obcí rovnakého mena. |
- |
address.city |
áno (ak chýba city_part) |
Mesto/obec. Bez obce AJ mestskej časti sa ponuka neprijme. |
property-city |
address.city_part |
nie |
Mestská časť - má prednosť pred city, ak ju strom danej krajiny pozná ako samostatnú obec (len mimo SK). |
property-city |
address.street |
nie |
Ulica (prípadne aj s číslom domu). |
street |
address.postal_code |
nie |
PSČ - zatiaľ sa nepreberá. |
- |
address.latitude / address.longitude |
nie |
GPS. Bez nich sa súradnice mesta dohľadajú geokóderom (len mimo SK) alebo ostanú prázdne. |
product-latitude / product-longitude |
address.hide_exact |
nie |
true = skryť presnú adresu na webe. |
hidden-address |
images.image[] |
nie |
url (povinné), atribúty order (poradie), kind (photo...), main (true pri hlavnej fotke - poradie rozhoduje order, main sa zatiaľ nevyhodnocuje samostatne). |
fotky, cudzia URL sa postupne premiestni k nám |
detail_url |
nie |
Odkaz na pôvodnú ponuku - zatiaľ sa neukladá (generujeme vlastný odkaz). |
- |
broker.name / .email / .phone / .web |
nie |
Maklér - podľa e-mailu sa páruje/zakladá ako child klient kancelárie. |
child client (type=broker) |
agency.name / .ico |
nie |
Kancelária - zatiaľ sa neukladá (napojenie samo nesie, pod ktorú kanceláriu ponuky idú). |
- |
updated_at |
nie |
zatiaľ sa nepreberá (súbor vždy nesie kompletný stav, nie je potrebné na synchronizáciu). |
- |
Neznáme/nepodporované pole v <listing> jadro jednoducho ignoruje (nie je to chyba) - pokojne doplňte
vlastné rozšírenia pre budúcnosť, len sa zatiaľ nič s nimi nestane.
Fotky
images.image[], povinný je len url - fotku si stiahneme sami. Odporúčame JPEG/PNG/WebP, rozumnú
veľkosť (niekoľko MB na fotku, nie desiatky) - väčšie súbory môžu pri sťahovaní zlyhať na časovom alebo
veľkostnom limite. Fotka, ktorá sa pri sťahovaní nepodarí (nedostupná URL, príliš veľká...), sa jednoducho
vynechá - nezastaví import ostatných polí ani ostatných ponúk.
Kategória
U nás "N izbový byt" nie je parameter, ale podkategória bytu. Poradie, podľa ktorého sa kategória
určuje (prvé, ktoré vie rozhodnúť, vyhráva):
disposition (bez ohľadu na type/subtype) - česká dispozícia (1+kk, 2+1...). Počet izieb =
číslo PRED "+" (kuchyňa v "+kk" aj samostatná kuchyňa v "+1" sa NEPOČÍTA - "2+kk" aj "2+1" sú obe
2 izbový byt), 6 a viac izieb aj "atypický" idú do 5 a viac izbový byt.
rooms - slovenský spôsob, obyčajné celé číslo izieb (rovnaká podkategória ako vyššie).
category - explicitný kód z číselníka Nehnuteľností.sk/United Classifieds (napr. 61 = Skladový
objekt, 20 = Domy, 30 = Pozemok pre rod. domy...). Vhodné pre domy, pozemky, komerčné priestory a
všetko, kde dispozícia/rooms nedáva zmysel. Zoznam kódov vám na požiadanie poskytneme (interný
číselník, ešte nemá verejnú stránku - plánovaný /api/v2/codelists/category).
- Bez všetkého vyššie (pozemky, objekty bez dispozície) sa kategória hľadá podľa
type:subtype (malá
predvolená mapa pre bežné pozemkové podtypy). Neznámy type:subtype čaká na priradenie v admine
(nie je to chyba importu) - ponuka sa uloží SKRYTÁ, po priradení sa doplní a zverejní sama.
Lokalita
Slovensko (address.country=SK) - obec (address.city, voliteľne spresnená address.district) sa
hľadá v existujúcom strome obcí SR podľa mena. Nájde sa presne jedna zhoda = ponuka sa zverejní hneď.
Viac zhodných mien bez district (alebo úplne neznáma obec) = ponuka sa uloží skrytá, čaká na
priradenie v admine (nie je to chyba) - presne rovnaké správanie ako pri type backOFFICE/Zoznam realít.
Zahraničie - mesto (prednostne city_part, inak city) sa hľadá v existujúcom strome danej krajiny
(podľa ISO kódu z address.country) - ak ho krajina/kraj/mesto ešte nemá, založí sa hneď (žiadne
čakanie na admina), ponuka sa zverejní. Admin vidí všetko automaticky založené v Nastavenia -> Real
estate -> Zahraničné lokality a v dennom súhrnnom e-maile. Súradnice ponuky sa uložia PRESNE z feedu.
Mena
Cena ostáva v mene, akú poslal zdroj (currency/price) - na webe sa ZOBRAZUJE takto. Orientačný
prepočet na eurá (podľa denného kurzu ECB) sa dopočíta len pre filter/radenie a text "≈ X €" - nemení sa
tým zobrazená cena.
Mapovanie hodnôt (orientačné, dopĺňa sa podľa toho, čo zdroj reálne posiela)
-
building_type -> materiál: brick→tehla, panel→panel, skeleton→skelet, concrete→železobetón,
block→tvárnice/blok, wood→drevo, mixed→zmiešaná, stone→kameň, other→iný.
-
building_condition -> stav: new→novostavba, very_good/good→pôvodný stav,
after_reconstruction→kompletná rekonštrukcia, partial_reconstruction→čiastočná rekonštrukcia,
under_construction→vo výstavbe, project→developerský projekt, needs_reconstruction→pôvodný stav,
for_demolition→na demoláciu.
-
ownership -> vlastníctvo: personal→osobné, cooperative→družstevné, company→firemné, other→iné.
-
furnished -> zariadenie: yes→kompletne zariadený, no→nezariadený.
-
heating_systems.heating_system[] -> kúrenie (číselník Nehnuteľnosti.sk, pole heating_system[]; opakovaním elementu pošlete viac hodnôt):
| Kód |
Kúrenie |
717 |
ústredné |
722 |
podlahové |
723 |
lokálne |
728 |
iné |
729 |
krb |
730 |
klimatizácia |
732 |
žiariče |
30739 |
nedostupné (bez kúrenia) |
Neznáma hodnota v týchto poliach sa jednoducho nevyplní (parameter ostane prázdny) - nie je to chyba
importu. Mapovanie sa dopĺňa podľa reálnych hodnôt, ktoré zdroj posiela - napíšte nám, ak vaša hodnota
chýba.
Príklad - slovenský byt
<listing>
<id>sk-byt-001</id>
<status>active</status>
<transaction>sale</transaction>
<type>apartment</type>
<rooms>3</rooms>
<title><![CDATA[3-izbový byt po rekonštrukcii]]></title>
<description><![CDATA[...]]></description>
<price>185000</price>
<currency>EUR</currency>
<usable_area>72.5</usable_area>
<floor>4</floor>
<total_floors>6</total_floors>
<building_condition>after_reconstruction</building_condition>
<ownership>personal</ownership>
<energy_class>B</energy_class>
<address>
<country>SK</country>
<city>Trnava</city>
</address>
<images>
<image order="1" kind="photo" main="true"><url>https://realitka.sk/foto/byt1-1.jpg</url></image>
</images>
<broker>
<name>Jana Nováková</name>
<email>jana@realitka.sk</email>
<phone>+421 900 123 456</phone>
</broker>
</listing>
Kompletný vzorový súbor (SK byt, SK dom, SK pozemok, zahraničná ponuka) - bydo-xml-vzor.xml,
XSD schéma na overenie - bydo-xml.xsd.
Napojenie v administrácii
Nastavenia -> Napojenia -> Nové napojenie -> typ XML súbor (jednoduchý formát) ->
- URL súboru - jedna povinná adresa, odkiaľ si súbor stiahneme.
- Používateľ / Heslo (voliteľné) - ak súbor vyžaduje HTTP Basic Auth. Bez neho musí byť súbor na danej
URL verejne dostupný (bez prístupových údajov v URL - tie presunúť do tu dostupných polí).
Frekvencia stiahnutia - podľa nastavenia napojenia (predvolene niekoľko hodín, dá sa aj kratšie);
tlačidlom "Spustiť teraz" v admine viete stiahnutie vyvolať okamžite.
Zrušenie ponuky - buď úplne vynechajte <listing> zo súboru, alebo nastavte iný status
(napr. sold) - oboje vedie k rovnakému výsledku (skrytie/archivácia podľa nastavenia missing_mode).