Dokumentace importního rozhraní RealityMIX ¶

Aktuální verze kanálu je 1.3.5

Změny oproti verzi 1.3.4 19.04.2022 ¶

Změny oproti verzi 1.3.3 29.11.2021 ¶

Změny oproti verzi 1.3.2 31.8.2021 ¶

Byly přidány položky pro import nabídky sdílené v rámci aplikace RMIX MLS. Konkrétně se jedná o položky shared_advert - příznak zda je nabídka sdílená, neveřejná nebo se jedná o předprodej. Provize nabízená spolupracujícímu makléři v rámci spolupráce shared_advert_commission a poznámka ke spolupráci shared_advert_note, ve které by měl makléř popsat detaily ke spolupráci, případně například uvést cenu, která je jinak na vyžádání. Konkrétní hodnoty jsou uvedeny v datové struktuře.

Doplňeno: V případě, že makléř exportuje nabídku v režimu veřejného sdílení, musí být registrován v MLS. Pokud není registrován, rozhraní vrací informaci o ignorování parametrů pro sdílení v novém poli userMessages - zprávy pro uživatele. V případě neveřejného sdílení a neregistrovaného makléře je nemovitost zamítnuta zcela, aby při ignorování polí pro sdílení nedošlo ke zveřejnění nemovitosti.

Změny oproti verzi 1.3.1 4.8.2021 ¶

Byla upravena maximální délka položky projektu basic_project_description na 250 znaků.

Změny oproti verzi 1.3.0 30.6.2021 ¶

Byly přidány funkce listInquiry, listFullInquiry a getInquiry. Tyto funkce slouží pro práci s dotazy zaslanými přes portál RealityMIX.

Pro využívání funkcí musí provozovatel softwaru uzavřít s DALTEN media s.r.o. provozující portál RealityMIX.cz dohodu o zpracování osobních údajů a zaregistrovat pro svůj softwarový klíč IP adresu nebo sadu IP adres. Pro nesprávnou kombinaci sw klíč / IP adresa nebude vydávání dotazů fungovat.

Změny oproti verzi 1.2.1 10.5.2020 ¶

Přidání parametru hide_portals k nabídkám. Specifikuje portály, na kterých si uživatel nepřeje nabídku inzerovat. V tuto chvíli je podporováno skrytí na portálu FTV Prima (iprima.realitymix.cz, HbbTV aplikace TV Prima).

Poznámka: Všechny realitní portály skupiny RealityMIX vychází ze stejné databáze, a tak není možné pro jednotlivé portály vytvořit samostatnou importní frontu.
Klientovi se na specifickém portálu nabídka zobrazí pouze při splnění dvou podmínek. Klient musí mít pro inzerci na portálu podepsanou samostatnou smlouvu o inzerci a u nabídky nesmí být zasláno hide_portals (pro HbbTV Prima s hodnotou “01”). V případě, že nabídka má vyplněný hide_portals nebo klient nemá podepsanou smlouvu, nabídka se na portálu nezobrazí a není klientovi na daný portál účtována.

Změny oproti verzi 1.2.0 22.8.2019 ¶

Přidání metody topAdvert k nabídkám. Jde o metodu pro topování nabídek.

Nově podporujeme pro položku virtual_tour také službu Matterport. Do parametru zasílejte URL.

Změny oproti verzi 1.1.8 20.8.2018 ¶

Přidání metody listStats k nabídkám. Jde o hromadný tvar existující metody listStat vracející pole statistik.

Změny oproti verzi 1.1.7 19.6.2018 ¶

Přidání parametru virtual_tour k nabídkám. Do parametru je možné zadat url na virtuální prohlídku ze služby Nview.cz.

Změny oproti verzi 1.1.6 25.5.2016 ¶

Odstranění nepoužívaného parametru user_status z nabídek a projektů.

Změny oproti verzi 1.1.5 8.3.2016 ¶

Přidání parametru video_url k nabídkám. Do parametru je možné zadat url na video ze služby YouTube.com.

Změny oproti verzi 1.1.4 25.6.2014 ¶

Položka počet podlaží objektu floors pro typ nemovitosti byty již není povinná.

Změny oproti verzi 1.1.3 4.5.2014 ¶

Úprava omezení počtu operací.

Změny oproti verzi 1.1.2 17.4.2014 ¶

Rozšíření povinných položek při importu developerských projektů.
Nově jsou povinné tyto položky.

1. project_name
2. project_city
3. project_zip
4. developer_name
5. developer_street
6. developer_city
7. developer_zip
8. developer_email
9. developer_phone
10. basic_project_description
11. project_description
12. gps_latitude
13. gps_longitude

Změny oproti verzi 1.1.1 ¶

