Specifikace importního rozhraní www.ceskereality.cz - verze 3.0


Tento soubor je dostupný na adrese: https://import.ceskereality.cz/specifikace/


Obsah



Changelog

verze: 2019-04-01 - zveřejnění specifikace 3.0

verze: 2019-05-14 - zapracována kontrola zasílané velikosti fotografie makléře - požádována je fotografie o minimální velikosti 200 bodů na kratší straně

Změny oproti starému rozhraní 2.0 ...

Výhody přechodu na novou verzi 3.0

Chci nově exportovat

V případě nového exportéra kontaktujte nejprve technickou podporu podpora@ceskereality.cz pro přidělení přihlašovacích údajů (CLIENT_ID a CLIENT_SECRET) a doporučené nastavení povolených IP adres exportních serverů.
Na žádost poskytujeme také testovací účet pro ověření vašeho exportního softwaru. Nabízíme exportérům možnost uveřejnění odkazu na našich stránkách.

Všechna vstupní data a výstupy jsou poskytovány/požadovány v kódování UTF-8. Výstupy jsou ve formátu JSON.

V případě jakýchkoliv dotazů či připomínek prosím kontaktujte naši technickou podporu podpora@ceskereality.cz.



Použité názvosloví



Odpovědi serveru

Serveru vrací všechny odpovědi v poli ve formátu JSON (kódování UTF-8).

Příklad:
{
    "ceskereality": {
        "status": "success",
        "code": "200",
        "message": "import_OK",
        "details": "import nemovitosti proběhl v pořádku",
        "id_inzeratu": "12455"
    }
}

Význam položek:

Doplňující položky: Kompletní přehled výstupů naleznete zde.

Postup exportu a popis volání

Pomocí autorizačního skriptu požádá exportér na základě svých přihlašovacích údajů (CLIENT_ID a CLIENT_SECRET) o přidělení přístupového tokenu (access_token) k exportu zakázek. Token je platný jednu hodinu. Poté je nutné požádat o přidělení nového tokenu.

Následně si exportér stáhne pomocí skriptu výpis RK seznam realitních kanceláří, které mu udělily právo k exportu zakázek na realitní server www.ceskereality.cz. Právo k exportu zakázek pomocí konkrétního exportního programu si přiděluje RK ve své servisní sekci, případně může na požádání nastavit i pracovník podpory realitního server www.ceskereality.cz. RK obdrží jedinečný pin_exportu, který vloží do svého realitního software.
Na základě údaje pin_exportu z výpisu RK napáruje exportér seznam svých RK v systému s výpisem povolených RK k exportu dat. Zároveň získá hodnotu id_firmy, kterou používá v dalších skriptech.

V dalším kroku exportér pomocí skriptu výpis nemovitostí RK vypíše seznam nemovitostí konkretní RK na realitním serveru www.ceskereality.cz. Porovná položky id_inzeratu a datum poslední změny inzerátu (last_access) ve výpisu s výpisem zakázek RK ve svém realitním software. Nové zakázky nahraje pomocí skriptu upload datového souboru a fotografií na server www.ceskereality.cz - XML s daty, fotografie inzerátu a makléře, PDF soubory u dražeb. Vlastní import nemovitosti do databáze, po nahrání všech souborů, spustí exportér pomocí importního skriptu. Změněné zakázky (dle položky last_access) aktualizuje exportér stejným způsobem. Neexistující zakázky v systému exportéra (dle id_inzeratu) exportér vymaže ze serveru www.ceskereality.cz.
Tímto postupem bude stav zakázek v realitním programu exportéra a na serveru www.ceskereality.cz vždy konzistentní.

Pomocí výpisu konkretního inzerátu lze zkontrolovat uspěšnost importu zakázky na server včetně kontroly existence všech fotografií. Zároveň exportér získá ve vyýpisu i URL nemovitosti na serveru www.ceskereality.cz.

Postup opakuje exportér pro všechny povolené RK.


1) Autorizace

Importní rozhraní využívá protokol (https://oauth.net/2/), používaný např. Facebookem, Googlem, Windows Live ID. Exportér musí na své straně zprovoznit aplikaci pro komunikaci s API.

Ukázka řešení klienta (PHP)

Upravené zdrové kódy lze stáhnout na adrese https://gitlab.ci.cz/ceskyinternet/OAuth2Token nebo přímo v komprimovaném souboru (přímý odkaz).
Stažený archiv rozbalíte na serveru do webového adresáře. V souboru index.php upravite parametry CLIENT_ID a CLIENT_SECRET za hodnoty získané při registraci.
Voláním skriptu získáte access_token pro použití v dalších skriptech (příklady jednotlivých skriptů naleznete ve staženém komprimovaném souboru ve složce examples).

Odpověď ve formátu JSON:

{                  
	"ceskereality": {
		"code": 222,
		"access_token": "9287c2acc6e3ecac835198020720927706510ff9",
		"expires_in": 3600,
	}
}

Význam položek:

Chybový výstup
neplatné CLIENT_ID či CLIENT_SECRET při žádosti o access token
{
	"ceskereality": {
		"status": "error",
		"code"": 400,
		"message": "invalid_client",
		"details": "The client credentials are invalid"
	}
}
export z nepovolené IP adresy, exportér využívá doporučené bezpečnostní omezení exportu pouze z registrovaných IP adres, kontaktujte podporu
    {
    "ceskereality": {
        "0": {
            "status": "error",
            "code": "404",
            "message": "invalid_ip",
            "details": "export z nepovolené IP adresy, exportér využívá doporučené bezpečnostní omezení exportu pouze z registrovaných IP adres, kontaktujte podporu"
        },
        "ip_adresa": "3.228.21.204"
    }
}


2) Výpis seznamu realitních kanceláří

Výpis seznamu všech realitních kanceláří, u kterých má exportér povoleno exportovat nemovitosti. Příklad skriptu naleznete v balíku s ukázkovým PHP klientem (soubor rk.php ve složce examples).

Volané URL: https://import.ceskereality.cz/rk.html

Odpověď ve formátu JSON:

{
    "ceskereality": [
        {
            "id_firmy": "202333",
            "pin_exportu": "4616168138764",
            "nazev": "Testovací RK",
            "ico": "123456789",
            "ulice": "Kostelní 942\/46",
            "mesto": "České Budějovice",
            "psc": "37004",
            "telefon": "",
            "email": "test@ceskereality.cz",
            "www": "",
            "registrace_do": "2030-01-01 00:00:00"
        },
        {
            "id_firmy": "201482",
            "pin_exportu": "86761364654684",            
            "nazev": "Testovací RK2",
            "ico": "",
            "ulice": "Kostelní 46",
            "mesto": "České Budějovice",
            "psc": "0",
            "telefon": "",
            "email": "testovani@ceskereality.cz",
            "www": "",
            "registrace_do": "2030-01-01 00:00:00"
        },
    ]
}

Význam položek:

Chybový výstup
The access token provided is invalid - vypršela platnost access tokenu, požádejte o nový access token)
    {
    "ceskereality": [
        {
            "status": "error",
            "code": "401",
            "message": "invalid_token",
            "details": "The access token provided is invalid"
        }
    ]
}      


3) Výpis nemovitostí RK

Vypíše seznam nemovitostí konkrétní realitní kanceláře dle parametru id_firmy z předchozího dotazu. Příklad skriptu naleznete v balíku s ukázkovým PHP klientem (soubor vypis_nemovitosti.php ve složce examples).

Volané URL: https://import.ceskereality.cz/vypis_nemovitosti.html?id_firmy=202333

Odpověď ve formátu JSON:

{
    "ceskereality": [
        {
            "id_inzeratu": "5678",
            "last_access": "2019-01-25 12:14:13"
        },
        {
            "id_inzeratu": "5552",
            "last_access": "2019-01-29 10:10:03"
        },
        {
            "id_inzeratu": "5515",
            "last_access": "2019-01-22 09:15:44"
        },
        {
            "id_inzeratu": "5349",
            "last_access": "2019-01-25 13:48:45"
        }
    ]
}

Význam položek:

Chybový výstup
chybějící nebo neplatné id_firmy, nemáte právo k exportu dat příslušné realitní kanceláře
    {
    "ceskereality": [
        {
            "status": "error",
            "code": "430",
            "message": "invalid_id_firmy",
            "details": "chybějící nebo neplatné id_firmy, nemáte právo k exportu dat příslušné realitní kanceláře"
        }
    ]
}      

U dotazu je možné použít volitelný parametr id_inzeratu ... vypisuje data pouze jedné konkrétní dotazované nemovitosti.

Volané URL: https://import.ceskereality.cz/vypis_nemovitosti.html?id_firmy=202333&id_inzeratu=2983002

Odpověď ve formátu JSON:

{
    "ceskereality": [
        {
            "id_inzeratu": "5678",
            "last_access": "2019-01-25 12:14:13",
            "makler_int_id": "15477",
            "foto1": "8a6f67f4649bc6ef6f8ca51723c4b635.jpg",
            "foto2": "89094fe83bb3f43eaa572e06149312d4.jpg",
            "foto3": "d1e550ad86c5350e670407b9a1d6b9c6.jpg",
            "foto4": "dedc4e0c5fa1187af6f18e1c741f5588.jpg",
            "foto5": "be0e25da52a2cf196bc56ac70ee0fa4e.jpg",
            "url_inzeratu": "https:\/\/www.ceskereality.cz\/nemovitost.html?pid=2151645689",
        }
    ]
}

Význam položek:

Chybový výstup
neplatné nebo neexistující id_inzeratu
    {
    "ceskereality": [
        {
            "status": "error",
            "code": "440",
            "message": "invalid_id_inzeratu",
            "details": "neplatné nebo neexistující id_inzeratu",
            "id_inzeratu": "2983002"
        }
    ]
}      


4) Upload datového souboru a fotografií

Nahrání datového souboru ve formátu xml (bez komprese), fotografií ve formátu jpg, případně souborů k dražbám ve formátu pdf (používejte malá písmena v koncovkách souborů).
Příklad skriptu naleznete v balíku s ukázkovým PHP klientem (soubor uloz_xml.php ve složce examples).

Volané URL: https://import.ceskereality.cz/uloz_xml.html?id_firmy=202333

Název XML souboru je "nemovitosti.xml". Povolené kódování souboru je utf-8. Chybová hlášení a výstupy jsou vraceny taktéž v kódování utf-8.
Název souborů fotografií představuje MD5 sumu s koncovkou ".jpg" (md5 je možné vygenerovat z libovolného jedinečnéhu údaje), stejný hash je použit i v datovém souboru v poli <foto id="...

Skript uloz_xml.html voláte tolikrát, kolik souborů posíláte (fotografie, PDF, XML). Doporučujeme posílat soubory v tomto pořadí, tj. nejprve fotografie, PDF soubory a nakonec XML soubor "nemovitosti.xml".
Po uploadu všech souborů na server spouštíte následující skript - import_xml.html - pro vlastní import dat do databáze.

Odpověď ve formátu JSON:

{
    "ceskereality": [
        {
            "status": "success",
            "code": "201",
            "message": "upload_OK",
            "details": "nahrání souboru proběhlo v pořádku"
        }
    ]
}

Chybový výstup
chybný typ souboru, podporované formáty: XML,JPG,PDF
    {
    "ceskereality": [
        {
            "status": "error",
            "code": "450",
            "message": "invalid_filetype",
            "details": "chybný typ souboru, podporované formáty: XML,JPG,PDF"
        }
    ]
}      


5) Import dat do databáze

Spuštění importu XML souboru do databáze. Voláme až po nahrání všech souborů (xml, fotografií ve formátu jpg, souborů pdf).
Příklad skriptu naleznete v balíku s ukázkovým PHP klientem (soubor import_xml.php ve složce examples).

Volané URL: https://import.ceskereality.cz/import_xml.html?id_firmy=202333

!!! Po importu nemovitosti na server trvá cca. 20 minut, než se nemovitost plně zobrazí na webu !!! (v tomto čase probíhá generování náhledu fotografií, kontroly dat, dopočítávání polohy apod).

Odpověď ve formátu JSON:

Export proběhl v pořáku. Byly nahrány všechny fotografie.
{
    "ceskereality": [
        {
            "status": "success",
            "code": 200,
            "message": "import_OK",
            "details": "import nemovitosti proběhl v pořádku",
            "id_inzeratu": 3234
            "url_inzeratu": "https:\/\/www.ceskereality.cz\/nemovitost.html?pid=2151836306"
        }
    ]
}


Export proběhl v pořádku. U nemovitosti s ID 3234 nebyla nahrána fotografie 88b29514ebc306baeff8f33b5ffdc563.jpg. Fotografie nebyla ani nalezena na serveru z předchozích exportů. Prosím nahrajte fotografii a opakujte export.
{
    "ceskereality": [
        {
            "status": "warning",
            "code": 300,
            "message": "missing_foto",
            "details": "chybějící fotografie",
            "id_inzeratu": 3234,
            "id_foto": "88b29514ebc306baeff8f33b5ffdc563.jpg"
        },
        {
            "status": "success",
            "code": 200,
            "message": "import_OK",
            "details": "import nemovitosti proběhl v pořádku",
            "id_inzeratu": 3234
            "url_inzeratu": "https:\/\/www.ceskereality.cz\/nemovitost.html?pid=2151836306"
        }
    ]
}

Export proběhl v pořádku. Realitní kancelář je na serveru ceskereality.cz blokovaná. Nemovitost nebude na serveru zobrazena! Kontaktujte obchodní oddělení Českých realit nebo technickou podporu na podpora@ceskereality.cz.
{
    "ceskereality": [
        {
            "status": "warning",
            "code": 333,
            "message": "blokovana_RK",
            "details": "realitní kancelář je blokovaná, kontaktujte podporu serveru na podpora@ceskereality.cz"
        },
        {
            "status": "success",
            "code": 200,
            "message": "import_OK",
            "details": "import nemovitosti proběhl v pořádku",
            "id_inzeratu": 3234
            "url_inzeratu": "https:\/\/www.ceskereality.cz\/nemovitost.html?pid=2151836306"
        }
    ]
}

Chybový výstup
na serveru není nahrán XML soubor nemovitosti.xml
    {
    "ceskereality": [
        {
            "status": "error",
            "code": "470",
            "message": "invalid_xml",
            "details": "na serveru není nahrán XML soubor nemovitosti.xml"
        }
    ]
}      
nahraný XML soubor nemovitosti.xml není validní
    {
    "ceskereality": [
        {
            "status": "error",
            "code": "471",
            "message": "invalid_xml_file",
            "details": "nahraný XML soubor nemovitosti.xml není validní"
        }
    ]
}      
neplatná nebo chybějící položka XXX v exportním XML
    {
    "ceskereality": [
        {
            "status": "error",
            "code": "480",
            "message": "invalid_item",
            "details": "neplatná nebo chybějící položka XXX v exportním XML"
        }
    ]
}      


Popis formátu XML dokumentu

Notace: <tag>, @atribut

<xreal> -- hlavní tag (XML Reality).

<identifikace> -- identifikátor autora souboru
@typ -- CLIENT | SERVER

<datumcas> -- datum a čas vzniku souboru ve formátu RRRR-MM-DD-HH-MI-SS
<autorizace> @id_firmy -- id_firmy - ID realitní kanceláře získané pomocí výpisu skriptu 2)

<nabidky> -- seznam nabídek
@nahrada -- hodnota "t" znamená nahradit všechny existující nabídky

<nabidka> -- nabídka, v XML souboru je možné poslat všechny nabídky hromadně, doporučujeme ale nemovitosti exportovat po jedné z důvodu lepšího trasování neplatných exportů a chyb zasílaných dat
@id -- ID číslo nabídky
@operace -- operace = "U" nebo "D" nebo "I" (Update/Insert/Delete)

Pokud se provádí 'I'nsert dat s již existujícím ID, provede se akce 'U'pdate - dojde k přemazání původních hodnot. Pokud nabídka na serveru neexistuje a použije se 'U'pdate není to chybou a nabídka bude přidána. Doporučujeme používat 'U'pdate.

<pole> -- pole s informacemi o nabídce
@id -- identifikátor pole
Možné položky <pole>:
název typ poznámky
cislo char(20) interní označeni kódu nemovitosti v realitním programu RK - povinné
operace tinyint unsigned viz. číselník, povinné
subtyp_n smallint unsigned viz. číselník, povinné
ruian_uroven tinyint(3) unsigned RUIAN úroveň, viz info níže, povinné
ruian_kod int(10) unsigned RUIAN kód polohy nemovitosti, viz info níže, povinné
obec char(255) plné textové jméno obce,povinné pokud neposíláte RUIAN, export aktuálních položek DB, je možné doplnit o název části obce(např. "České Budějovice - sídliště Šumava")
obec_kod mediumint(8) unsigned kód jména obce, povinné pokud neposíláte RUIAN, export aktuálních položek DB
obec_cast_kod mediumint(8) unsigned kód části obce obce, povinné pokud neposíláte RUIAN, export aktuálních položek DB
kod_spravnihoob_pha smallint(5) unsigned kód správního obvodu Hl. města Prahy (Praha 1-22) dle číselníku, povinné u pražských nemovitostí pokud neposíláte RUIAN, export aktuálních položek DB
kod_uzemniob_pha smallint(5) unsigned kód územního obvodu Hl. města Prahy (Praha 1-10), povinné u pražských nemovitostí pokud neposíláte RUIAN, export aktuálních položek DB
ulice char(255) jméno ulice/čtvrti nemovitosti
cp char(50) číslo popisné
co char(50) číslo orientační
gps_lat double GPS souřadnice nemovitosti - Latitude (Decimal degrees), např. 50.41515246, zaokrouhleno na 8 desetiných míst, (ukázka převodu WGS na DD)
gps_lon double GPS souřadnice nemovitosti - Longitude (Decimal degrees), např. 14.25153254, zaokrouhleno na 8 desetiných míst, (ukázka převodu WGS na DD)
zeme smallint(3) unsigned kód země (kod_n3), povinné, (u nemovitostí ležících mimo ČR povinnou položku obec_kod a obec_cast_kod vyplňte kódem 0), export aktuálních položek DB
nezverejnovat_polohu tinyint(3) unsigned nezveřejňovat přesnou polohu nemovitosti, viz. číselník
poloha_domu tinyint(4) poloha domu v zástavě, viz. číselník
poloha tinyint viz. číselník
stav_n tinyint stav nemovitosti, viz. číselník, povinné u typů Byty, Domy, Komerční, Ostatní
popisek varchar(200) krátký popis základních vlastností nemovitosti, maximální délka je 200 znaků
popis text textový popis nemovitosti, maximální délka je 5000 znaků, povinné
cena int unsigned cena nemovitosti, povinné
mena tinyint(3) unsigned měna, viz. číselník, povinné
typceny_n tinyint(3) unsigned viz. číselník, povinné
cena_neuvadet tinyint(3) unsigned neuvádět cenu na webu - hodnota 1
poznamkakcene char(255) textová informace k ceně (např. cena k jednání)
podrobnosti text položka sestavená z nul a jedniček, každá nula či jednička znamená jednu položku v poli, zde se navíc od sebe ještě oddělují sekce mezerou, viz. příklad, číselník
tech_popis text textová položka upřesňující technické vybavení nemovitosti v případě neexistence odpovídajících položek, max. 1000 znaků, (např. střecha skleněná, podlaha modřínová)
video varchar(20) ID videa na youtube.com, napr. eCGsrzyv5u (kontrola na délku řetězce - 11 znaků)
prohlidka3d varchar(70) ID 3D prohlídky nemovitostí (např. XWHKG8fuFBj). Podporované formáty v číselníku prohlidka3d_typ.
prohlidka3d_typ tinyint(4) typ 3D prohlídky nemovitostí. Podporované formáty viz. číselník, povinné v případě odeslání položky prohlidka3d
pl_celkova mediumint unsigned celková plocha nemovitosti v metrech
pl_zastavena mediumint unsigned zastavěná plocha v metrech
pl_obytna mediumint unsigned obytná plocha v metrech
pl_podlahova mediumint unsigned podlahová plocha v metrech
pl_uzitna mediumint unsigned užitná plocha v metrech, povinné u typu domy, byty, chaty, chalupy, komerční a ostatní
pl_vyrobni mediumint unsigned výrobní plocha v metrech
pl_nebytova mediumint unsigned nebytová plocha v metrech
pl_sklepu mediumint unsigned plocha sklepu v metrech
pl_sklad mediumint unsigned plocha skladu v metrech
pl_terasy mediumint unsigned plocha terasy v metrech
pl_balkonu mediumint unsigned plocha balkonu v metrech
pl_lodzie mediumint unsigned plocha lodžie v metrech
pl_pozemku mediumint unsigned plocha pozemku nemovitosti v metrech, povinné u typu pozemek a dům
pl_obchodni mediumint unsigned plocha obchodních prostor v metrech
typ_domu int(2) typ domu, viz. číselník, povinné u typu dům
podlazi_n char(50) počet nadzemních podlaží
podlazi_p char(50) počet podzemních podlaží
mistnosti char(50) počet místností (např. 4 + kuchyň, příslušenství, komora)
pocet_garazi tinyint(3) unsigned počet garáží
bytu char(50) počet bytů (např. 2x 2+1, 3x 4+1)
volnychbytu char(50) počet volných bytů (např. 2 ihned, zbylé do konce roku)
vyska_stropu double výška stropu v metrech
pocet_sklepu tinyint(3) unsigned počet sklepů
rok_vystavby char(4) rok výstavby nemovitosti (např. 2001)
en_trida varchar(1) třída energetické náročnosti budovy (A-G), hodnotu "X" lze posílat u nemovitostí, kde ze zákona není nutno údaj uvádět (např. z důvodu stáří budovy)
en_hodnota smallint(6) energetická náročnost budovy (v kWh/m2)
en_vyhlaska int(1) unsigned podle jaké vyhlášky je uvedena energetická náročnost budovy - defaultní hodnota je 0 dle vyhlášky 148/2007 Sb., 1 dle novelizace ...
posl_rekonstrukce char(50) rok poslední rekonstrukce nemovitosti (např. 2001 kuchyň, 2003 příslušenství, ...)
parkoviste_aut smallint počet parkovacích míst
prum_kat_bytu char(50) průměrná kategorie bytu (např. 1x byt 1. kategorie, 3x byt 3. kategorie)
patro char(50) patro nemovitosti (např. zvýšené přízemí)
patro_cislo int patro nemovitosti v číselné podobě, povinné u typu byt
najem char(50) výše nájmu (např. nájem 5000,- Kč /měsic plus 2000,- Kč /měsíc služby)
vytah tinyint unsigned výtah, nabývá hodnot 1/0 (ano či ne)
bezbarier tinyint unsigned bezbariérový přístup, nabývá hodnot 1/0 (ano či ne)
anuita char(50) aniuta nemovitosti
vlastnictvi tinyint unsigned viz. číselník, povinné u typu byt
typ_smlouvy tinyint unsigned viz. číselník
status tinyint unsigned stav prodeje nemovitosti - REZERVOVÁNO, PRODÁNO číselník
makler_int_id int(10) ID makléře ve Vašem interním realitním SW (umožňuje rozlišení makléřů), povinné
makler_login varchar(50) interní email makléře, sloužící k přihlášení do servisni sekce, položka se nezobrazuje na webu !!!
makler_jmeno varchar(50) jméno makléře zajišťující prodej nemovitosti
makler_telp varchar(30) telefon (pevná linka) makléře zajišťující prodej nemovitosti
makler_telm varchar(30) telefon (mobil) makléře zajišťující prodej nemovitosti
makler_info varchar(255) rozšiřující informace o makléři zajišťující prodej nemovitosti
makler_mail varchar(50) mail makléře zajišťující prodej nemovitosti
makler_last_change datetime datum a čas poslední změny údajů makléře
datumdrazby datetime datum dražby nemovitosti v datetime (2017-10-10 10:00:00), povinné v případě operace = 9 (dražba)
druh_drazby int(11) viz. číselník, povinné v případě operace = 9 (dražba)
misto_drazby varchar(45) místo konání dražby - textový popis, povinné v případě operace = 9 (dražba)
prohlidka1 datetime datum a čas první prohlídky v datetime (2017-10-10 10:00:00)
prohlidka2 datetime datum a čas druhé prohlídky v datetime (2017-10-10 10:00:00)
posudek_drazby varchar(45) soubor ve formátu PDF se znaleckým posudkem dražby, jméno souboru malými písmeny dle vzoru "posudek-ID_zakazky.pdf" (např. posudek-12345.pdf), povinné v případě operace = 9 (dražba)
vyhlaska_drazby varchar(45) soubor ve formátu PDF s dražební vyhláškou, jméno souboru malými písmeny dle vzoru "vyhlaska-ID_zakazky.pdf" (např. vyhlaska-12345.pdf), povinné v případě operace = 9 (dražba)
drazba_cena_odhad int(11) cenový odhad nemovitosti, povinné v případě operace = 9 (dražba)
drazba_jistina int(11) dražební jistina, povinné v případě operace = 9 (dražba)
drazba_min_prihoz int(11) minimální příhoz dražby, povinné v případě operace = 9 (dražba)
last_access datetime poslední změna v záznamu nemovitosti, např. 2005-06-03 15:18:33., povinné


Veškeré textové hodnoty omezujte na char(xx), textovou položku popis max. na 5000 znaků. Při výskytu znaku " (uvozovky) nebo znaku ' (jednoduché uvozovky) v libovolném textovém poli je nutno provést náhradu za \" případně \'
Při výskytu znaku \" (zpětné lomítko a uvozovky) v libovolném textovém poli ponechat původní stav, popřípadě provést náhradu za \\\" .
Při výskytu znaku \' (zpětné lomítko a jednouché uvozovky) v libovolném textovém poli ponechat původní stav, popřípadě provést náhradu za \\\' .
Při výskytu znaku & v libovolném textovém poli je nutno provést náhradu za &#38; .
Jakýkoliv textový řetězec po oříznutí nesmí končit zpětným lomítkem \ a proto je nutné text oříznout o jeden znak kratší a doplnit na konci mezerou, či filtrovat poslední znak a zpětné lomítko odstranit.
Jakýkoliv textový řetězec po oříznutí na max. počet znaků nesmí končit částí speciálního znaku. Např. ořez &#38; na "&#3".
Hypertextové odkazy v poli popis posílejte v této formě: &lt;a href=&quot;http://www.nekde.cz&quot;&gt;www.nekde.cz&lt;/a&gt; .

Položky posudek_drazby a vyhlaska_drazby zasílejte na server stejným způsobem jako fotografie nemovitosti - skript (uloz_xml.html) - ve formátu "Content-type: application/pdf".


<foto> -- fotografie
@id -- identifikátor (MD5 hash) fotografie, hash každé fotografie musí být pro dannou RK jedinečný v rámci všech nemovitostí, max. délka hash je 40 znaků
@popis -- komentář k fotografii

Pozor: jméno souboru fotografie v exportu musí být:<id=MD5-hash-fotografie>
Systém v současné době akceptuje maximálně 25 fotografií. Ostatní jsou ignorovány.
Minimální rozlišení je 1024x768 obr. bodů. Doporučené rozlišení je 1920x1080 obr. bodů.
Fotografie první v pořadí se na webu zobrazuje jako hlavní a současně jako náhledová u seznamů - měla by zobrazovat celkový vzhled nemovitosti.
Při zmeně fotografie je nutné změnit i identifikátor fotografie (MD5 hash) !!!


Export fotografií makléřů:
Fotky makléře zasílejte na server stejným způsobem jako fotografie nemovitosti - skript (uloz_xml.html).
Jméno souboru musí být složeno z makler_int_id a koncovky .jpg (malými písmeny).
Např.
<pole id="makler_int_id">KXB-14587</pole>
zaslaná fotografie: KXB-14587.jpg
Formát fotografií - JPG. Zasílaná velikost fotografií makléřů je minimálně 200 obr. bodů na kratší straně. Větší fotografie budou automaticky zmenšeny. Zachovávejte poměr stran.
Fotografii makléře není nutné posílat při každém exportu - stačí 1x ke každěmu makléři (případně změny). Položku makler_int_id, ... je nutno posílat vždy.
Existenci či neexistenci fotky makléře lze zjistit pomocí skriptu.



Další poznámky:


Poloha nemovitostí:
Adresu nemovitosti je možné variantně zadat podle číselníku adres RUIAN-ADR (preferovaný způsob) nebo UIR-ADR. RUIAN adresa má přednost před UIR adresou v případě zaslání obou položek. Stačí zasílat adresu jen jedním způsobem.
Adresu nemovitosti je nutno specifikovat minimálně na úrovni obce. Pro správné umístění inzerátu ve vyhledávání zasílejte adresu co nejpřesněji!!!

Způsob RUIAN (položky exportu ruian_uroven, ruian_kod)
Import na server podporuje urovně RUIAN: Více informací naleznete na stránkách http://www.ruian.cz.

Způsob UIR (položky exportu obec, obec_kod, obec_cast_kod, kod_spravnihoob_pha, kod_uzemniob_pha, ulice, cp, co)
Více informací naleznete na stránkách http://forms.mpsv.cz/uir/.

Polohu nemovitosti lze upřesnit zaslání GPS souřadnic (položky exportu gps_lat,gps_lon).
Adresu je možno v případě potřeby znepřesnit pomocí položky exportu nezverejnovat_polohu.
U zahraničních nemovitostí se posílají vyplněné pouze položky obec a zeme (povinné položky obec_kod a obec_cast_kod vyplňte kódem 0 a pošlete také).

Příklady exportu přesné polohy nemovitosti včetně komentářů:


<pole id="ruian_uroven">11</pole> //úroveň RUAIN s přesností na adresu nemovitosti
<pole id="ruian_kod">20845570</pole> //kód RUAIN
<pole id="nezverejnovat_polohu">0</pole> //zveřejnit plnou polohu nemovitosti
<pole id="zeme">203</pole> //kód země


<pole id="obec">Praha - Malá Strana</pole> //textový popis polohy - obec, popříp. část obce, zsj
<pole id="obec_kod">554782</pole> //kód obce - Praha
<pole id="kod_spravnihoob_pha">1101</pole> //kód správního obvodu - Praha 1
<pole id="kod_uzemniob_pha">019</pole> //kód územního obvodu - Praha 1
<pole id="obec_cast_kod">490121</pole> //kód části obce - Malá Strana
<pole id="zeme">203</pole> //kód země
<pole id="gps_lat">50.0885848999023</pole> //GPS souřadnice
<pole id="gps_lon">14.3979616165161</pole> //GPS souřadnice
<pole id="nezverejnovat_polohu">1</pole> //zveřejnit polohu nemovitosti bez GPS souřadnic (na mapě)

Ukázka XML souboru:

<?xml version="1.0" encoding="utf-8"?>
<xreal>
<identifikace typ="CLIENT">
<datumcas>2015-06-01-15-23-58</datumcas>
<autorizace id_firmy="202333"/>
</identifikace>
<nabidky>
<nabidka id="1" operace="D"/>
<nabidka id="2" operace="D"/>
<nabidka id="3" operace="U">
<pole id="cislo">187030</pole>
<pole id="subtyp_n">202</pole>
<pole id="ruian_uroven">11</pole>
<pole id="ruian_kod">6156860</pole>
<pole id="zeme">203</pole>
<pole id="operace">0</pole>
<pole id="nezverejnovat_polohu">0</pole>
<pole id="poloha">-1</pole>
<pole id="stav_n">1</pole>
<pole id="popis">Prodej bytu v ....</pole>
<pole id="podrobnosti">100110 0110 001000 01100 100 10000 000010 0000000 000010 000000100 000 0000 100 000 000000 000 0000000 000000000000000000 000000 0000 000</pole>
<pole id="pl_uzitna">22</pole>
<pole id="patro_cislo">4</pole>
<pole id="vlastnictvi">1</pole>
<pole id="cena">800000</pole>
<pole id="mena">1</pole>
<pole id="typceny_n">1</pole>
<pole id="last_access">2004-07-19 12:34:26</pole>
<pole id="makler_int_id">KXB-14587</pole>
<pole id="makler_jmeno">Novák Jan</pole>
<pole id="makler_telp">+420 222 222 222</pole>
<pole id="makler_telm">+420 777 777 111</pole>
<pole id="makler_info">specialista pro Prahu 6</pole>
<pole id="makler_icq">123456789012</pole>
<pole id="makler_mail">makler@ceskereality.cz</pole>
<foto id="e05f13e8d56ea51f8e9b50a4382fee3b" popis="Pohled od severu"/>
<foto id="e86cd0d457dbfa443bf12ef491f3bd58" popis="Pohled od východu"/>
</nabidka>
<nabidka id="4" operace="U">
<pole id="cislo">12345</pole> 
<pole id="subtyp_n">101</pole>
<pole id="obec">Praha - Malá Strana</pole>
<pole id="obec_kod">554782</pole>
<pole id="zeme">203</pole>
<pole id="ulice">Dlouhá</pole>
<pole id="cp">782</pole>
<pole id="kod_spravnihoob_pha">1101</pole>
<pole id="kod_uzemniob_pha">019</pole>
<pole id="obec_cast_kod">490121</pole>
<pole id="gps_lat">50.0885848999023</pole>
<pole id="gps_lon">14.3979616165161</pole>
<pole id="nezverejnovat_polohu">1</pole>
<pole id="operace">0</pole>
<pole id="stav_n">1</pole>
<pole id="cena">5800000</pole>
<pole id="mena">1</pole>
<pole id="typceny_n">1</pole>
<pole id="popis">Prodej RD v klidné čtvrti Praha...</pole>
<pole id="podrobnosti">100010 0110 001000 01000 100 00000 000010 0000100 000010 000000110 001 0000 000 000 000000 000 0000000 000000000000000000 000000 0000 000</pole>
<pole id="pl_celkova">3000</pole>
<pole id="pl_pozemku">3000</pole>
<pole id="pl_zastavena">150</pole>
<pole id="pl_uzitna">350</pole>
<pole id="podlazi_n">2</pole>
<pole id="podlazi_p">1</pole>
<pole id="poznamkakcene">informace v kancelari</pole>
<pole id="last_access">2015-05-04 15:18:33</pole>
<pole id="makler_int_id">KXB-14587</pole>
<pole id="makler_jmeno">Novák Jan</pole>
<pole id="makler_telp">+420 222 222 222</pole>
<pole id="makler_telm">+420 777 777 111</pole>
<pole id="makler_info">specialista pro Prahu 6</pole>
<pole id="makler_icq">123456789012</pole>
<pole id="makler_mail">makler@ceskereality.cz</pole>
<foto id="b905351963c5065a8b7b548bce503ca" popis="Kuchyň"/>
<foto id="c4f67744cbb9c3ec64199b11dab6f0e4" popis="Zahrada"/>
<foto id="95006a9fb4835a958483450de048ff46" popis="Bazén"/>
</nabidka>
</nabidky>
</xreal>


