Glovato XML 1.0 – technická specifikace feedu

1. Základní princip

Každá nabídka musí mít stabilní external_id. Tato hodnota je hlavním klíčem pro rozpoznání, zda jde o nový inzerát nebo aktualizaci existujícího záznamu.

GlovatoReal si vlastní interní ID a veřejný URL slug generuje samo. Pole jako interní databázové ID, slug, statistiky zobrazení nebo interní stav scrapingu se do externího feedu neposílají.

Pro dodavatele CRM je důležitý veřejný integrační formát, nikoli 1:1 kopie interní databáze GlovatoReal.

2. Kořenová struktura feedu

Feed obsahuje identifikaci poskytovatele a seznam nabídek. Atribut version určuje verzi této specifikace.

<?xml version="1.0" encoding="UTF-8"?>
<glovato_feed version="1.0" generated_at="2026-08-19T07:00:00+02:00">
    <provider>
        <name>Nazev CRM</name>
        <provider_id>nazev-crm</provider_id>
        <feed_type>full</feed_type>
    </provider>

    <offers>
        <offer>
            ...
        </offer>
    </offers>
</glovato_feed>

Prvek	Hodnoty	Význam
`provider/name`	text	Název dodavatele systému nebo zdroje feedu.
`provider/provider_id`	stabilní textový identifikátor	Např. `poski`, `softreal` nebo interní dohodnuté označení.
`provider/feed_type`	`full` / `delta`	Úplný snapshot nebo pouze změnový feed.
`generated_at`	ISO 8601	Čas vygenerování feedu včetně časové zóny.

3. Povinná a klíčová pole nabídky

Pole	Požadavek	Typ	Význam
`external_id`	ano	string	Stabilní jedinečné ID nabídky v rámci zdroje. Nesmí se změnit při běžné aktualizaci.
`status`	ano	active \| inactive	Určuje, zda má být nabídka zveřejněna, nebo skryta.
`transaction_type`	ano	sale \| rent	Prodej nebo pronájem.
`property_type`	ano	číselník	Např. flat, house, land, commercial, garage, cottage, other.
`title`	ano	string	Titulek nabídky.
`description`	ano	string / CDATA	Text nabídky v UTF-8. HTML lze po dohodě sanitizovat.
`price`	ano*	decimal	Cena bez oddělovačů tisíců. *Pokud je cena na dotaz, použije se price_on_request=1.
`location/city`	ano	string	Alespoň obec/město nebo jednoznačný text lokality.
`images/image`	doporučeno	HTTPS URL	Alespoň jedna fotografie je silně doporučena.

Cena na vyžádání

Pokud kancelář cenu nezveřejňuje, použijte <price_on_request>1</price_on_request>. V takovém případě může být price vynecháno nebo nastaveno na 0 podle dohodnutého mapování.

4. Doporučená a volitelná pole

Pole	Formát	Poznámka
`currency`	CZK	ISO 4217. Pokud chybí, použije se CZK.
`price_on_request`	0 \| 1	1 = cena na vyžádání.
`price_note`	string	Např. „včetně provize“ nebo doplňující podmínky nájmu.
`disposition`	string	Např. 1+kk, 2+1, 4+kk.
`usable_area_m2`	decimal	Užitná plocha.
`floor_area_m2`	decimal	Podlahová plocha.
`land_area_m2`	decimal	Plocha pozemku.
`energy_class`	A–G	Energetická třída.
`latitude / longitude`	decimal	GPS v desetinných stupních.
`source_url`	HTTPS URL	Detail nabídky na webu kanceláře.
`updated_at`	ISO 8601	Datum a čas poslední změny.
`business_status`	available \| reserved \| sold \| rented	Volitelný obchodní stav; mapování se dohodne při integraci.
`video_url`	HTTPS URL	Video nebo virtuální prohlídka.

5. Realitní kancelář a makléř

Pokud jeden dodavatelský feed obsahuje nabídky více realitních kanceláří, musí být u každé nabídky možné jednoznačně určit, komu patří. Doporučený formát:

<agency>
    <external_id>RK-00427</external_id>
    <name>Ukázková reality s.r.o.</name>
    <ico>12345678</ico>
    <website>https://www.ukazkova-reality.cz</website>
    <email>info@ukazkova-reality.cz</email>
    <phone>+420777123456</phone>
    <logo_url>https://www.ukazkova-reality.cz/logo.png</logo_url>
</agency>

<agent>
    <external_id>AG-105</external_id>
    <name>Jan Novák</name>
    <email>jan.novak@ukazkova-reality.cz</email>
    <phone>+420777654321</phone>
    <photo_url>https://www.ukazkova-reality.cz/makleri/jan-novak.jpg</photo_url>
</agent>

Upozornění: ID kanceláře a makléře v externím CRM nejsou interní ID GlovatoReal. Glovato je při prvním napojení namapuje na vlastní záznamy.

6. Fotografie a média

Fotografie posílejte jako veřejně dostupné HTTPS URL. Doporučujeme zachovat původní rozlišení a stabilní URL po celou dobu, kdy je nabídka aktivní.

<images>
    <image>
        <url>https://www.example.cz/images/12345/01.jpg</url>
        <order>1</order>
    </image>
    <image>
        <url>https://www.example.cz/images/12345/02.jpg</url>
        <order>2</order>
    </image>
</images>

<video_url>https://www.youtube.com/watch?v=example</video_url>

Pokud váš stávající feed používá fotografie jako opakovaný jednoduchý element URL, není nutné strukturu měnit – mapování lze dohodnout.

7. Pravidla synchronizace

Nová nabídka

Neznámé external_id → vytvoření nové nabídky po úspěšné validaci a mapování partnera.

Aktualizace

Stejné external_id → aktualizace ceny, textu, parametrů, médií a dalších změněných údajů.

Skrytí

status=inactive → nabídka se přestane veřejně zobrazovat, ale její identita zůstává zachována.

Znovu aktivní

Stejné external_id se stavem active lze znovu zveřejnit, pokud je to součást dohodnutého workflow.

Úplný feed (`full`)

Úplný feed reprezentuje aktuální kompletní sadu nabídek daného zdroje. Nabídky explicitně označené inactive se skryjí. O zacházení s nabídkou, která z feedu zmizí úplně, se rozhodne při integraci; automatické skrytí se smí provést pouze po úspěšném kompletním načtení, nikoli po chybě nebo neúplném feedu.

Přírůstkový feed (`delta`)

Chybějící nabídka nic neznamená. Pro ukončení inzerce musí feed poslat konkrétní záznam s původním external_id a stavem inactive.

8. Základní číselníky

`transaction_type`

Hodnota	Význam
`sale`	prodej
`rent`	pronájem

`property_type`

Hodnota	Význam
`flat`	byt
`house`	dům
`land`	pozemek
`commercial`	komerční nemovitost
`garage`	garáž / parkovací objekt
`cottage`	chata / chalupa / rekreační objekt
`other`	ostatní

Pokud váš systém používá jiné hodnoty nebo podrobnější kategorie, neposílejte data násilně pod špatný typ. Při integraci vytvoříme mapovací tabulku.

`status`

Hodnota	Význam
`active`	nabídka je určena ke zveřejnění
`inactive`	nabídka se má skrýt / dále neinzerovat

9. Formát souboru a přenos

Kódování: UTF-8.
Preferovaný přenos: veřejná nebo dohodnutým způsobem chráněná HTTPS URL.
XML musí být syntakticky validní a správně escapovat znaky &, <, >.
Časy: ISO 8601 včetně časové zóny, např. 2026-08-19T07:00:00+02:00.
Desetinná čísla: tečka jako desetinný oddělovač, bez mezer a oddělovačů tisíců.
Měna: ISO 4217; pokud není uvedena, očekává se CZK.
URL médií: absolutní HTTPS URL bez dočasných session parametrů, pokud je to možné.

10. Máte vlastní XML formát? Použijte ho.

Glovato XML 1.0 je referenční formát. Dodavatel realitního systému nemusí vytvářet nový export, pokud již disponuje stabilním XML feedem obsahujícím potřebná data.

Pro integraci stačí poskytnout dokumentaci nebo testovací vzorek. Společně určíme mapování vašeho ID, typů transakcí, kategorií, stavů, kanceláří, makléřů a médií na GlovatoReal.

11. Ukázka a XSD validace

Pro první implementaci jsou k dispozici dva soubory:

glovato_feed_example.xml glovato_feed_schema.xsd

XSD ověřuje základní strukturu a typy dat. Obchodní pravidla, vztahy mezi poli a mapování číselníků se kontrolují při importu a při integračním testu.

Verzování: tato stránka popisuje Glovato XML 1.0. Případné budoucí rozšíření bude navrženo tak, aby byla zachována zpětná kompatibilita, nebo dostane nové číslo verze.

Technická specifikace XML feedu