1. Z číselníku estate kind byly odstraněny hodnoty 8 (průmyslová zóna), 9 (chmelnice, vinice) a 10 (vodní plocha).
2. Z číselníku transport byly odstraněny hodnoty 5 (silnice 1. třídy), 6 (říční přístav) a 7 (přímořský přístav).

Tyto hodnoty nebylo možné exportovat ani v předchozích verzí rozhraní, ale byly chybně uvedeny v dokumentaci.

Změny oproti verzi 1.1 ¶

1. Odstraněna duplicitní položka floor. Místo je používána položka floor_number. Pokud exportní software zašle k nemovitosti parametr floor a nikoli floor_number, bude floor považováno za floor_number. (tj. není potřeba nic měnit)

Změny oproti verzi 1.0 ¶

1. Metody addAdvert, addPhoto, listAdvert, addDevel, listDevel, addDevelPhoto, listDevelPhoto, addSeller a listSeller vrací nově datový typ struct v proměné output.
2. Změna adresy importního rozhraní.
3. Změna datových typů u advert_price a ceiling_height z int na float.
4. Podpora vkládání energetických štítků.
5. Podpora metody listStat (viz dokumentace jednotlivých metod).
6. Doplnění ladících informací (ignorované hodnoty, ignorované parametry, atp.).
7. Ukončení platnosti univerzálního softwarového klíče.

Přechod z verze 1.0 na 1.1 ¶

Při přechodu z verze 1.0 budete v případě, že používáte univerzální sw. klíč, potřebovat vygenerovat unikátní klíč pro Váš software. Ten Vám vygeneruje klientský servis.

Kontaktní informace naleznete na stránce: https://realitymix.cz/o-nas.php

Vytvoření nového exportního modulu ¶

Vytváříte-li nový exportní software, obrat’te se na klientský servis RealityMIX. Klientský servis Vám poskytne testovací údaje včetně testovacího softwarového klíče. Po dokončení vývoje exportu Vám klientský servis také zajistí vytvoření softwarového klíče pro Vaši aplikaci.

Kontaktní informace naleznete na stránce: https://realitymix.cz/o-nas.php

Základní popis komunikace ¶

Import je realizován protokolem XML/RPC, s jehož pomocí lze velice jednoduše volat vzdálené procedury. Protokol při komunikaci přeloží data do značkovacího jazyka XML a tyto data pak dále přenáší protokolem HTTP. Veškerá komunikace se serverem a zpět probíhá v kódování UTF-8. Binární data se přenáší přeložená do Base64.

Implementace do aplikací může být realizována množstvím knihoven pro různé programovací jazyky. V naší dokumentaci naleznete krátké vzorové miniaplikace pro komunikaci se serverem v jazyku PHP a Python.

Všechny metody vrací strukturovaný výstup, který tvoří položky output (výstupní data), status (kód odpovědi), statusMessage (textová reprezentace odpovědi).

Všem uvedeným metodám je nutno předat všechny specifikované parametry. Pokud je uvedeno, že parametr je nepovinný, stačí jej vyplnit podle typu prázdnou hodnotou.

Pro přihlášení se nejprve musí zavolat metoda getHash, které se předá ID, a ta vrátí hashovací klíč, který se použije dále pro metodu login. Metoda login slouží pro potvrzení přihlášení, které se předá zakódované heslo a softwarový klíč. Pokud přihlášení proběhne v pořádku, vrátí metoda status 200.

Rozhraní používá MD5 hashování v hexadecimálním tvaru.

Adresa rozhraní ¶

Serverové rozhraní XML-RPC se nachází na adrese: https://realitymix.cz/import/rpc/, port číslo 443 (https://realitymix.cz:443/import/rpc/)

Identifikace inzerátů ¶

Kdykoliv je použito v parametru metody advert_id a rkid, platí toto pravidlo. Pokud je zadáno advert_id, musí být rkid prázdný řetězec. Pokud je zadáno rkid, musí být advert_id číslo nula. Stejná situace nastává u photo_id X photo_rkid, seller_id X seller_rkid, developer_id X devel_rkid.

U rkid lze využít tzv. dvojtečkovou konvenci abc::xyz. Ta je vhodná pro případ, kdy uživatel potřebuje rozlišit veřejný a neveřejný identifikátor zakázky. První část (před ::) je veřejná a zobrazovaná u inzerátu, druhá část slouží pro identifikaci.

Vzhledem k tomu, že první část je unikátní v rámci RK pro identifikaci inzerátu (pokud má o inzerát někdo zájem) a druhá část slouží jako unikátní pro identifikaci (např. jako klíč) v softwaru, který zakázku exportuje, jsou unikátně brány obě varianty. V případě rozdílných identifikací unikátního RK a unikátního software klíče má přednost klíč softwaru. Lze tak pro zakázku v případě potřeby změnit veřejný kód zakázky.

Příklad rkid:
export 1: 'abc::xyz' => vložení nového inzerátu
export 2: 'abc' => update inzerátu
export 3: 'bcd::xyz' => update inzerátu xyz, změna kódu zakázky
export 4: 'dse::see' => vložení nového inzerátu

Nalezení nabídek na RealityMix.cz ¶

Pokud potřebujete najít nabídku na RealityMixu můžete k tomu použít pomocnou url: https://realitymix.cz/detail.php?rk_id=client_id&rk_cislo=rkid.

Názvosloví ¶

• session_id – řetězec znaků a čísel, který identifikuje konkrétní přihlášení
• hash – řetězec znaků a čísel, který slouží k zakódování hesla
• software_key – řetězec, identifikující použitý software
• advert_data – asociativní pole dat inzerátu
• type_data – asociativní pole dat specifických dat inzerátu
• advert_id – jedinečné interní číslo inzerátu
• photo_id – jedinečné interní číslo fotky
• seller_id – jedinečné interní číslo makléře
• developer_id – jedinečné interní číslo projektu

Typický průběh komunikace ¶

• getHash
• login
• listAdvert
• delAdvert
• ...
• addAdvert
• addPhoto
• ...
• logout

Omezení počtu operací ¶

Od 1.5.2014 není omezen počet operací prováděných přes importní rozhraní. Je však zakázáno nadměrné využívání níže uvedených operací a to v počtu nad limit 10% operací z počtu zveřejněných inzerátů za minulý den (minimálně 10). Operace prováděné nad uvedený limit (10 a nebo 10% z uveřejněných inzerátů) penalizují všechny další nabídky se kterými jsou ten den operace prováděny. Nabídky po vyčerpání počtu operací jsou řazeny na poslední místa ve vyhledávání.

Toto omezení se týká následujících operací:

• vložení nového inzerátu (addAdvert),
• změna ceny existujícího inzerátu (addAdvert),
• smazání inzerátu (delAdvert),
• změna stavu inzerátu (statusAdvert).

Limit se počítá vždy od půlnoci a uplatňuje se pouze pro aktivní inzeráty.

Příklady:

• RK má 100 aktivních inzerátů. Následující den tedy bude moci vložit, smazat, změnit cenu nebo změnit stav nejvýše 10 inzerátů. Po vyčerpání limitu 10 operací budou další vkládané nabídky penalizovány.
• RK má 1000 aktivních inzerátů. Následující den tedy bude moci vložit smazat, změnit cenu nebo změnit stav nejvýše 100 inzerátů. Po vyčerpání limitu 100 operací budou další vkládané nabídky penalizovány.

V textu inzerátu je vyloučeno zejména.

1. Zveřejnění verzálkami psaných slov (pokud se nejedná o zkratky či názvy, které se oficiálně zapisují pouze verzálkami).
2. Uveřejnění více než jednoho vykřičníku (před vykřičníkem nesmí být mezera).
3. Psaní tázacích, zvolacích a rozkazovacích vět.
4. několikanásobné opakování slova/fráze, nadměrná interpunkce (tři tečky), „smajlíky“.
5. HTML značky.
6. Ukončení výčtu výrazy „atd.“ , „a tak dále“, „...“ a jejich ekvivalenty.
7. Používání superlativů, např: „nejlepší služby poskytované…“.
8. Uvádět nic neříkající věty typu „vše, co jste kdy chtěli vědět o…“, „přijďte se podívat…“.
9. Zobrazovat loga společnosti na místě pro fotografie nemovitosti.
10. Obchodní sdělení, reklama či zmínky o konkurenci.
11. Uveřejňovat přetažené a neautorizované fotografie od jiných uživatelů systému.
12. Vodotisk (logo RK) fotografie s průhledností nad 50%.
13. Vložení identické nabídky nemovitostí, totožné nemovitosti s drobnými odchylkami v popisu nebo fotografiích, nabídky s nulovou cenou či spekulativní cenou.
14. Vložení fotografie, bezprostředně se dané nemovitosti týkající.
15. Vložení fotografie s reklamním sdělením či grafickým zvýrazněním (netýká se vodotisku s logem realitní kanceláře).
16. Zveřejňovat kontaktní informace na osoby, firmy nebo webové stránky mimo místa k tomu určená např. v popisu nabídky nebo fotografiích.

Řazení nemovitosti ve vyhledávání není podle data vložení nabídky. Datum vložení je pouze jednou z proměnných.

V případě zjištění opakovaného překračování denních limitů nebo jejich nadměrného čerpání s ohledem na celkový průměr všech realitních kanceláří budou nabídky kanceláře penalizovány a zařazeny na konec výpisů ve vyhledávání.