Topování nemovitostí

Topování nemovitostí se provádí pomocí stejného XML souboru. Typ uvedené operace je @operace -- "TOP" (velikost písmen se rozlišuje).
Podmínky služby topování naleznete zde. Lze topovovat více nemovitostí naráz (v jednom XML souboru).

Ukázka XML souboru pro topování:

<?xml version="1.0" encoding="utf-8"?>
<xreal>
  <identifikace typ="CLIENT">
    <datumcas>2015-04-20-22-55-51</datumcas>
    <autorizace id="202333"/>
  </identifikace>                                            
  <nabidky>
    <nabidka id="1065" operace="TOP">
    </nabidka>
    <nabidka id="1068" operace="TOP">
    </nabidka>
  </nabidky>
</xreal>

Odpověď ve formátu JSON:

Topování proběhlo v pořáku.
{
    "ceskereality": [
         {
            "status": "success",
            "code": 202,
            "message": "top_OK",
            "details": "topování proběhlo v pořádku",
            "id_inzeratu": 2983002
        }
    ]
}

Topování neproběhlo v pořádku.
{
    "ceskereality": [
        {
            "status": "error",
            "code": 494,
            "message": "top_last_24h",
            "details": "nemovitost byla v poslednich 24 hodinách již topována",
            "id_inzeratu": 5678
        },
        {
            "status": "error",
            "code": 491,
            "message": "top_no_foto1",
            "details": "nemovitost pro topování nemá vloženy fotografie",
            "id_inzeratu": 5515
        },
    ]
}

Chybový výstup
neplatné nebo neexistující id_inzeratu pro topování
{
    "ceskereality": [
        {
            "status": "error",
            "code": "490",
            "message": "top_invalid_id_inzeratu",
            "details": "neplatné nebo neexistující id_inzeratu pro topování",
            "id_inzeratu": "2983002"
        }
    ]
}      
nemovitost pro topování nemá vloženy fotografie
{
    "ceskereality": [
        {
            "status": "error",
            "code": "491",
            "message": "top_no_foto1",
            "details": "nemovitost pro topování nemá vloženy fotografie",
            "id_inzeratu": "2983002"
        }
    ]
}      
nemovitost pro topování je blokována
{
    "ceskereality": [
        {
            "status": "error",
            "code": "492",
            "message": "top_blokovana_nem",
            "details": "nemovitost pro topování je blokována",
            "id_inzeratu": "2983002"
        }
    ]
}      
nemovitost pro topování je umístěna v BOXu
{
    "ceskereality": [
        {
            "status": "error",
            "code": "493",
            "message": "top_box",
            "details": "nemovitost pro topování je umístěna v BOXu",
            "id_inzeratu": "2983002"
        }
    ]
}      
nemovitost byla v posledních 24 hodinách již topována
{
    "ceskereality": [
        {
            "status": "error",
            "code": "494",
            "message": "top_last_24h",
            "details": "nemovitost byla v posledních 24 hodinách již topována",
            "id_inzeratu": "2983002"
        }
    ]
}      
vnitřní chyba topování, kontaktujte správu serveru
{
    "ceskereality": [
        {
            "status": "error",
            "code": "495",
            "message": "top_internal_error",
            "details": "vnitřní chyba topování, kontaktujte správu serveru",
            "id_inzeratu": "2983002"
        }
    ]
}      
nedostatečný kredit pro topování
{
    "ceskereality": [
        {
            "status": "error",
            "code": "496",
            "message": "top_no_credit",
            "details": "nedostatečný kredit pro topování",
            "id_inzeratu": "2983002"
        }
    ]
}      


Statistiky návštěvnosti nemovitostí

Statisky jsou dostupné za souhrnné období nebo za konkrétní den (ve formátu YYYY-MM-DD).

Upozornění: vzhledem k charakteru služby Google Analytics jsou data za aktuální den dostupná po 3 dnech.


1. Souhrnné období:
Základní dotaz na všechny zakázky - výstup za posledních evidovaných 30 dní.
Příklad skriptu naleznete v balíku s ukázkovým PHP klientem (soubor statistiky.php ve složce examples).

Volané URL: https://import.ceskereality.cz/statistiky/statistiky.html?id_firmy=202333

Další volitelné parametry dotazu:

2. Denní statistika
https://import.ceskereality.cz/statistiky/statistiky.html?id_firmy=202333&den=2020-07-06

Odpověď ve formátu JSON:

