Aktualní verze 1.4, poslední změna: 21.2.2024, seznam změn
Swagger framework rozhraní
Obecné informace k rozhraní
Práce s exportním rozhraním
ReEx Service je služba, která umožňuje realitnímu softwaru zasílat nabídky na různé exportní (realitní) servery.
Služba je určena pro software, ale který se nechtějí starat o neustále se měnící rozhraní jednotlivých exportních serverů, na které zasílají své nabídky. Tvůrce tak implementuje pouze jedno rozhraní mezi jejich softwarem a službou ReEx a přes tuto službu pak může zasílat své nabídky na všechny servery, které ReEx podporuje.
Uživatel pracující s rozhraním má přidělen "token", kterým identifikuje každý požadavek zasílaný do rozhraní.
Pro identifikaci použijte standardní "Bearer Authentication", tedy do http hlavičky přidejte:
Authorization: Bearer <token>
Pokud by váš token byl diskreditován, obraťte se na provozovatele systému, který Vám přidělí nový token.
Budete-li chtít pro testování volat funkce z Swagger framework, autorizaci provedete tak, že do pole "api_key" v záhlaví stránky napíšte: Bearer <token>
Funkce rozhraní pracují vždy s konkrétní realitní kanceláří, která je identifikována svým guidem: Estate Agency Guid - eaguid.
Eaguid se předává v rámci URL adresy příslušné funkce, které mají podobu /api/{eaguid}/jmeno_funkce...
Každou RK, se kterou chcete v rozhraní pracovat, je potřeba nejprve vložit - zaregistrovat její eaguid. K tomu slouží funkce objektu "EstateAgencies", které jediné v rozhraní nevyžadují eaguid v rámci url adresy.
Eaguid musí být unikátní pro každou RK v rámci celého systému.
Založené RK není možné ze systému odstranit. Pokud byste toto potřebovali, obraťte se na provozovatele systému.
Ve službě ReEx má každá realitní kancelář 3 stupňovou strukturu:
Každý z těchto objektů má v rozhraní funkce, pomocí kterých je lze přidávat, aktualizovat a mazat (RK lze pouze aktualizovat).
Každý objekt, který se zasílá na exportní servery (nabídky, poptávky, developerské projekty) se vždy váže na konkrétního makléře a zároveň se samotným objektem jsou na server zasílány údaje o tomto makléři a jeho pobočce (pokud toto exportní server podporuje).
Pokud RK nemá pobočky, je třeba vkůli zachování struktury vytvořit jednu "umělou" pobočku se stejnými informacemi jako má RK a makléře vkládat pod tuto "umělou" pobočku.
Pozn: Mazání objektů se při běžné práci nepoužívá. Stažením nabídek z realitních serverů dojde i ke stažení makléřů. Ve službě ReEx tyto objekty ale zůstávají.
Na začátku je třeba zjistit, jaké exportní servery jsou ve službě ReEx k dispozici, jaké jsou jejich čísla a jiné údaje. K tomu slouží funkce objektu "TargetServer" / Full - Podrobné informace o všech exportních serverech. Tuto funkci je následně možné volat např. jednou týdně pro ověření aktuálnosti údajů. Častěji (např. jednou denně) je možné volat funkci objektu "TargetServer" - Seznam exportních serverů - základní info, pomocí které ověříte, zda příslušné servery nemají nějaké problémy a zda je možné na ně exportovat.
Aby bylo možné na vybraný server exportovat, je třeba jej nejprve aktivovat. K tomu slouží funkce objektu "TargetServer" / Activate - Aktivace účtu na exportní server pro celou RK (do funkce se předávají aktivační údaje účtu, které získáte od příslušného exportního serveru).
Takto aktivovaný účet je společný pro celou RK a exportují se na něj nabídky ze všech poboček (tzn. primární účet). Pokud má nějaká pobočka odlišný účet, je možné pro pobočku aktivovat tento účet pomocí funkce na objektu "TargetServer" / Affiliate / Activate - Aktivace účtu na exportní server pro pobočku RK.
Export nabídky by měl probíhat v těchto krocích:
Při aktualizaci nabídky se postupuje obdobných způsobem jako při vkládání nové nabídky s tím, že není třeba vkládat datové soubory (pokud v souborech nedošlo ke změně), začít tedy bodem 3 s tím že se volá funkce na objektu "Estate" - Aktualizace nabídky, které se předává Guid nabídky.
Chcete-li již jednou exportovanou nabídku zaslat na nový server či ji ze serveru stáhnout, postupujte obdobně jako při exportu nové nabídky, pouze začněte až od bodu 3. a použijte funkci na objektu "Estate" - Nastavení stavu nabídky na exportních serverech (tedy budete ukládat pouze požadavky na servery, nikoliv nabídku samotnou).
Potřebujete-li aktualizovat data o makléři, stačí zavolat funkci na objektu "Agent" - Aktualizace údajů o makléři. Služba ReEx automaticky údaje aktualizuje na jednotlivých exportní serverech u nabídek. Není tedy třeba aktualizovat všechny nabídky, u kterých je makléř připojen.
Totéž platí s aktualizací údajů o pobočce, do které makléř patří.
Služba ReEx umožňuje vkládat vodoznak do fotografií při zasílání na exportní servery, tedy do každé fotografie nabídky (dev. projektu) vloží dle nastavení např. logo RK či určitý text.
Pokud chcete tuto funkcionalitu využívat, je potřeba do systému nahrát nastavení vodoznaku a pro každou fotografie při jejím vkládání určit, zda se na ni vodoznak má aplikovat či nikoliv (položka "WithoutWatermark" při vkládání souboru).
Vodoznak může být nastavený na úrovní celé RK (položku AffiliateGuid nechte prázdnou) a každá pobočka může mít nastaven svůj vlastní vodoznak.
Vodoznaky mohou být buď textové (na příslušné místo fotografie se vloží zadaný text), nebo obrázkové.
Funkce pro vkládání, úpravu a mazání vodoznaků naleznete pod objektem "Watermark".
Pozn: Změnou vodoznaku nedojde k přeexportování fotografií, které jsou již na exportních serverech. Změna se projeví až u nově exportovaných fotografií.
Topování obecně slouží pro posunování nabídek na přední pozice na exportních serverech.
Jelikož některé exportní servery se topování brání, některé pro ně mají speciální funkce a některé je nijak neřeší, lze servery rozdělit do 3 kategorií:
Některé servery si za topování účtují speciální poplatky - ať již přímo za použití funkce topování v případu 3, nebo za vložení nabídky v případu 2. Budete-li tedy používat topování, musíte počítat s tím, že vám za něj exportní server může tyto poplatky účtovat - je proto potřeba se předem seznámit s podmínkami inzerce na exportním serveru. Z tohoto důvodu mají účty na exportní servery ve službě ReEx ve výchozím stavu zakázáno topování. Chcete-li na některý server topování použít, musíte pro příslušný účet topování povolit pomocí funkce na objektu "TargetServer" - Povolení / zakázání možnosti topování na exportní server pro RK.
Jak funguje topování
Pro topování je třeba nastavovat 2 položky:
Obě tyto položky u nové nabídky nastavte na 0.
Pokud chcete topovat na některý exportní server, postupujte následovně:
Služba ReEx při exportu na servery porovnává aktuální stamp topování (CurrentTopStamp) s požadovaným stampem RequestedTopStamp a pokud je požadovaný vyšší, je na server provedeno topování.
Z předchozího postupu vyplývá, že topování se provádí stejnou funkcí jako aktualizace nabídky. Proto také vždy při topování se provádí i aktualizace nabídky (aktualizace se provádí na všechny servery, kam je nabídky vyexportována). Ve výsledku funkce proto chodí zvlášť informace o výsledku aktualizace a zvlášť informace o výsledku topování (např. aktualizace může proběhnout bez problémů, ale k topování nedojde z důvodu nedostatečného kreditu).
Základní práce s developerskými projekty je identická jako s nabídkami. Developerský projekt se zašle do služby ReEx a poté se určuje, na který exportní server má být zaslán.
Je třeba si uvědomit, že zatímco nabídky podporují všechny exportní servery, developerské projekty podporují jen některé. V informacích o exportních serverech lze zjistit, zda developerské projekty podporuje či nikoliv.
Služba ReEx umožňuje jednotlivé nabídky zařadit do developerského projektu (u nabídky stačí vyplnit položku "DevelopmentProjectGuid"). Pokud toto podporuje i exportní server, je na něj informace předávána.
Při přiřazení nabídky do developerského projektu je potřeba hlídat, aby makléř nabídky a makléř projektu byly buď stejní, nebo aby byli ze stejné pobočky! (Jelikož každá pobočka může mít aktivovaný jiný účet na exportní server, při různých pobočkách by mohlo docházet k nekonzistentnosti při zasílání.)
Základní práce s poptávkami je identická jako s nabídkami. Poptávka se zašle do služby ReEx a poté se určuje, na který exportní server má být zaslána.
Je třeba si uvědomit, že zatímco nabídky podporují všechny exportní servery, poptávky většina exportních serverů nepodporuje. V informacích o exportních serverech lze zjistit, zda poptávky podporuje či nikoliv. Zasílání poptávek slouží primárně pro vlastní webové stránky.
Lokační zatřídění nabídky je uloženo v následujících položkách:
Položka LcVersion určuje verzi lokačního zatřídění, podle které se mají interpretovat další položky lokačního zatřídění. Existuje 5 verzí lokačního zatřídění:
Každá úroveň lokačního zatřídění má dvě položky - Id a Name. Id je identifikátor položky v příslušné databázi, Name je název této položky (např. pro ČR položky Lc3 - kraj : Lc3Id = 19, Lc3Name = "Hlavní město Praha"). Některé položky musí mít vždy vyplněn identifikátor i jméno, některé položky mají vyplněno pouze jméno (nejsou napojeny na žádnou databázi a jsou zadány pouze textově), některé položky mohou, ale také nemusí mít identifikátor vyplněn (např. ulice v ČR).
V každé lokační verzi jsou používány pouze některé úrovně položek a některé úrovně jsou prázdné (nepoužívané) (např. v ČR není používána Lc1, Lc2 a Lc8).
LcVersion = 1 - Česká republika
Data vychází z databáze RUIAN poskytované Českým úřadem zeměměřickým a katastrálním, viz https://www.cuzk.cz/ruian/RUIAN.aspx či https://vdp.cuzk.cz/.
| Položka | Popis | Způsob zadávání | Poznámka |
|---|---|---|---|
| ID1 | |||
| ID2 | |||
| ID3 | Kraj | id + text | RUIAN - VUSC |
| ID4 | Okres | id + text | RUIAN - Okres |
| ID5 | Obec | id + text | RUIAN - Obec |
| ID6 | Městská část | id + text | RUIAN - MOMC |
| ID7 | Část obce | id + text | RUIAN - Část obce |
| ID8 | |||
| ID9 | Ulice | id + text nebo pouze text | RUIAN - Ulice |
| ID10 | KÚ | id + text | RUIAN - Katastrální území |
| ID11 | PSČ | pouze text | pouze textově |
| ID12 | čp | id + text nebo pouze text | RUIAN - Stavební objekt |
| ID13 | čo | id + text nebo pouze text | RUIAN - Adresní místo |
| ID14 | Parcela | id + text | RUIAN - Parcela |
| ID15 | Druh číslování parcely | id |
1 - Stavební parcela 2 - Pozemková parcela |
| ID16 |
LcVersion = 2 - Slovenská republika
Data vychází z dat Štatistického úradu Slovenskej republiky.
Tabulky:
| Položka | Popis | Způsob zadávání | Poznámka | |
|---|---|---|---|---|
| ID1 | ||||
| ID2 | ||||
| ID3 | Kraj | id + text | ||
| ID4 | Okres | id + text | ||
| ID5 | Obec | id + text | ||
| ID6 | ||||
| ID7 | Část obce | pouze text | ||
| ID8 | ||||
| ID9 | Ulice | pouze text | ||
| ID10 | KÚ | pouze text | ||
| ID11 | PSČ | pouze text | ||
| ID12 | čp | pouze text | ||
| ID13 | čo | pouze text | ||
| ID14 | ||||
| ID15 | ||||
| ID16 |
LcVersion = 3 - Evropská unie
Databáze lokačního zatřídění EU je dostupná v přiloženém souboru EU_levels.xlsx.
| Položka | Popis | Způsob zadávání | Poznámka |
|---|---|---|---|
| ID1 | stát | id + text | |
| ID2 | Region | id + text | |
| ID3 | Oblast | id + text | |
| ID4 | Kraj | id + text | |
| ID5 | Město | pouze text | |
| ID6 | Ulice | pouze text | |
| ID7 | PSČ | pouze text | |
| ID8 | čp | pouze text |
LcVersion = 4 - USA
Databáze lokačního zatřídění USA je dostupná v přiloženém souboru USA_levels.xlsx.
| Položka | Popis | Způsob zadávání | Poznámka |
|---|---|---|---|
| ID1 | |||
| ID2 | stát | id + text | |
| ID3 | město | id + text | |
| ID4 | PSČ | id + text | |
| ID5 | Ulice | pouze text | |
| ID6 | čp | pouze text |
LcVersion = 5 - Svět
Tabulka států vychází ze standardu ISO 3166-1 (viz http://cs.wikipedia.org/wiki/ISO_3166-1, sloupečky "numeric" a "stát"). Ostatní položky jsou pouze textové.
| Položka | Popis | Způsob zadávání | Poznámka |
|---|---|---|---|
| ID1 | stát | id + text | http://cs.wikipedia.org/wiki/ISO_3166-1 |
| ID2 | Region | pouze text | |
| ID3 | Oblast | pouze text | |
| ID4 | Město | pouze text | |
| ID5 | Ulice | pouze text | |
| ID6 | PSČ | pouze text | |
| ID7 | ČP | pouze text |
Povinné položky
| CZ | SK | EU | USA | Svět | |
|---|---|---|---|---|---|
| ID1 | ano | ano | |||
| ID2 | ano | ano | |||
| ID3 | ano | ano | ano | ||
| ID4 | ano | ano | |||
| ID5 | ano | ano | |||
| ID6 | |||||
| ID7 | |||||
| ID8 | |||||
| ID9 | |||||
| ID10 | |||||
| ID11 | |||||
| ID12 | |||||
| ID13 | |||||
| ID14 | |||||
| ID15 | |||||
| ID16 |
Systém každou hodinu stahuje zájmy (dotazy odeslané klienty od konkrétních inzerátů) ze serverů, které k tomuto poskytují rozhraní a tyto zájmy zprostředkovává skrz rozhaní. K práci se zájmy lze přistupovat dvěmi způsoby: