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

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

Upozornění: Důrazně doporučujeme implementovat import dotazů k nemovitostem do všech realitních programů. Standardně posíláme každý požadavek o nemovitosti makléřům formou e-mailu, jehož doručení však nelze garantovat. Makléř tak při opakovaném neobdržování informací o zájemcích k nemovitostem může zaznamenávat vysoké finanční ztráty.
Viz odkaz: Exporty dotazů k nemovitostem.

Obsah

• Changelog
• Výhody přechodu na novou verzi 3.0
• Postup exportu a popis volání
• Popis formátu XML dokumentu
• Topování nemovitostí
• Statistiky návštěvnosti nemovitostí
• Exporty dotazů k nemovitostem
• Správa makléřů
• Developerské projekty
• Změny oproti starému rozhraní

Changelog

Výhody přechodu na novou verzi 3.0

• exportér nemusí znát přístupové údaje (login a heslo) každé realitní kanceláře, nehrozí tak ani jejich únik ze serveru exportéra (ideální z hlediska GDPR)
• pokud si realitní kancelář změní heslo, export nepřestane fungovat
• veškerá komunikace při exportu probíhá šifrovaně přes https
• volitelně, jako doporučené nastavení, lze nastavit seznam povolených adres exportních serverů pro zabránění zneužití třetí stranou
• autorizace exportéra funguje přes volně přístupnou knihovnu OAuth2
• lze importovat ze serveru statistiky nemovitostí
• lze importovat jednotlivé dotazy návštěvníků k nemovitostem

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í

• id_firmy - unikátní ID realitní kanceláře na serveru ceskereality.cz (!!! nejedná se o client_id z předchozích verzí exportu !!!)
• pin_exportu - aktivační kód realitní kanceláře umožňující export na ceskereality.cz, kód RK vyplní v nastavení exportu na ceskereality.cz v administraci svého realitního programu
• id_inzeratu - unikátní ID nemovitosti v systému exportéra(realitní kanceláře)
• url_inzeratu - URL exportované nemovitosti na serveru ceskereality.cz
• id_foto - unikátní ID fotografie u inzerátu v systemu exportéra(realitní kanceláře), ID musí být unikátní pro všechny inzeráty příslušné RK
• id_maklere - unikátní ID makléře na serveru ceskereality.cz
• makler_int_id - unikátní ID makléře v systému exportéra(realitní kanceláře)
• access_token - přístupový token k exportům získaný exportérem na základě CLIENT_ID a CLIENT_SECRET od serveru ceskereality.cz
• CLIENT_ID - ID exportéra potřebné pro získání access_tokenu
• CLIENT_SECRET - heslo exportéra potřebné pro získání access_tokenu

Odpovědi serveru

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

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

Význam položek:

• status - může nabývat hodnot success(code 2XX), warning(code 3XX) nebo error(code 4XX,5XX)
• code - jednoznačný číselný kód vráceného statusu, v případě uspěšného dokončení akce se vrací kód 2XX, v případě varování se vrací kód 3XX (akce byla dokončena s varováním, např. kvůli chybějící fotografii), v případě chyby se vrací kód 4XX (chyba na straně exportéra, např. chybějící povinná položka) nebo kód 5XX (chyba na straně serveru, např. nefunkční databáze)
• message - jednoslovný popis výstupu
• details - detailní popis výstupu

• id_inzeratu - ID nemovitosti, které se výstup týká
• id_foto - ID chybějící fotografie, která při importu nebyla nahrána na server
• id_maklere - ID makléře, kterého se výstup týká

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.

Důrazně doporučujeme implementaci tohoto výpisu a následné synchronizace zakázek RK na serveru. Doporučená frekvence je minimálně 1x týdně. Optimálně 1x denně.

Ušetříte si spoustu zbytečných dotazů a stížností ze strany inzerentů na nevymazné či nahrané/neaktualizované zakázky na serveru.

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:

• code - návratový kód 222 - přidělen platný access token
• access_token - přístupový token
• expires_in - doba expirace tokenu ve vteřinách

{
	"ceskereality": {
		"status": "error",
		"code"": 400,
		"message": "invalid_client",
		"details": "The client credentials are invalid"
	}
}

    {
    "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": "52.15.63.145"
    }
}

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:

• id_firmy - ID realitní kanceláře
• pin_exportu - aktivační kód RK umožňující export, kód RK vyplní v nastavení exportu na ceskereality.cz v administraci svého realitního programu a exportér přes tento kód spáruje RK na serveru ceskereality.cz a ve svém realitním systému
• nazev - název realitní kanceláře
• ico - IČ realitní kanceláře
• ulice - ulice sídla realitní kanceláře
• mesto - obec sídla realitní kanceláře
• psc - PSČ sídla realitní kanceláře
• telefon - kontaktní telefon realitní kanceláře
• email - kontaktní email realitní kanceláře
• www - webová adresa realitní kanceláře
• registrace_do - datum platnosti registrace realitní kanceláře (pokud není datum platné, RK nemá právo exportu)

    {
    "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).

Důrazně doporučujeme implementaci tohoto výpisu a následné synchronizace zakázek RK na serveru. Doporučená frekvence je minimálně 1x týdně. Optimálně 1x denně.

Ušetříte si spoustu zbytečných dotazů a stížností ze strany inzerentů na nevymazné či nahrané/neaktualizované zakázky na serveru.

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",
	    "url_inzeratu": "https:\/\/www.ceskereality.cz\/nemovitost.html?pid=2151645689",
        },
        {
            "id_inzeratu": "5552",
            "last_access": "2019-01-29 10:10:03",
	    "url_inzeratu": "https:\/\/www.ceskereality.cz\/nemovitost.html?pid=2151645699",
        },
        {
            "id_inzeratu": "5515",
            "last_access": "2019-01-22 09:15:44"
	    "url_inzeratu": "https:\/\/www.ceskereality.cz\/nemovitost.html?pid=151645689",
        },
        {
            "id_inzeratu": "5349",
            "last_access": "2019-01-25 13:48:45"
	    "url_inzeratu": "https:\/\/www.ceskereality.cz\/nemovitost.html?pid=1645689",
        }
    ]
}

Význam položek:

• id_inzeratu - unikátní ID nemovitosti v systému exportéra(realitní kanceláře)
• last_access - datum poslední změny nemovitosti
• url_inzeratu - veřejné URL nemovitosti na serveru ceskereality.cz

    {
    "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:

• id_inzeratu - unikátní ID nemovitosti v systému exportéra(realitní kanceláře)
• last_access - datum poslední změny nemovitosti
• makler_int_id - unikátní ID makléře v systému exportéra(realitní kanceláře)
• foto1, foto2, ... - výpis ID dostupných fotografií nemovitosti
• url_inzeratu - veřejné URL nemovitosti na serveru ceskereality.cz
• makler_foto_url - URL fotografie makléře uloženého u nemovitosti (pokud na serveru existuje)

    {
    "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

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"
        }
    ]
}

    {
    "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:

{
    "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"
        }
    ]
}

{
    "ceskereality": [
        {
            "status": "success",
            "code": 205,
            "message": "import_OK",
            "details": "import projektu proběhl v pořádku",
            "id_inzeratu": "5872",
	    "url_inzeratu": "https:\/\/www.ceskereality.cz\/developerske_projekty\/nove-plane-5872.html"
        }
    ]
}

{
    "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"
        }
    ]
}