{
    "ceskereality": {
        "souhrny": {
            "od": "2019-01-06",
            "do": "2019-01-06",
            "suma_zobrazeno_celkem": 105,
            "suma_dny": [
                {
                    "suma_datum": "2019-01-06",
                    "suma_datum_zobrazeno": 632
                }
            ]
        },
        "nemovitosti": [
            {
                "id_polozky": 2148687503,
                "id_inzeratu": "0387",
                "zobrazeno": 37,
                "datumy": [
                    {
                        "datum": "2019-01-06",
                        "pocet": 37
                    }
                ]
            },
            {
                "id_polozky": 2151573517,
                "id_inzeratu": "2696",
                "zobrazeno": 36,
                "datumy": [
                    {
                        "datum": "2019-01-06",
                        "pocet": 36
                    }
                ]
            },

...

            {
                "id_polozky": 2151636975,
                "id_inzeratu": "2762",
                "zobrazeno": 1,
                "datumy": [
                    {
                        "datum": "2019-01-06",
                        "pocet": 1
                    }
                ]
            }
        ]
    }
}



Exporty dotazů k nemovitostem

Výpis dotazů k nemovitostem od návštěvníků webového portálu www.ceskereality.cz.
Příklad skriptu naleznete v balíku s ukázkovým PHP klientem (soubor zadosti_k_nemovitostem.php ve složce examples).

Volané URL: https://import.ceskereality.cz/statistiky/zadosti_k_nemovitostem.html?id_firmy=202333

Je možné použít v dotazu datumové parametry od a do (dle vzoru RRRR-MM-DD). Je nutné použít oba dva parametry zároveň. Skript vypíše poté jen dotazy vložené do systému v zadaném časovém rozmezí. Bez parametrů od a do vypíše skript dotazy za posledních 30 dnů.

https://import.ceskereality.cz/statistiky/zadosti_k_nemovitostem.html?id_firmy=202333&od=2020-07-06&do=2020-07-13

Odpověď ve formátu JSON:

{
    "ceskereality": {
        "od": "2019-03-10",
        "do": "2019-03-11",
        "pocet": 1,
        "zadosti": [
            {
                "id": 275501,
                "jmeno": "Petra Nová ",
                "telefon": "777777777",
                "email": "test@seznam.cz",
                "text_zadosti": "Dobrý den, mám zájem o více informací k této nemovitosti (Byt 1+1, Aš 144/5, cena 5.000 Kč/měsíc). Prosím kontaktujte mě. Děkuji",
                "id_inzeratu": "02911",
                "datumcas": "2019-03-10 02:06:14"
            }
        ]
    }
}

Význam položek:

Prázdný výstup
nemáte na serveru uložené žádné dotazy k nemovitostem, případně jste nesprávně použili parametry dotazu od a do
{
    "ceskereality": {
        "od": "2019-03-06",
        "do": "2018-03-11",
        "pocet": 0
    }
}
      


Správa makléřů

Skript pro možnost výpisu a výmazu makléřů realitní kanceláře.
Příklad skriptu naleznete v balíku s ukázkovým PHP klientem (soubor makleri.php ve složce examples).

Makléř je identifikován položkou makler_int_id - ID makléře ve Vašem realitním software.

1) Výpis makléřů

Volané URL: https://import.ceskereality.cz/makleri.html?id_firmy=202333

Odpověď ve formátu JSON:

{
    "ceskereality": [
        {
            "id_maklere": "80948",
            "makler_int_id": "4909",
            "makler_login": "",
            "makler_jmeno": "Jan Nechvátal",
            "makler_telp": "",
            "makler_telm": "+420  777 777 777",
            "makler_info": "",
            "makler_mail": "nechvatal@ceskereality.cz",
            "makler_last_change": null,
            "blokovany": "1",
            "makler_foto_url": "https:\/\/img.ceskereality.cz\/makleri\/21200\/4909.jpg"
        },
        {
            "id_maklere": "79237",
            "makler_int_id": "KXB-14587",
            "makler_login": "",
            "makler_jmeno": "Novák Jan",
            "makler_telp": "+420 222 222 222",
            "makler_telm": "+420 777 777 111",
            "makler_info": "specialista pro Prahu 6",
            "makler_mail": "makler@ceskereality.cz",
            "makler_last_change": null,
            "blokovany": "1"
        }
    ]
}

Význam položek:

Prázdný výstup
nemáte na serveru uloženého žádného makléře
    {
    "ceskereality": [
        {
            "status": "success",
            "code": "203",
            "message": "makler_OK",
            "details": "nemáte na serveru uloženého žádného makléře"
        }
    ]
}      


2) Smazání makléře

Přídáním položky id_maklere a "operace=D" dojde k vymazání příslušného makléře a jeho fotografie (pokud je na serveru uložena).

Volané URL: https://import.ceskereality.cz/makleri.html?id_firmy=202333&operace=D&id_maklere=77829

Odpověď ve formátu JSON:

{
    "ceskereality": [
      {
          "status": "success",
          "code": "210",
          "message": "makler_del_OK",
          "details": "výmaz makléře proběhl v pořádku",
          "id_maklere": "80948"
      }
    ]
}


Chybový výstup
neplatné nebo neexistující id_makléře
    {
    "ceskereality": [
        {
            "status": "error",
            "code": "445",
            "message": "invalid_id_maklere",
            "details": "neplatné nebo neexistující id_makléře",
            "id_maklere": "77829"
        }
    ]
}      
neplatný typ operace ve výpisu makléřů
    {
    "ceskereality": [
        {
            "status": "error",
            "code": "446",
            "message": "invalid_makler_operace",
            "details": "neplatný typ operace ve výpisu makléřů",
            "id_maklere": "77829"
        }
    ]
}      


Změny oproti starému rozhraní

Přehled změn proti předchozí verzi exportu 2.0 (http://import.ceskereality.cz/specifikace/).