{
    "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"
        }
    ]
}

    {
    "ceskereality": [
        {
            "status": "error",
            "code": "470",
            "message": "invalid_xml",
            "details": "na serveru není nahrán XML soubor nemovitosti.xml\/projekty.xml"
        }
    ]
}      

    {
    "ceskereality": [
        {
            "status": "error",
            "code": "471",
            "message": "invalid_xml_file",
            "details": "nahraný XML soubor není validní"
        }
    ]
}      

    {
    "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

@typ -- CLIENT | SERVER

@nahrada -- hodnota "t" znamená nahradit všechny existující nabídky

@id -- ID číslo nabídky

@operace -- operace = "U" nebo "D" nebo "I" (Update/Insert/Delete)

@id -- identifikátor pole

@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

• neznámé položky <pole> jsou ignorovány
• všechny pole nabídky musejí být exportovány v jednom souboru
• nepřidávat prázdné <pole>do exportu s obsahem ("" nebo 0)
• koncovka zasílaných souborů fotografií je ".jpg" s malými písmeny v příponě
• pořadí fotografií na serveru je dáno jejich pořadím v <nabidka>
• maximální povolená velikost zasílaných souborů (xml, jpg, pdf) je 30000000b

• obec (3) - číselník obsahuje všechny obce, automaticky se doplní příslušnost k okresu
• část obce (5) - číselník obsahuje všechny části obce, automaticky se doplní příslušnost k obci a okresu
• ulice (7) - číselník obsahuje všechny ulice, automaticky se doplní příslušnost k obci a okresu
• adresa (11) - adresné zadání polohy nemovitosti, automaticky se doplní okres, obec, část obce, městská část, číslo popisné a orientační
• městská část (17) - číselník obsahuje všechny městské části, automaticky se doplní příslušnost k obci a okresu

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_facebook">http://www.facebook.com/xxxxxx</pole>

   <pole id="makler_twitter">http://www.twitter.com/xxxxxx</pole>

   <pole id="makler_linkedin">https://www.linkedin.com/xxxxxx</pole>

   <pole id="makler_pinterest">https://cz.pinterest.com/xxxxxx</pole>
         
   <pole id="makler_youtube">https://youtube.com/xxxxxx</pole>

   <pole id="makler_instagram">https://www.instagram.com/xxxxxx</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_mail">makler@ceskereality.cz</pole>

   <pole id="makler_facebook">http://www.facebook.com/xxxxxx</pole>

   <pole id="makler_twitter">http://www.twitter.com/xxxxxx</pole>

   <pole id="makler_linkedin">https://www.linkedin.com/xxxxxx</pole>

   <pole id="makler_pinterest">https://cz.pinterest.com/xxxxxx</pole>
    
   <pole id="makler_youtube">https://youtube.com/xxxxxx</pole>

   <pole id="makler_instagram">https://www.instagram.com/xxxxxx</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:

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

{
    "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
        },
    ]
}

{
    "ceskereality": [
        {
            "status": "error",
            "code": "490",
            "message": "top_invalid_id_inzeratu",
            "details": "neplatné nebo neexistující id_inzeratu pro topování",
            "id_inzeratu": "2983002"
        }
    ]
}      

{
    "ceskereality": [
        {
            "status": "error",
            "code": "491",
            "message": "top_no_foto1",
            "details": "nemovitost pro topování nemá vloženy fotografie",
            "id_inzeratu": "2983002"
        }
    ]
}      

{
    "ceskereality": [
        {
            "status": "error",
            "code": "492",
            "message": "top_blokovana_nem",
            "details": "nemovitost pro topování je blokována",
            "id_inzeratu": "2983002"
        }
    ]
}      

{
    "ceskereality": [
        {
            "status": "error",
            "code": "493",
            "message": "top_box",
            "details": "nemovitost pro topování je umístěna v BOXu",
            "id_inzeratu": "2983002"
        }
    ]
}      

{
    "ceskereality": [
        {
            "status": "error",
            "code": "494",
            "message": "top_last_24h",
            "details": "nemovitost byla v posledních 24 hodinách již topována",
            "id_inzeratu": "2983002"
        }
    ]
}      

{
    "ceskereality": [
        {
            "status": "error",
            "code": "495",
            "message": "top_unvalid_code",
            "details": "neplatný kód nemovitosti",
            "id_inzeratu": "2983002"
        }
    ]
}      

{
    "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.

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

Další volitelné parametry dotazu:

• cislo ... zobrazení statistik pouze pro konkrétní číslo nemovitosti
  https://import.ceskereality.cz/statistiky/statistiky.html?id_firmy=202333&id_inzeratu=2983002


• celeobdobi ... zobrazení celého období sledování statistik (neomezeno 30 dny jako u základního dotazu)
  https://import.ceskereality.cz/statistiky/statistiky.html?id_firmy=202333&celeobdobi=1


• sum ... vypne zobrazeni jednotlivych dni a zustane jen suma za každou nemovitost
  https://import.ceskereality.cz/statistiky/statistiky.html?id_firmy=202333&sum=1
  


• group_by ... povolena hodnota "id_inzeratu", sdruží výsledky dle ID inzerátu
  https://import.ceskereality.cz/statistiky/statistiky.html?id_firmy=202333&group_by=id_inzeratu
  

Odpověď ve formátu JSON:

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

...

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

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ů.

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",
                "navrzena_cena": "30 000 Kč" 
            }
        ]
    }
}

Význam položek:

• od - počáteční datum omezení výstupu
• do - konečné datum omezení výstupu
• pocet - celkový počet dotazů za vypisované období - omezeno parametry od a do

• id - id dotazu v databázi českých realit
• jmeno - jméno dotazujícího uživatele
• telefon - telefonní kontakt dotazujícího uživatele
• email - mailový kontakt dotazujícího uživatele
• text_zadosti - vlastní text žádosti
• id_inzeratu - id nemovitosti (pro propojeni s Vašimy záznamy)
• datumcas - datum zadání dotazu
• navrzena_cena - navržená cena dotazujícím uživatelem

{
    "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_pinterest": "",
	    "makler_twitter": "",	
	    "makler_linkedin": "",	
	    "makler_youtube": "",	
	    "makler_instagram": "",	
	    "makler_facebook": "",	
            "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_pinterest": "",
	    "makler_twitter": "",	
	    "makler_linkedin": "",	
	    "makler_youtube": "",	
	    "makler_instagram": "",	
	    "makler_facebook": "",	
            "makler_last_change": null,
            "blokovany": "1"
        }
    ]
}

Význam položek:

• id_maklere - ID makléře na serveru www.ceskereality.cz
• makler_int_id - ID makléře ve Vašem realitním software
• makler_login - interní email makléře, sloužící k přihlášení do servisni sekce, položka se nezobrazuje na webu !!!
• makler_telp - telefon (pevná linka) makléře zajišťující prodej nemovitosti
• makler_telm - telefon (mobil) makléře zajišťující prodej nemovitosti
• makler_info - rozšiřující informace o makléři zajišťující prodej nemovitosti
• makler_mail - mail makléře zajišťující prodej nemovitosti
• makler_last_change - datum a čas poslední změny údajů makléře
• blokovany - hodnota 1 značí blokaci makléře
• makler_foto_url - fotografie maléře uložená u nemovitosti

    {
    "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"
      }
    ]
}

    {
    "ceskereality": [
        {
            "status": "error",
            "code": "445",
            "message": "invalid_id_maklere",
            "details": "neplatné nebo neexistující id_makléře",
            "id_maklere": "77829"
        }
    ]
}      

    {
    "ceskereality": [
        {
            "status": "error",
            "code": "446",
            "message": "invalid_makler_operace",
            "details": "neplatný typ operace ve výpisu makléřů",
            "id_maklere": "77829"
        }
    ]
}      

Developerské projekty

Export developerských projektů na server se provádí obdobnýcm způsobem jako export nemovitostí.
Nejprve se pomocí skriptu upload datového souboru a fotografií - uloz_xml.html - nahrají na server všechny fotografie a XML soubor s popisem dat developerského projektu.
Názvev XML souboru musí být "projekty.xml". Povolené kódování souboru je 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, XML). Doporučujeme posílat soubory v pořadí: nejprve fotografie a nakonec XML soubor "projekty.xml".

Po uploadu všech souborů na server spouštíte skript import dat do databáze - import_xml.html.
Při importu dochází u textových řetezců k odstranění HTML značek.
Chybová hlášení a výstupy jsou vraceny v kódování utf-8 a ve formátu JSON. Příklady výstupů naleznete výše.

Popis formátu XML souboru "projekty.xml".

@typ -- CLIENT | SERVER

@id -- ID jedinečné číslo projektu, musí odpovídat položce id_dev_projektu exportované u nemovitostí patřících do dev. projektu

@operace -- operace = "I" nebo "D" (Insert(update)/Delete)

@id -- identifikátor pole

@id -- identifikátor (MD5 hash) fotografie, hash každé fotografie musí být pro dannou RK jedinečný v rámci všech developerských projektů, max. délka hash je 40 znaků

Ukázka XML souboru "projekty.xml".

<?xml version="1.0" encoding="utf-8" ?>

<xreal>

<identifikace typ="CLIENT">

<datumcas>2021-09-03-10-09-14</datumcas>

<autorizace id_firmy="100184"/>

</identifikace>

<projekty>

<projekt id="5870" operace="I">

<pole id="projekt_nazev">Nové Pláně</pole>

<pole id="projekt_popis">Dostupné bydlení v klidné části čtvrti NOvé Pláně ...</pole>

<pole id="projekt_popis_kratky">Nové Pláně nabízí dostupné bydlení ....</pole>

<pole id="projekt_url">https://www.noveplane.cz</pole>

<pole id="datum_platnost_do">2023-01-30</pole>

<pole id="datum_nastehovani">2022-01-30</pole>

<pole id="datum_vystavba">2021-10-30</pole>

<pole id="datum_prodej">2021-11-01</pole>

<pole id="standard_podlahy">dřevěné, dle přání zákazníka</pole>

<pole id="standard_obklady">keramické, Rakona</pole>

<pole id="standard_okna">6-ti komorová plastová, venkovní strana barva RAL, vnitřní strana v bílé barvě</pole>

<pole id="blokovany">0</pole>

<pole id="ruian_uroven">11</pole>

<pole id="ruian_kod">22277889</pole>

<pole id="zeme">203</pole>

<pole id="gps_lat">50.13652</pole>

<pole id="gps_lon">14.36959</pole>

<pole id="en_trida">A</pole>

<pole id="en_hodnota">5</pole>

<pole id="en_vyhlaska">1</pole>

<pole id="last_access">2021-09-03 10:43:04</pole>

<kategorie id="1" />

<kategorie id="3" />

<foto id="d28e29dee952e0b412897b56f6e69820"/>

<foto id="3e64ada54c8a9159a5222015cd3813ca"/>

<foto id="562e9858290373f02376e219a5fc968f"/>

<foto id="f1c8b16c5708bbee5ea4198ccb1bc1ed"/>

<foto id="b67d91bcde0b39d1f3add0541dce1516"/>

<foto id="d3ba2d794aa21e7cf2158dcee70f6d6a"/>

<foto id="25839cf943d625aaf2004b8008ecd9fa"/>

<foto id="8101d866cda740f1940fb7b9ab7a6732"/>

<video id="eCGsrzyv5u"/>

<video id="aa45rzy587"/>

<video id="arcs7d5v54"/>

<prohlidka3d id="XWHKG8fuFBj" typ="1" />

<prohlidka3d id="4587dASEK54" typ="1" />

</projekt>

</projekty></xreal>

Změny oproti starému rozhraní

• přechod na https - adresa exportního rozhraní https://import.ceskereality.cz/
• autoritace pomocí knihovny OAuth2
• všechny výstupy ve formátu JSON ve sjednoceném formátu
• změna pole autorizace v posílaném XML z původního <autorizace id="12332" prefix="TTT" jmeno="jmenoxx"/> na novou podobu <autorizace id_firmy="202333"/>
• velikost fotografie makléře zvětšena na 200x240px
• přidána nová položka: prohlidka3d_typ a položka pl_podlahova
• nově se kontrolují proti číselníku položky kod_spravnihoob_pha a kod_uzemniob_pha
• podpora exportů dotazů k nemovitostem