1 - Úvod

Serverové rozhraní XML-RPC se nachází na adrese
https://www.prazskereality.cz/RPC2 nebo http://www.prazskereality.cz/RPC2
a slouží k exportu zakázek realitních kanceláří do systému PrazskeReality.cz.

Veškerá komunikace se serverem a zpět probíhá v kódování UTF-8.
Na adrese http://xmlrpc.com/spec.md se nalézá podrobná specifikace protokolu.

Zbytek dokumentu pojednává o RPC metodách, které importní rozhraní nabízí. Všem uvedeným metodám je nutno předat všechny specifikované parametry. Pokud je uvedeno, že parametr metody je nepovinný, stačí jej vyplnit podle typu prázdnou hodnotou. Počet parametrů musí odpovídat předpisu.

Vytváříte-li nový exportní software, obrat’te se na info linku (info@PrazskeReality.cz), kde vám založí testovací účet. Testovací účet vydrží 1 měsíc a je zdarma. Nelze přes něj žádným způsobem inzerovat, slouží pouze k ověření vyvíjeného exportního softwaru.

1.3 - Co je nového

Proti verzi 1.2:

• Přídáno pole pro zadávání čísla bytu apartment_number
• Nový typ inzerátu:Podíly
• Nové atributy: share_numerator, share_denominator, share_common_area_numerator, share_common_area_denominator, num_owners. Atributy share_common_area_numerator a share_common_area_denominator jsou urceny pouze pro byty.
• Přejmenovaná položka v atributu building_type: Dřevěná → Dřevostavba
• Nová položka v atributu building_type: Modulární
• Nová položka v atributu flat_class: Jednopodlažní
• Nové položky v atributu protection: Památková zóna, Památková rezervace, Kulturní památka, Národní kulturní památka
• Přejmenované položky v atributu surroundings_type: Obytná → Bydlení, Obchodní a obytná → Bydlení a kanceláře, Komerční → Administrativní
• Nová položka v atributu road_type: Není příjezdová komunikace
• Nová položka v atributu electricity: Bez přípojky
• Přejmenované položky v atributu water: Místní zdroj → Místní zdroj vody, Dálkový vodovod → Vodovod
• Nová položka v atributu water: Retenční nádrž na dešťovou vodu

Nové atributy u inzerát:

• circuit_breaker - Jističe
• commission - Provize, pro pronájmy
• ftv_panels - Fotovoltaika
• heating_element - Topné těleso
• heating_source - Zdroj topení
• internet_connection_provider - Poskytovatel internetového připojení
• internet_connection_speed - Rychlost internetového připojení (Mbit/s)
• internet_connection_type - Typ internetového připojení
• keywords - Klíčová slova
• lease_type_cb - Typ pronájmu - nájem / podnájem
• phase_distributions - Počet fází elektrického proudu
• refundable_deposit - Výše vratné kauce
• solar_panels - Solarní panely
• tenant_not_pay_commission - Nájemce neplatí provizi
• water_heat_source - Zdroj teplé vody
• well_type - Typ studny
• project_matteport_url - Odkaz na VR prohlídku na webu Matterport

Nové metody pro videa inzerátů a projektů. Nově lze přidávat k inzerátům a projektům více videí, k videu lze nahrát úvodní fotografii a určit pořadí videí

U metod pro nahrávání a mazání videa byla zachována možnost p ˚uvodního používání, jako v pˇredchozí verzi

Metody listVideo a listProjectVideo budou odstraněny a mělo by se přejít na jejich nástupce listVideos a listProjectVideos.

• addVideoPhoto a addProjectVideoPhoto pro nahrání fotky k videu
• delVideoPhoto a delProjectVideoPhoto pro smazání fotky videa
• listVideos a listProjectVideos pro výpis videí
• setVideoOrder a setProjectVideoOrder pro nastavení pořadí videí
• Metody delVideo a delProjectVideo, pro smazání videa, mají další nepovinný atribut identifikující video. Bez tohoto atributu se smaže první video.
• U metod addVideo, addProjectVideo přibyla hodnota ve struktuře odpovědi output s klíčem video_id, která obsahuje identifikátor nahrávaného videa

Proti dokumentaci PražskéReality verzi 1.1:

• přidány chybové návratové hlášky importního rozhraní řady 9XX (901 - maximální počet inzerátů dle inzertního balíčku)
• přidány chybové návratové hlášky importního rozhraní řady 9XX (901 - maximální počet inzerátů dle inzertního balíčku)
• Nový parametr project_url při importu developerských DP obsahuje webovou adresou na projekt na stránkách developera.
• Možnost zadat ruský popis inzerátu a poznámku k ceně. (položky description_ru a advert_price_text_note_ru).
• Doplnění informace o maximálním počtu fotografií
• Oprava maximálního počtu znaků v anotaci developerských projektů (položka annotation).
• Nastavení energetického štítku dle vyhlášky č. 78/2013 Sb. (položka energy_performance_certifi cate).
• Nově vracíme položku typu hash_id v metodě pro výpis inzerátů (listAdvert) jako řetězec (string)
• Přidána chybová hláška o detekci příliš velké fotografi e při jejím uploadu (metody addPhoto a addProjectPhoto, chyba číslo 410)
• Přidána chybová hláška o detekci duplicitní fotografi e při jejím uploadu (metoda addPhoto, chyba číslo 451)
• Přidána kontrola textových položek inzerátu a projektu (metody addAdvert, addProject chyba číslo 455)
• Přidání položek do číselníku advert_price_unit:
  • za m2/den (ID 9),
  • za m2/hodinu (ID 10).

Úprava číselníku advert_subtype:

• Přejmenování položky 6+kk na „6 a více“, položky 6+1, 7+1 a 7+kk sloučeny na „6 a více“.,
• Položka Jiný sloučena s Atypický.
• Přejmenování položky „Pro komerční výstavbu“ na Komerční.
• Přejmenování položky „Pro bydlení“ na Bydlení.
• Přejmenování položky „Zemědělská půda“ na Pole.
• Přejmenování položky „Trvalý travní porost“ na Louka.
• Přejmenování položky „Zemědělské objekty“ na Zemědělský.
• Přejmenování položky Jiný na Ostatní.
• Přejmenování položky „Činžovní“ na „Činžovní dům“.
• Přejmenování položky Vily na Vila.
• Odstranění položky Dřevostavby (typ dřevostavba je určen číselníkem building_type, konverze inzerátů s podkategorií Dřevostavby na podkategorii Rodinný).
• Přesun položky Nízkoenergetické do samostatné položky advert_low_energy (konverze inzerátů s podkategorií Nízkoenergetické na podkategorii Rodinný).
• Přidání položek Sady/vinice, Virtuální kancelář, Vinný sklep, Půdní prostor, Garážové stání, Mobilheim a Ostatní.

• Balkón povinný pouze pro Byty.
• Lodžie povinná pouze pro Byty.
• Bazén povinný pro Domy.
• Terasa povinná jen pro Byty.
• Přejmenování položky číselníku vlastnictví Jiné na Státní/obecní.
• Přejmenování položky „Parkovací stání“ na Parkování.
• Přejmenování položky „Bezbariérový přístup“ na Bezbariérový.
• Přejmenování položky Zařízeno na Vybavení.
• Pole auction_date_tour a auction_date_tour2 jsou nyní povinné pro Dražby.

Do číselníku auction_kind přibyly následující položky:

• Exekutorská dražba (ID 3),
• Aukce (ID 4),
• Obchodní veřejná soutěž (ID 5).

Nově přidaná pole:

• Velikost (advert_room_count),
• Poznámka k ceně v Angličtině (advert_price_text_note_en),
• Náklady na bydlení (cost_of_living),
• Typ bytu (flat_class),
• Nízkoenergetické (advert_low_energy).

Odstraněná pole:

• Stavba (estate_building_type),
• Počet objektů (object_count),
• Počet domů (house_count),
• Počet obchodů (shops),
• Počet míst (seats),
• Počet lůžek (beds),
• Počet bytů (fl ats),
• Počet volných bytů (free_fl ats),
• Počet kanceláří (offices),
• Rozměry - výška (height),
• Rozměry - délka (length),
• Rozměry - šířka (width).

Opravy oproti původním změnám:

• Odstranění pole equipment.
• Namísto sjednocení položek Jiný (ID 36) a „Historické objekty“ (ID 35) na „Památka/jiné“ (ID 36) došlo jen k přejmenování položky „Historické objekty“ (ID 35) na „Památka/jiné“ a přejmenování položky Jiné (ID 36) na „Ostatní“. ID těchto položek tedy zůstávají stejné, jako ve verzi 2.1.9.

• Aktualizovány příklady použití importního rozhraní v PHP a Pythonu. Obě varianty nyní obsahují ukázku přidání inzerátu.
• Možnost definovat lokalitu na základě RUIAN kódu (viz.1.7). Tato změna se dotkla rpc metod addProject, addAdvert, kde byly vstupní parametry rozšířeny o dva nepovinné parametry locality_ruian resp. locality_ruian_level.

• Do návratových kódů přidán kód 415 - Company is not active.
• Přidána metoda listAllDailyStat() vracející statistiky všech inzerátů daného klienta za konkrétní den.
• Možnost zadat nové nepovinné parametry pro výtah (atribut elevator) a datum prohlídky do (atribut first_tour_date_to). Všechny tyto nové atributy jsou nepovinné a tudíž jejich absence neohrozí export dat do systému PrazskeReality.cz.
• Upraven parametr bezbariérový přístup (atribut easy_access) se zachováním zpětné kompatibility k předešlým stavům. Stav false a true automaticky přetypován na 0 a 1. Přibyla hodnota číselníku 2 jejíž pomocí lze explicitně říci bez bezbariérového přístupu.
• Možnost zadat parametry pro energetický štítek náročnosti budovy pomocí 4 nepovinných atributů inzerátu. Atributy jsou:
  • energy_efficiency_rating (číselník třídy A-G), energy_performance_summary (celkový ukazatel náročnosti kWh/m2 za rok), energy_performance_attachment (příloha ve formatu .pdf nebo .jpg), energy_performance_certificate (číselník odkazuje na platnou normu).
• Při editaci hlavních položek (kdy nelze modifi kovat povinné položky) se nevrací chybový kód 452, ale nový chybový kód 484, viz kapitola 3.3. Hlavní položky jsou: advert_function (typ inzerátu) a advert_type (kategorie inzerátu).
• Rozšíření výstupu pro metody listSellerStat, listDailyStat, listStat o atribut with_vat, který určuje zda ceny jsou s nebo bez DPH.

1.2 - Názvosloví

• Klient - z pohledu importního rozhraní je klientem pobočka realitní kanceláře
• password - heslo na import, heslo potřebné k přístupu, lze nastavit v admin webu
• rkid - importní id, id z realitní kanceláře
• seller - makléř RK
• session - relace - časově omezený přístup na importní rozhraní iniciováno metodou login, ukončeno metodou logout
• session_id - řetězec znaků a čísel, který identifiuje konkrétní importní session
• software_key - SW klíč - řetězec, identifikující použitý software. Lze změnit přes obchodního zástupce
• topování inzerátu - placené zvýhodnění pozice v hledání na webu PrazskeReality.cz

1.3 - Typy dat

Prázdná hodnota je při vkládání nového objektu ekvivalentní zcela chybějící položce. Při editaci pomáhá zrušit vybranou položku, aby se neukazovala v detailu zakázky.
Poznámka: Typy date a datetime se přes XML-RPC protokol přenáší stejným typem datetime, pouze serverová strana ukládá u typu date jen část informace.

1.4 - Struktura odpovědi serveru

Všechny metody vrací strukturovaný výstup (asociativní pole), který tvoří položky output (výstupní datová struktura), status (kód chyby), statusMessage (chyba jako textový řetězec).

struct(
  [status] => 200, [statusMessage] => ’OK’, [output] => array( )
)

Obecně platí, že význam návratových kódů je podobný jako u HTTP protokolu, tedy 2xx (kód je v intervalu 200-299) informuje o dobře dopadnuvší operaci. Vyšší kódy signalizují chybu, jejichž seznam je uveden v sekci 3.3

1.5 - Autorizace

Pro přihlášení se nejprve musí zavolat metoda getHash, která inicializuje session_id. Ta se používá pro autorizaci všech importních metod. Každá importní metoda s výjimkou metody getHash a version mají jako první parametr session_id, což je řetězec identifikující relaci, který se s každým autorizovaným přístupem mění!! To znamená, že předaná hodnota session_id je už v příštím požadavku neplatná. Pro jakýkoliv nový dotaz na importní rozhraní je tedy nutné vypočítat novou hodnotu session_id z naposledy platné hodnoty.

Poznámka: Relaci vyprší platnost, pokud se více jak 15 minut nepošle žádný autorizovaný požadavek.

Session_id se skládá z fixní a variabilní části. Fixní se vytvoří při volání metody getHash a zůstává stejná po celý čas relace. Jedná se o prvních 48 znaků sessionId. Variabilní část je vypočtena pomocí funkce MD5 běžně používanou na hashování dat, do které vstupuje současné session_id a heslo.

Postup výpočtu nového session_id:

fixedPart = session_id[0:48]
varPart = md5(session_id + md5(password) + software_key) session_id
= fixedPart + varPart 

1.6 - Identifikace inzerátu, obecné vazby

Pro identifikaci slouží dva druhy id, dají se odlišit pomocí přípony:

_id - interní id v databázi - unikátní v celém univerzu
_rkid - id realitní kanceláře (RK), pod kterým jej zná klient - unikátní v rámci jednoho klienta, tedy jedné pobočky RK Takto se identifikují makléři, inzeráty, dev. projekty a fotografie.

Použití advert_rkid u metody addAdvert říká, že edituji inzerát, který odpovídá danému id. Pokud uvádím advert_rkid u metody addPhoto, říkám, že fotografii chci svázat s příslušným inzerátem.

Rozdíl v chování _id proti _rkid je patrný hlavně při přidávání.

Příklady dvou druhů adresací:

• advert_rkid předávám vždy naplněné. Pokud pod takovým id inzerát již existuje, jedná se o editaci, pokud ne, vytvoří se nový a přidělí se mu předané id.
• advert_id posílám prázdné, pokud chci inzerát přidat a naplněné interním id inzerátu v případě editace.

1.7 - Zadávání lokality

Klasické zadání adresy znamená, co nejpřesněji uvést všechny položky týkající se adresy (locality_city - město, locality_street - ulice, locality_co - číslo orientační, locality_cp - číslo popisné). Adresa je ověřena proti databázi adres serveru mapy.cz a pokud není jednoznačně zadaná, vrací se chyba.

Díky tomuto ověření je adresa inzerátu validována a lze podle zadaných údajů spolehlivěji hledat, protože atributy jako kraj a okres, případně jiné nevyplněné atributy, jsou automaticky do- plněny na základě informací z map.

Zadání přes UIR-ADR nově i přes RUIAN-ADR celou věc zjednodušuje na pouhé získání detailů o zadaném RUIAN(UIR), které se vepíší do příslušných kolonek. Více informací je uvedeno níže v kapitole 1.7.

Důležité: Oba tyto způsoby vyžadují co nejpřesnější zadání adresy. Ale ne vždy je přesná šipka na mapě žádoucí. Proto lze zadat ještě atribut locality_inaccuracy_level, který říká jak moc je dobré znepřesnit adresu pro zobrazení na mapě.

Tento parametr má 3 možné hodnoty:

1. adresa je zobrazena přesně dle zadání;
2. adresa je o 1 stupeň znepřesněna, místo přesné adresy se ukazuje ulice, případně obec, podle toho, který nadřazený prvek je logicky nejblíže;
3. adresa je o 2 stupně znepřesněna, místo přesné adresy se ukazuje na mapách část města.

GPS souřadnice - Posledním druhem je zadání adresy přes GPS souřadnice (locality_longitude, locality_latitude). Používá se v situacích, kdy není ještě oblast zaměřena v mapách. Zadává se jako zeměpisná šířka a výška ve stupních. Minuty a vteřiny jsou vyjádřeny desetinnou částí. Předpokládá se vždy šířka severní a délka východní. Nevýhoda tohoto zadání spočívá v tom, že inzerát je svázán pouze s okresem a krajem, ale nikoliv s městem či ulicí, která je nejblíže. Inzerát je spolehlivě dohledatelný pouze pomocí funkce hledat v okolí.

Zahraniční nemovitosti: Importovat lze i zahraniční nemovitosti. V takovém případě je vhodné posílat s městem nejlépe i zemi, ve které se nachází. Jelikož se lokalita validuje proti databázi mapy.cz, jsme omezeni jen na Evropu.

Adresa UIR-ADR a RUIAN-ADR Adresy je nutno specifikovat na město (případně městskou část), byty až na číslo popisné nebo číslo orientační. Ministerstvo práce a sociálních věcí ve spolupráci s obecními úřady udržuje registr adres všech stavebních objektů, které mají číslo domovní.

Česká pošta poskytuje pro adresy platná poštovní smeřovací čísla. Ministerstvo práce a sociálních věcí dává tento registr k dispozici veřejnosti. Kromě zpřístupnění dat registru na www stránkách MPSV (http://forms.mpsv.cz/uir/) je možno získat zdarma CD-ROM s daty a programy pro prohlížení a periodickou aktualizaci těchto dat. Informace o RUIAN kódu je možné získat na www adrese (http://www.ruian.cz). Při použití RUI- AN(UIR) kódu není nutno vyplňovat adresu, kromě případu, kdy RUIAN(UIR) kód není dostatečně podrobný, pak je možno adresu upřesnit textově. (Příklad: K bytu máme k dispozici RUIAN(UIR) kód na úrovni 5, je tedy potřeba doplnit položky locality_street, locality_cp. V případě, že bychom doplnili i locality_city, nebude bráno v potaz a naopak bude přepsáno hodnotou z RUIAN(UIR)).

Popis UIR se předává pomocí parametrů locality_uir (vlastní uir) a locality_uir_level (přesnost, typ). Popis RUIAN se předává pomocí parametrů locality_ruian (vlastní ruian) a locality_ruian_level (přesnost, typ). Odpovídající hodnoty parametrů locality_ruian_level resp. locality_uir_level naleznete v tabulce níže.

Zadání lokality pomocí RUIAN parametrů má vyšší prioritu než-li zadání lokality pomocé UIR parametrů. V případě neúspěchu při získávání lokality pomocí RUIAN parametrů se server pokouší získat lokalitu pomocí UIR parametrů. Naopak v případě úspěchu pro RUIAN vstupní parametry server ignoruje UIR parametry.

1.8 - Vkládání videoprohlídek

PrazskeReality.cz podporují vkládání videozáznamů do inzerátů a developerských projektů ve spolupráci se službou youtube.com. Vždy maximálně jedno video na inzerát/projekt. Každé uploadované video se musí vždy nejdříve zpracovat, což znamená převést do různých kvalit a připravit tak výdej pro přehrávač. Doba zpracování každého videa se mění od tří do deseti minut v závislosti na délce videozáznamu a také na denní době. Než se video překóduje do příslušných kvalit pro naše přehrávače, tak video nelze vidět ani ho modifikovat. Pokud překódování trvá déle jak hodinu, dostává video příznak Timeout a nadále se s nim už na Prazských Realitách nepočítá.

Uploadované video tedy není v detailu inzerátu či developerského projektu vidět ihned po zveřejnění, ačkoliv inzerát už zveřejněný je a všechny fotografie jsou již přístupné. Pro exportní softwary proměnlivá délka zpracování znamená, že se nedozví výsledek operace. 200 OK u addVideo znamená, že se povedlo vložit video do fronty požadavků ke zpracování. Nepodporovaný formát případně jinou chybu je možné získat až s časovým odstupem, což není št’astné pro automatizované nástroje.

Doporučený postup je stejný jako při práci s fotografiemi. V rámci aktualizace nabídky nejdříve zjistit již přítomné videoprohlídky (listVideo) a následně přidat, resp. odebrat videozáznam podle zjištěných rozdílů (addVideo, resp. delVideo).

Maximální velikost video souboru je 150MB, podporované formáty lze dohledat na v kapitole 3.5. Zjednodušeně se dá říct, že se podporují všechny formáty knihovny ffmpeg.

2 - Metody

2.1 - Autorizační metody

2.1.1 - getHash( client_id as int )

Získání řetězce zvaného sessionId, který je použit pro hashování hesla.

Metoda slouží k získání řetězce pro hashování hesla. Po zavolání s existujícím client_id je vrácen status 200 a v output je sessionId a hashovací klíč. Volá se vždy na začátku relace.

struct { 
    int status => Status (200 = Ok; 402 = nexistující klient)
    string statusMessage => Slovní popis statusu
    array struct output(
        string sessionId => Identifikace spojení
    )
}

2.1.2 - login( session_id as string )

Potvrzení přihlášení.

Metoda login potvrdí session jako autorizovanou. V kladném případě se ověří, že výpočet nového session_id odpovídá očekávání na straně serveru.

Metodě login se předávají parametry session_id z metody getHash. Pozor, session_id už musí být přepo- čítáno pomocí vzorečku. Softwarový klíč je přidělen administrátorem pražských realit zvlášt’ pro každého klienta (RK) v závislosti na použitém export- ním software. Nazpět je vrácen status úspěšnosti.

Poznámka: Bez úspěšně dokončené metody login je celá importní relace ve stavu nepřihlášen a tedy nelze v exportu zakázek pokračovat.

Vrací-li metoda opakovaně 407 Bad session je špatně zadané heslo, importní klíč a nebo client_id u klienta nebo na importním serveru. Je třeba zkontrolovat tyto údaje. Heslo na import si nastavuje klient sám, import- ní klíč lze měnit přes obchodního zástupce, clientid bylo fi rmě přiděleno.

struct { 
    int status => Status ( 200=OK 402=Neexistujici klient 405=Neplatný klič softwaru 407=Neplatné přihlášení)
    string statusMessage => Slovní popis statusu.
    array struct output ()
}

2.1.3 - logout( session_id as string )

Odhlášení.

struct { 
    int status => Status ( 200=Odhlášení je OK)
    string statusMessage => Slovní popis statusu.
    array struct output ()
}

2.2 - Správa inzerátů

2.2.1 - addAdvert( session_id as string, advert_data as struct )

Přidání / editace inzerátu.

Metodě se předává slovník advert_data, který v sobě nese veškeré číselníkové i nečíselníkové údaje o inzerátu. Možné atributy inzerátu jsou vypsány v tabulce 1 v kapitole 3.1. Pokud chybí povinná položka, addAd- vert končí s chybou. Pozor, některé položky jsou povinné v závislosti na typu (kategorii) inzerátu.

Pozor, datová struktura advert_data nemusí obsahovat všechny předepsané atributy, jsou vyžadovány pouze povinné atributy. Pokud atribut není ve slovníku obsazen, server odpovídající položku nechává nedotčenou. Tedy nemění samovolně její hodnotu.

Metoda vrací status a advert_id, které je vhodné si uchovat pro další operace s uloženým inzerátem. Pokud je vyplněn parametr advert_rkid, musí být v rámci inzerce konkrétního klienta unikátní. Tento parametr obsahuje vlastní identifikátor inzerátu a tento identifikátor lze v budoucnu použít pro práci s inzerátem přes importní rozhraní, kde plně zastupuje advert_id. Editace inzerátu se zajistí vyplněním advert_id již uloženého inzerátu, nebo je možno zadat existující advert_rkid (viz kapitola 1.6). Adresu inzerátu lze vyplnit více způsoby: klasické zadání, RUIAN(UIR-ADR), GPS souřadnice, viz kapitola 1.7.

Poznámka: Pokud zadáte cenu 0 nebo 1, bude místo ceny zobrazeno Info o ceně u RK.

struct { 
    int status => Status ( 200=OK, 404=Inzerat pro tuto RK neexistuje, 407=Neplatné přihlášení, 452=Nekompletní data k inzeratu, 455=Nevalidní textová položka inzerátu, 461=Makléř neexistuje, 484=Hlavní položky již není možné modifikovat, 491=Projekt neexistuje, 901=Dosažen maximální počet inzerátů dle inzertního balíčku)
    string statusMessage => Slovní popis statusu.
    array struct output (int advert_id => Číslo inzerátu)
}

Metoda addAdvert při zpracování vstupních parametrů kontroluje maximální počet znaků a detekuje nevhodná slova u některých textových položek. V případě neúspěšné kontroly vrací metoda addAdvert status kód 455. V tabulce uvedené níže je výčet textových položek u kterých probíhá kontrola během zpracování inzerátu:

2.2.2 - delAdvert( session_id as string, advert_id as int, advert_rkid as string )

Vymazání inzerátu.

Pomocí advert_id nebo advert_rkid se identifikuje inzerát (viz kapitola 1.6). Uložené fotografie u inzerátu a statistiky budou smazány. Pokud inzerát neexistuje bude vrácen status OK (200).

Poznámka: Inzeráty nejsou smazány ihned po zavolání této metody, aktuálně se drží ještě po dobu 21 dní než se opravdu smažou.

struct { 
    int status => Status ( 200=OK, 407=Neplatné přihlášení, 452=Nejsou vyplněny všechny povinné položky nebo jsou špatného typu)
    string statusMessage => Slovní popis statusu.
    array struct output ()
}

2.2.3 - listAdvert( session_id as string )

Výpis všech inzerátů přihlášené realitní kanceláře.

V output je vráceno pole, kde každý prvek pole obsahuje strukturu (viz níže). Inzeráty jsou seřazeny podle pořadí vložení.

struct { 

int status => Status ( 200=OK, 407=Neplatné přihlášení, 452=Nejsou vyplněny všechny povinné položky nebo jsou špatného typu)

string statusMessage => Slovní popis statusu.

array struct output (
    int advert_id => číslo inzerátu,
    string advert_rkid => interní číslo realitky,
	string advert_url => odkaz na detail inzerátu na serveru,
	int advert_type => druh inzerátu (byty, pozemky...) podle dokumentace,
	string hash_id => veřejné číslo inzerátu,
	string modified => datum poslední editace(format datumu: YYYY-MM-DD),
	int published => 1=inzerát zveřejněný, 0=inzerát nezveřejněný,
	int published_status => status kód - důvod nezveřejnění inzerátu(viz Status kódy inzerátu),
	int top => inzerát je/není dnes zvýhodněn[0/1]
    )
}

2.2.4 - topAdvert( session_id as string, advert_id as int, advert_rkid as string )

Nastavit zvýhodnění inzerátu pro aktuální den.

Pomocí advert_id nebo advert_rkid se identifikuje inzerát (viz kapitola 1.6). Zvýhodnění inzerátu (tzv. topování) je možnost inzerát umístit do horních pozic ve výpise inzerátu. Topování je zpoplatněno dle aktuálního ceníku. Inzerát lze „topovat“ jen jednou denně nebo dle aktuálních podmínek. Nelze topovat v den vložení inzerátu, ani pokud není inzerát zveřejněn. Také inzerát označený jako duplicitní s nesmazaným originálem nelze zvýhodnit. Nelze zvýhodnit (topovat) nezveřejněný nebo neschválený inzerát.

struct { 
    int status => Status (
		200 = OK,
		404 = inzerát nenalezen,
		407 = neplatné přihlášení,
		452 = nejsou vyplněny všechny položky nebo jsou špatného typu
		477 = Nelze topovat v den vložení
		478 = Nelze zvýhodnit(topovat) inzerát označený jako duplicitní
		479 = Nelze topovat nezveřejněný inzerát
		482 = Dnes již byl inzerát zvýhodněn
	)

	string statusMessage => Slovní popis statusu.
	array struct output ()
}

2.3 - Správa fotek u inzerátů

2.3.1 - addPhoto( session_id as string, advert_id as int, advert_rkid as string, data as struct )

Vložení fotografie k již uloženému inzerátu.

Vstupními parametry jsou advert_id nebo advert_rkid a struktura data:

struct data

binary data => vlastní obrázek

int main => 1 = hlavní fotka, 0 = ostatní

int order => nepovinné pořadí v rámci vedlejších fotek 

string alt => nepovinný údaj, popisek obrázku

int photo_id => nepovinný údaj, interní id fotky

string photo_rkid => nepovinný údaj, rkid fotky

Pomocí advert_id nebo advert_rkid se identifikuje inzerát (viz kapitola 1.6). Výstupem je photo_id, které je vhodné si uložit pro mazání fotky. Pokud je vkládána vedlejší fotografie, a přitom není u inzerátu žádná, stává se tato automaticky hlavní fotografií. Pokud je vkládána hlavní fotografie, a přitom u inzerátu již jedna je, stane se vložená fotka fotkou hlavní. Minimální rozlišení fotografie je 320x240 a maximální velikost souboru je 5 MB. Pro publikování inzerátu není nutné vkládat fotografie, takovýto inzerát bude zobrazen s tzv. no-image obrázkem. Maximální počet fotografií je 100. Po překročení této velikosti server vrací chybu a fotografii nezpracuje. Je možné obrázek pouze editovat, což znamená, že se nepřikládá vlastní obrázek, pouze se editují jeho parametry (hlavní, pořadí, popisek).

Pro snadnější orientaci se dá vložit photo_rkid, pomocí kterého se později fotka adresuje.

struct { 
    int status => Status (
    	200 = OK,
    	404 = inzerát nenalezen,
    	407 = neplatné přihlášení,
    	410 = Obrázek je příliš velký
    	412 = Šířka nebo výška obrázku je příliš malá
    	450 = Fotka patří k jinému inzerátu
    	451 = Fotku nelze přidat jelikož je duplicitní
    	452 = Nejsou vyplněny všechny povinné položky nebo jsou špatného typu
    	476 = Není to JPEG/GIF/PNG obrázek
    )

    string statusMessage => Slovní popis statusu.

    array struct output (
    	int photo_id => číslo fotografie
    )
}

2.3.2 - delPhoto( session_id as string, photo_id as int, photo_rkid as string ) Vymazání fotografie.

Pomocí photo_id nebo photo_rkid se identifikuje fotografie (viz kapitola 1.6). Pokud je mazána hlavní fotografie, hlavní se automaticky stane první vedlejší. Pokud fotografie neexistuje bude vrácen status OK (200).

struct { 
    int status => Status (
    	200 = OK,
    	404 = inzerát nenalezen,
    	407 = neplatné přihlášení,
    	452 = Nejsou vyplněny všechny povinné položky nebo jsou špatného typu
    )

    string statusMessage => Slovní popis statusu.

    array struct output ()
}

2.3.3 - listPhoto( session_id as string, advert_id as int, advert_rkid as string ) Výpis fotografie existujícího inzerátu**.**

Pomocí advert_id nebo advert_rkid se identifikuje makléř (viz kapitola 1.6). V output je vráceno pole, kde každý prvek pole obsahuje strukturu (viz níže). Fotografie jsou seřazeny podle pořadí (atribut order) a v tomto pořadí se ukazují i na webu.

struct { 
    int status => Status (
    	200 = OK,
    	404 = inzerát nenalezen,
    	407 = neplatné přihlášení,
    	452 = Nejsou vyplněny všechny povinné položky nebo jsou špatného typu
    )
    
    string statusMessage => Slovní popis statusu.
    
    array struct output (
    	int photo_id => interní id fotografie
    	string photo_rkid => id fotografie realitky
    	int main => hlavní fotografie (1 = ano, 0 = ne)
    	int order => pořadí (0 = na konci, 1 = hlavní, 2...50 = pořadí
    )
}

2.4 - Správa videoprohlídek u inzerátů

2.4.1 - addVideo( session_id as string, advert_id as int, advert_rkid as string, data as struct )

Vložení videoprohlídky k již uloženému inzerátu.

struct { 
    string video_name => Nepovinný údaj, orientační pojmenování videa 
    int video_order => Nepovinný údaj, pořadí videa 
    binary video_data => Povinná data, vlastní datový záznam 
}

Vstupními parametry jsou advert_id nebo advert_rkid a struktura video_data obsahuje vlastní video. Pomocí advert_id nebo advert_rkid se identifikuje inzerát (viz kapitola 1.6). Nepovinný údaj video_name se používá pouze k internímu označení videa. Objevuje se pouze při volání metody listVideo, není zveřejněn.

Maximální velikost datového záznamu je 150MB. Po překročení této velikosti server vrací chybu a video nezpracuje. Zpracování je blíže popsáno v kapitole 1.8, podporované formáty lze nalézt v kapitole 3.5.

struct { 
    int status => Status (
    	200 = OK,
    	404 = inzerát nenalezen,
    	407 = neplatné přihlášení,
    	413 = Příliš velký video soubor
    	420 = Aktuální video se stále zpracovává
    	452 = Nejsou vyplněny všechny povinné položky nebo jsou špatného typu
    )

    string statusMessage => Slovní popis statusu.

    array struct output { int video_id => id videa}
 }

2.4.2 - delVideo( session_id as string, advert_id as int, advert_rkid as string, video_id as int)

Vymazání videoprohlídky.

Pomocí advert_id nebo advert_rkid se identifikuje inzerát (viz kapitola 1.6). Pomocí video_id se identifikuje video. Položka není povinná a bez jejího vyplnění se smaže první video. Pokud video neexistuje, bude vrácen status OK (200)

struct { 
    int status => Status (
    	200 = OK,
    	404 = inzerát nenalezen,
    	407 = neplatné přihlášení,
    	420 = Aktuální video se stále zpracovává
    	452 = Nejsou vyplněny všechny povinné položky nebo jsou špatného typu
    )

    string statusMessage => Slovní popis statusu.

    array struct output ()
}

2.4.3 - listVideo( session_id as string, advert_id as int, advert_rkid as string )

Získání informací o videoprohlídkách existujícího inzerátu.

Pomocí advert_id nebo advert_rkid se identifikuje inzerát (viz kapitola 1.6). V output je vráceno pole, které má 0-1 prvků. Prázdné pole se vrací v případě, že inzerát nemá u sebe žádné video.

struct { 
    int status => Status (
    	200 = OK,
    	404 = inzerát nenalezen,
    	407 = neautorizovaný přístup
    	452 = Nejsou vyplněny všechny povinné položky nebo jsou špatného typu
    )

    string statusMessage => Slovní popis statusu.
 
    array struct output (
        string video_name => symbolické jméno vložené v addVideo
        int video_state => stav zpracování videa
        int video_length => délka zpracovaného video v sekundách
    )
}

2.4.4 - addVideoPhoto( session_id as string, advert_id as int, advert_rkid as string, data as struct )

Vložení fotografie k videu

Vstupními parametry jsou advert_id nebo advert_rkid a struktura data:

struct data { 
    binary data => Vlastní obrázek
    int video_id => id videa
}

Pomocí advert_id nebo advert_rkid se identifikuje inzerát (viz kapitola 1.6). Pomocí video_id se identifikuje video. Minimální rozlišení fotografie je 480x360.

struct { 

    int status => Status (
    	200 = OK,
    	404 = inzerát nenalezen,
    	407 = neautorizovaný přístup
    	452 = Nejsou vyplněny všechny povinné položky nebo jsou špatného typu
    )

    array struct output ()
}

2.4.5 - delVideoPhoto( session_id as string, advert_id as int, advert_rkid as string, data as struct )

Vymazání fotografie k videu

Pomocí advert_id nebo advert_rkid se identifikuje inzerát (viz kapitola 1.6). Pomocí video_id se identifikuje video.

struct { 
    int status => Status (
    	200 = OK,
    	404 = inzerát nenalezen,
    	407 = neautorizovaný přístup
    	452 = Nejsou vyplněny všechny povinné položky nebo jsou špatného typu
    )

    array struct output ()
}

2.4.6 - setVideoOrder( session_id as string, advert_id as int, advert_rkid as string, data as array )

Nastavení pořadí videí. Je potřeba uvést všechna videa, která jsou k inzerátu přiřazena

Pomocí advert_id nebo advert_rkid se identifikuje inzerát (viz kapitola 1.6).

array data [
id_videa1, id_videa2, id_videa3, ...
]

struct { 
    int status => Status (
    	200 = OK,
    	404 = inzerát nenalezen,
    	452 = Nejsou vyplněny všechny povinné položky nebo jsou špatného typu
    )
    array struct output ()
}

2.4.7 - listVideos( session_id as string, advert_id as int, advert_rkid as string)

Získání informací o videoprohlídkách existujícího inzerátu.

Pomocí advert_id nebo advert_rkid se identifikuje inzerát (viz kapitola 1.6). V output je vráceno pole. Prázdné pole se vrací v případě, že inzerát nemá u sebe žádné video.

struct { 

int status => Status (
	200 = OK,
	404 = inzerát nenalezen,
	407 = neautorizovaný přístup
	452 = Nejsou vyplněny všechny povinné položky nebo jsou špatného typu
)

array struct output (
    string video_name => symbolické jméno vložené v addVideo
    int video_state => stav zpracování videa
    int video_length => délka zpracovaného videa v sekundách
    int video_id => id videa
    int video_order => pořadí videa číslované od 0
    int video_image => náhled na fotografii, která se bude zobrazovat jako úvodní fotografie videa
    int video_description => popis videa
)
}

2.5 - Správa makléřů

2.5.1 - addSeller( session_id as string, seller_id as int, seller_rkid as string, client_data as struct )

Přidání nového makléře. Aby makléř byl vložen, je potřeba vyplnit povinné položky v rámci struktury client_data.

struct client_data{ 
    string client_login => emailový účet, kterým se dá přihlásit na prazskereality.cz
    string client_domain => nepovinný údaj, doména pro login. Lze ji uvést přímo do client_login
    string client_name => jméno makléře
    string contact_gsm => mobil makléře
    string contact_gsm_code => nepovinný údaj, mezinárodní předvolba makléře
    string contact_phone =>nepovinný údaj telefon
    string contact_phone_code =>nepovinný údaj mezinárodní předvolba
    string contact_email => nepovinný údaj, kontaktní email se může lišit
    string makléř_note => nepovinný údaj, poznámka
    string broker_specialization => nepovinný údaj, specializace makléře
    binary photo => nepovinný údaj, obrázek makléře
}

Pomocí seller_id nebo seller_rkid se identifikuje makléř (viz kapitola 1.6). Při vkládaní inzerátu, pokud má vlastního makléře, je tedy na výbeř mezi seller_rkid a seller_id. Ostatní položky ze struktury client_data jako contact_phone (telefon), makléř_note (poznámka makléře), broker_specialization (specializace makléře) a photo (fotografi e makléře) jsou nepovinné. U korektně vloženého makléře je získáno seller_id číslo.

struct { 
    int status => Status (
    	200 = OK,
    	407 = Neplatné přihlášení
    	452 = Nejsou vyplněny všechny povinné položky nebo jsou špatného typu
    	461 = Makléř neexistuje
    	462 = Login makléře je již použit
    	476 = Není to JPEG/PNG obrázek
    )

    string statusMessage => Slovní popis statusu.

    array struct output (
        int seller_id => číslo makléře
    )
}

2.5.2 - delSeller( session_id as string, seller_id as int, seller_rkid as string )

Odebrání existujícího makléře.

Odstranění proběhne při vyplnění seller_id nebo seller_rkid. Pomocí seller_id nebo seller_rkid se identifikuje makléř (viz kapitola 1.6).

struct { 
    int status => Status (
        200 = OK,
        407 = Neplatné přihlášení,
        461 = Makléř neexistuje,
    )
    string statusMessage => Slovní popis statusu.
    array struct output ()
}

2.5.3 - listSeller( session_id as string )

Výpis makléřů.

V output je vráceno pole, kde každý prvek pole obsahuje strukturu (viz níže). Makléři jsou seřazeny podle pořadí vložení.

struct { 
    int status => Status (
    	200 = OK,
    	407 = Neplatné přihlášení,
    )

    string statusMessage => Slovní popis statusu.

    array struct output (
        int seller_id => číslo makléře,
        string seller_rkid => interní číslo rk makléře,
        string client_name => jméno a přijmení makléře,
        string client_login => login(email) makléře,
        int photo => fotografie[1 - ano; 0 - ne],
    )
}

2.6 - Správa developerských projektů

2.6.1 - addProject( session_id as string, project_data as struct ) Přidání nového developerského projektu

Metodě se předává slovník project_data, který v sobě nese veškeré číselníkové i nečíselníkové údaje o projektu. Tyto atributy naleznete v tabulce 2 v kapitole 3.2. Pokud chybí povinná položka, addProject končí s chybou.

Metoda vrací status a project_id, které je dobré si uchovat pro další operace s uloženým projektem. Pokud je vyplněn parametr project_rkid, musí být v rámci inzerce konkrétního klienta unikátní. Tento parametr obsahuje vlastní identifikátor projektu a tento identifikátor lze v budoucnu použít pro práci s projektem přes importní rozhraní, kde plně zastupuje project_id. Editace projektu se zajistí vyplněním project_id již uloženého projektu, nebo je možno zadat existující project_rkid (viz kapitola 1.6). Adresu projektu lze vyplnit více způsoby: klasické zadání, RUIAN(UIR-ADR), GPS souřadnice (viz kapitola 1.7).

Poznámka: Atribut developer_ic (IČ developerské společnosti), který je povinný a slouží ke svázání projektu s developerem, se kontroluje, zda IČ developera bylo evidováno v systému. Registrace developera do systému není přes importní rozhraní možná. Pouze přes obchodního zástupce.

Metoda addProject při zpracování vstupních parametrů kontroluje maximální počet znaků a detekuje nevhodná slova u některých textových položek. V případě neúspěšné kontroly vrací metoda addProject status kód 455. V tabulce uvedené níže je výčet textových položek u kterých probíhá kontrola během zpracování projektu:

struct { 
    int status => Status (
    	200 = OK,
    	404 = Projekt nenalezen
    	407 = Neplatné přihlášení
    	452 = Nejsou vyplněny všechny povinné položky nebo jsou špatného typu
    	455 = Nevalidní textová položka
    	471 = IČ developera nenalezeno
    )

    string statusMessage => Slovní popis statusu.

    array struct output (
        int seller_id => číslo makléře,
        int project_id => Číslo projektu,
    )
}

2.6.2 - delProject( session_id as string, project_id as int, project_rkid as string )

Odebrání existujícího developerského projektu.

Pomocí project_id nebo project_rkid se identifi kuje projekt (viz kapitola 1.6), který má být smazán. Uložené fotografi e u projektu budou smazány.

struct { 
    int status => Status (
    	200 = OK,
    	404 = Projekt nenalezen
    	407 = Neplatné přihlášení
    	452 = Nejsou vyplněny všechny povinné položky nebo jsou špatného typu
    )
    string statusMessage => Slovní popis statusu.
    array struct output ()
}

2.6.3 - listProject( session_id as string )

Výpis developerských projektů.

V output je vráceno pole, kde každý prvek pole obsahuje strukturu (viz níže). Projekty jsou seřazeny podle pořadí vložení.

struct { 
    int status => Status (
    	200 = OK,
    	407 = Neplatné přihlášení
    )

    string statusMessage => Slovní popis statusu.

    array struct output (
        int project_id => Číslo projektu,
        string project_rkid => Interní číslo realitky,
        string project_name => název projektu,
    )
}

2.7 Správa fotek u developerských projektů

2.7.1 addProjectPhoto( session_id as string, project_id as int, project_rkid as string, data as struct )

Vložení fotografie k již uloženému developerskému projektu.

Vstupními parametry jsou project_id nebo project_rkid a struktura data.

struct data{ 
    binary data => vlastní obrázek
    int main => 1 = hlavní, 0 = ostatní
    int order => nepovinné pořadí v rámci vedlejších fotek
    string alt => nepovinný údaj, popisek obrázku
    int photo_id => nepovinný údaj, interní id fotky
    string photo_rkid => nepovinný údaj, id fotky realitky
}

Pomocí project_id nebo project_rkid se identifikuje projekt (viz kapitola 1.6). Výstupem je photo_id, které je výhodné si uložit pro mazání fotky. Pokud je vkládána vedlejší fotografie, a přitom není u projektu žádná, stává se tato automaticky hlavní fotografií. Pokud je vkládána hlavní fotografie, a přitom u projektu již jedna je, stane se vložená fotka fotkou hlavní. Minimální rozlišení fotografie je 320x240 a maximální velikost souboru 5 MB. Po překročení této velikosti server vrací chybu a fotografii nezpracuje.

Je možné obrázek pouze editovat, což znamená, že se nepřeukládá vlastní obrázek, pouze se editují jeho parametry (hlavní, pořadí, popisek).

Pro snadnější orientaci se dá vložit photo_rkid, pomocí kterého se později fotka adresuje.

struct { 
    int status => Status (
    	200 = OK
    	404 = Projekt nebo fotografie neexistuje
    	407 = Neplatné přihlášení
    	410 = Obrázek je příliš velký
    	412 = Šířka nebo výška obrázku je příliš malá
    	450 = Fotka patří k jinému projektu
    	452 = Nejsou vyplněny všechny povinné položky nebo jsou špatného typu
    	476 = Není to JPEG/GIF/PNG obrázek
    )
    string statusMessage => Slovní popis statusu.
        array struct output (
            int photo_id => Číslo fotografie,
    )
}

2.7.2 delProjectPhoto( session_id as string, photo_id as int, photo_rkid as string )

Vymazání fotografie.

Pomocí photo_id nebo photo_rkid se identifikuje fotografie (viz kapitola 1.6). Pokud je mazána hlavní fotografie, hlavní se automaticky stane první vedlejší. Pokud fotografie neexistuje bude vrácen status OK (200).

struct { 
    int status => Status (
    	200 = OK
    	407 = Neplatné přihlášení
    	452 = Nejsou vyplněny všechny povinné položky nebo jsou špatného typu
    )
    string statusMessage => Slovní popis statusu.
    array struct output ()
}

2.7.3 listProjectPhoto( session_id as string, project_id as int, project_rkid as string )

Výpis fotografie existujícího developerského projektu.

Pomocí project_id nebo project_rkid se identifikuje projekt (viz kapitola 1.6). V output je vráceno pole, kde každý prvek pole obsahuje strukturu (viz níže). Fotografie jsou seřazeny podle pořadí (atribut order) a v tomto pořadí se ukazují i na webu.

struct { 
    int status => Status (
    	200 = OK
    	404 = Projekt nebo fotografie neexistuje
    	407 = Neplatné přihlášení
    	452 = Nejsou vyplněny všechny povinné položky nebo jsou špatného typu
    )
    string statusMessage => Slovní popis statusu.
    array struct output (
        int photo_id => Číslo fotografie,
        string photo_rkid => id fotografie realitky,
        int main => hlavní fotografie(1 = ano, 0 = ne)
        int order => pořadí(0 = na konci, 1 = hlavní, 2..50 = pořadí)
    )
}

2.8 - Správa videoprohlídek u developerských projektů

2.8.1 - addProjectVideo( session_id as string, project_id as int, project_rkid as string, data as struct )

Vložení videoprohlídky k již uloženému developerskému projektu.

struct { 
    string video_name => Nepovinný údaj, orientační pojmenování videa,
    int video_order => Nepovinný údaj, pořadí videa,
    binary video_data => Povinná data, vlastní datový záznam,
}

Vstupními parametry jsou project_id nebo project_rkid a struktura video_data obsahuje vlastní video. Pomocí advert_id nebo advert_rkid se identifikuje projekt (viz kapitola 1.6). Nepovinný údaj video_name se používá pouze k internímu označení videa. Objevuje se pouze při volání metody listProjectVideo, není zveřejněn.

Maximální velikost datového záznamu je 150MB. Po překročení této velikosti server vrací chybu a video nezpracuje. Zpracování je blíže popsáno v kapitole 1.8.

struct { 
    int status => Status (
    	200 = OK,
    	404 = Projekt nenalezen
    	407 = Neplatné přihlášení
    	413 = Příliš velký video soubor
    	420 = Aktuální video se stále zpracovává
    	452 = Nejsou vyplněny všechny povinné položky nebo jsou špatného typu
    )
    string statusMessage => Slovní popis statusu.
    array struct output ()
}

2.8.2 - delProjectVideo( session_id as string, project_id as int, project_rkid as string, video_id as int )

Vymazání videoprohlídky.

Pomocí project_id nebo project_rkid se identifikuje dev. projekt (viz kapitola 1.6). Pomocí video_id se identifikuje video. Položka není povinná a bez jejího vyplnění se smaže první video. Pokud video neexistuje, bude vrácen status OK (200)

struct { 
    int status => Status (
    	200 = OK
    	404 = Projekt nenalezen
    	407 = Neplatné přihlášení
    	420 = Aktuální video se stále zpracovává
    	452 = Nejsou vyplněny všechny povinné položky nebo jsou špatného typu
    )
    string statusMessage => Slovní popis statusu.
    array struct output ()
}

2.8.3 - listProjectVideo( session_id as string, project_id as int, project_rkid as string )

Získání informací o videoprohlídkách existujícího developerského projektu. Pomocí project_id nebo project_rkid se identifikuje dev. projekt (viz kapitola 1.6).

V output je vráceno pole, které má 0-1 prvků. Prázdné pole se vrací v případě, že projekt nemá u sebe žádné video.

struct { 
    int status => Status (
    	200 = OK
    	404 = Projekt nenalezen
    	407 = Neplatné přihlášení
    	452 = Nejsou vyplněny všechny povinné položky nebo jsou špatného typu
    )
    string statusMessage => Slovní popis statusu.
    array struct output ( 
        string video_name => symbolické jméno vložené v addProjectVideo
        int video_state => Stav zpracování videa
        int video_length => Délka zpracovaného videa v sekundách
    )
}

2.8.4 - addProjectVideoPhoto( session_id as string, project_id as int, project_rkid as string, data as struct )

Vložení fotografie k videu

Vstupními parametry jsou project_id nebo project_rkid a struktura data:

struct data { 
    binary data => Vlastní obrázek,
    int video_id => id videa,
}

Pomocí project_id nebo project_rkid se identifikuje inzerát (viz kapitola 1.6). Pomocí video_id se identifikuje video. Minimální rozlišení fotografie je 480x360

struct { 
    int status => Status (
    	200 = OK,
    	404 = inzerát nenalezen,
    	407 = neautorizovaný přístup
    	452 = Nejsou vyplněny všechny povinné položky nebo jsou špatného typu
    )
    array struct output ()
}

2.4.5 - delProjectVideoPhoto( session_id as string, project_id as int, project_rkid as string, data as struct )

Vymazání fotografie k videu

Pomocí project_id nebo project_rkid se identifikuje inzerát (viz kapitola 1.6). Pomocí video_id se identifikuje video.

struct { 
    int status => Status (
    	200 = OK,
    	404 = inzerát nenalezen,
    	407 = neautorizovaný přístup
    	452 = Nejsou vyplněny všechny povinné položky nebo jsou špatného typu
    )
    array struct output ()
}

2.4.6 - setProjectVideoOrder( session_id as string, project_id as int, project_rkid as string, data as array )

Nastavení pořadí videí. Je potřeba uvést všechna videa, která jsou k inzerátu přiřazena

Pomocí project_id nebo project_rkid se identifikuje inzerát (viz kapitola 1.6).

array data [
    id_videa1, id_videa2, id_videa3, ...
]

struct { 
    int status => Status (
    	200 = OK,
    	404 = inzerát nenalezen,
    	452 = Nejsou vyplněny všechny povinné položky nebo jsou špatného typu
    )
    array struct output ()
}

2.4.7 - listProjectVideos( session_id as string, project_id as int, project_rkid as string)

Získání informací o videoprohlídkách existujícího projektu.

Pomocí project_id nebo project_rkid se identifikuje inzerát (viz kapitola 1.6). V output je vráceno pole. Prázdné pole se vrací v případě, že inzerát nemá u sebe žádné video.

struct { 
    int status => Status (
    	200 = OK,
    	404 = inzerát nenalezen,
    	407 = neautorizovaný přístup
    	452 = Nejsou vyplněny všechny povinné položky nebo jsou špatného typu
    )
    array struct output (
        string video_name => symbolické jméno vložené v addVideo,
        int video_state => stav zpracování videa,
        int video_length => délka zpracovaného videa v sekundách,
        int video_id => id videa,
        int video_order => pořadí videa číslované od 0,
        int video_image => náhled na fotografii, která se bude zobrazovat jako úvodní fotografie videa,
        int video_description => popis videa,
    )
}

Stavy atributu video_state lze najít v kapitole 2.4

2.9 - Čtení statistik

2.9.1 - listStat( session_id as string, advert_id as array, advert_rkid as array )

Výpis statistiky inzerátu / inzerátů.

Výpis je závislý na vyplněných vstupních parametrech. Pro výpis statistiky všech inzerátů, je advert_id i advert_rkid odesláno jako prázdné pole. Pokud je vyplněno pole advert_id, vypíší se jen uvedené inzeráty. Stejné je tomu i u advert_rkid. Oba parametry se dají kombinovaně použít, vždy musí oba obsahovat stejný počet prvků. Při vyplnění advert_id se ignorují hodnoty v advert_rkid, advert_id je preferováno (viz kapitola 1.6).

struct { 
    int status => Status (
    	200 = OK
    	407 = Neplatné přihlášení
    )
    string statusMessage => Slovní popis statusu.
    array struct output ( 
        int advert_id => číslo inzerátu,
        string rkid => číslo inzerátu realitní kanceláře,
        int total_views => Celková návštěvnost,
        double total_price => celkové náklady,
        string advert_code => id zakázky
        double topped_price => strženo za zvýhodnění inzerátu
        double advert_price => strženo za běžnou inzerci
        int top => inzerát byl/nebyl zvýhodněn [0,1]
        int with_vat => ceny jsou s DPH nebo bez DPH [0, 1]
    )
}

2.9.2 - listDailyStat( session_id as string, advert_id as int, advert_rkid as string )

Výpis denní statistiky inzerátu.

Pomocí advert_id nebo advert_rkid se identifikuje inzerát (viz kapitola 1.6).

struct { 
    int status => Status (
    	200 = OK,
    	407 = Neplatné přihlášení
    )
    string statusMessage => Slovní popis statusu.
    array struct output ( 
        string date => datum dne
        int views => počet shlédnutí,
        double price => stržená cena,
        double topped_price => strženo za zvýhodnění inzerátu,
        int with_vat => ceny jsou s DPH nebo bez DPH [0, 1],
    )
}

2.9.3 - listAllDailyStat( session_id as string, date as string )

Výpis statistiky všech inzerátů daného klienta za konkrétní den určený parametrem date.

struct { 
    int status => Status (
    	200 = OK
    	407 = Neplatné přihlášení
    )
    string statusMessage => Slovní popis statusu.
    array struct output ( 
        int advert_id => číslo inzerátu
        string rkid => číslo inzerátu realitní kanceláře
        int views => návštěvnost
        double advert_price => strženo za běžnou inzerci
        double topped_price => strženo za zvýhodnění inzerátu
        double total_price => celkové náklady
        int top => inzerát byl/nebyl zvýhodněn [0,1]
        int with_vat => ceny jsou s DPH nebo bez DPH [0, 1]
    )
}

2.9.4 - listSellerStat( session_id as string, seller_id as int, seller_rkid as string, from as datetime, till as datetime )

Výpis denních statistik inzerátů jednoho makléře. Čas je zadán uzavřeným intervalem(from, till). Pomocí seller_id nebo seller_rkid se identifikuje inzerát (viz kapitola 1.6).

struct { 
    int status => Status (
    	200 = OK,
    	407 = Neplatné přihlášení
    )
    array struct output ( 
        string date => den ke kterému jsou vztažena následující čísla
        int advert_count => počet inzerátu makléře pro aktuální den
        int views => počet shlédnutí inzerátu makléře
        double advert_price => platba za zveřejnění inzerátu
        double topped_price => platba za topovací operace
        double total_price => součet za inzerci a topování pro aktuální den
        int with_vat => ceny jsou s DPH nebo bez DPH [0, 1]
    )
}

2.10 - Metoda dostupná bez přihlášení

2.10.1 - version()

Výpis verze importu.

struct { 
    int status => Status (
    	200 = OK
    )
    string statusMessage => Slovní popis statusu.
    array struct output ( 
        string version
    )
}

3 - Datové struktury a číselníky

3.1 - Atributy a číselníky inzerátu

V následující tabulce jsou jednotlivé atributy řazeny tak, že nahoře jsou vyjmenované povinné položky a dole nepovinné.

Tabulka 1: Seznam atributů inzerátu (metoda addAdvert)

3.2 - Atributy a číselníky developerského projektu

V následném seznamu atributů developerského projektu jsou nejdříve vypsané povinné položky.

Tabulka 2: Seznam atributů developerského projektu (metoda addProject)

3.3 - Návratové kódy a chybové hlášky

3.4 - Stavy inzerátu ve výpise

3.5 - Podporované formáty videozáznamů

4 - Příklady

4.1 - PHP

<?php
    // Definováni základních přístupových údajů
    $client = 1; // ID klienta
    $password = „vlozte-md5-hash-hesla“; // heslo zašifrované pomocí MD5
    $key = „vlozte-importni-klic“; // importní klíč

    /**
    * Výpočet nové sessionId
    * @param string $sessionId Aktualni sessionId
    * @param string $password Heslo k importnimu rozhrani
    * @param string $key Klic k importnimu rozhrani
    * @return string Nove sessionId
    */
    function computeSessionId($sessionId, $password, $key) {
        $newVarPart = md5($sessionId . $password . $key);
        return substr($sessionId, 0, 48) . $newVarPart;
    }

    //Načtení třídy pro práci s XMLRPC, například z http://phpxmlrpc.sourceforge.net
    require_once 'xmlrpc/lib/xmlrpc.inc';

    //Nastavení interního kódováni na utf-8 pro správný přenos diakritiky
    PhpXmlRpcPhpXmlRpc::$xmlrpc_internalencoding = 'UTF-8';

    /* Pripojeni k importserveru */
    $client = new xmlrpc_client(’/RPC2’, ’prazskereality.cz’, 80);

    //vytvoreni dotazu - ID klienta
    //parametr - ID klienta
    $params = array(new xmlrpcval($clientId, ’int’));

    // vytvoreni zpravy pro ziskani sessionId
    $msg = new xmlrpcmsg(’getHash’, $params);

    // poslani dotazu na server
    $response = $client->send($msg);

    // nacteni vysledku
    $getHash = php_xmlrpc_decode($response->value());

    // je dotaz OK ?
    if ($getHash[’status’] != 200) {
    die(„Chyba pri volani getHash [{$getHash[’status’]}]: {$getHash[’statusMessage’]}“);

    }

    // sessionId se vypocte z obdrzeneho (vystup getHash), hesla a SW klice
    $sessionId = computeSessionId($getHash[’output’][0][’sessionId’], $password, $key);

    /* přihlášení na importserver */
    //vytvoreni dotazu pro login a poslani na server
    $params = array(new xmlrpcval($sessionId));
    $msg = new xmlrpcmsg(„login“, $params);
    $response = $client->send($msg);

    //nacteni vysledku
    php_xmlrpc_decode($response-value());
    //pokud je jiny status nez 200, nekde je chyba
    if ($login[’status’] != 200) {
    die(„Chyba pri přihlášení [{$login[’status’]}]: {$login[’statusMessage’]}“);

    }

    /* Ukazka pridani inzeratu */
    //pred kazdym dalsim pozadavkem je treba znovu vypocitat sessionId
    $sessionId = computeSessionId($sessionId, $password, $key);

    $advert = array(
        „advert_function“ => 1,  // prodej
        „advert_lifetime“ => 1,  // 7 dni
        „advert_price“ => 10000.0,
        „advert_price_currency“ => 1,  // Kč
        „advert_price_unit“ => 2,   // za měsíc
        „advert_type“ => 1,   //byty
        „description“ => „Pekny byt s vyhledem na zahradu.“,
        „locality_city“ => „Praha“,
        „locality_inaccuracy_level“ => 2,  //znepresnení adresy o 1 stupen
        „floor_number“ => 1,  //první patro
        „garage“ => false,
        „loggia“ => false,
        „balcony“ => false,
        „terrace“ => false,
        „ownership“ => 1,  // osobní vlastnictví
        „parking_lots“ => true,
        „advert_subtype“ => 4,  // typ bytu 2+kk
        „usable_area“ => 54,  //plocha 54m
        „building_type“ => 2,  //cihlová budova
        „building_condition“ => 1,  //stav objektu velmi dobrý
        „cellar“ => true,  //má sklep
        „heating“ => array(3, 4),  // topeni lokalni elektricke a ustredni plynove
        „telecommunication“ => array(1, 2, 4),  // telefon, internet, kabelova televize
        „seller_id“ => 123456, 
    )

    $msg = new xmlrpcmsg(„addAdvert“); $msg->addParam(php_xmlrpc_encode($sessionId));
    $msg->addParam(php_xmlrpc_encode($advert));
    $response = $client->send($msg);

    $result = php_xmlrpc_decode($response->value());
    if (floor($result[’status’] / 100) != 2) { die(„Chyba pri ukladani inzeratu [{$result[’status’]}]: {$result[’statusMessage’]}“);}

    /* Odhlaseni */
    $sessionId = computeSessionId($sessionId, $password, $key);
    $params = array(new xmlrpcval($sessionId));
    $msg = new xmlrpcmsg(„logout“, $params);
    $response = $client->send($msg);
    $result = php_xmlrpc_decode($response->value());
    if ($result[’status’] != 200) { die(„Chyba pri odhlaseni [{$result[’status’]}]: {$result[’statusMessage’]}“)};

    ?>

4.2 - Python

#!/usr/bin/python
import xmlrpclib
import hashlib

clientId = 1  # ID klienta
password = "vlozte-md5-hash-hesla"  # heslo zakryptovane pres md5
key = "vlozte-importni-klic"  # importni klic

def NewSessionId(oldId, password, key):  # Heslo by se melo pouzivat uz zakryptovane pres md5. Heslo i importni klic jsou zjistitelne v adminwebu.
    varPart = hashlib.md5()
    varPart.update(oldId + password + key)
    return oldId[0:48] + varPart.hexdigest()

# připojení na import server
client = xmlrpclib.ServerProxy('https://prazskereality.cz/RPC2')

# zavoláme metodu getHash pro získání počátečního sessionId
getHash = client.getHash(clientId)
if getHash['status'] / 100 == 2:
    # výpočet sessionId pro další dotaz
    sessionId = NewSessionId(getHash['output'][0]['sessionId'], password, key)
    # přihlášení na importserver
    response = client.login(sessionId)
    if response['status'] / 100 == 2:
        print 'logged in'

        # vložení inzerátu
        sessionId = NewSessionId(sessionId, password, key)
        advert = {
            'advert_function': 1,  # prodej
            'advert_lifetime': 1,  # 7 dní
            'advert_price': 10000.0,
            'advert_price_currency': 1,  # Kč
            'advert_price_unit': 2,  # za měsíc
            'advert_type': 1,  # byty
            'description': 'Pěkný byt s výhledem na zahradu',
            'locality_city': 'Praha',
            'locality_inaccuracy_level': 2,  # znepřesnění adresy o 1 stupeň
            'floor_number': 1,  # první patro
            'garage': False,
            'loggia': False,
            'balcony': False,
            'terrace': False,
            'ownership': 1,  # osobní vlastnictví
            'parking_lots': True,
            'advert_subtype': 4,  # Typ bytu 2+kk
            'usable_area': 54,  # Plocha bytu 54m
            'building_type': 2,  # Cihlová budova
            'building_condition': 1,  # Stav objektu velmi dobrý
            'cellar': True,  # Má sklep
            'heating': (3, 4),  # topení lokalní elektrické a ústřední plynové
            'telecommunication': (1, 2, 4),  # telefon, internet, kabelová televize
            'seller_id': 123456,
        }

        response = client.addAdvert(sessionId, advert)

        if response['status'] / 100 == 2:
            print 'Advert successfully added.'
        else:
            print 'addAdvert: %d %s' % (response['status'], response['statusMessage'])

        # Odhlášení
        sessionId = NewSessionId(sessionId, password, key)
        client.logout(sessionId)

    else:
        print 'login %d %s' % (response['status'], response['statusMessage'])

else:
    print 'getHash %d %s' % (getHash['status'], getHash['statusMessage'])

4.3 - Příklad XML požadavku

<?xml version="1.0"?>
<methodCall>
    <methodName>addAdvert</methodName>
    <params>
        <param>
            <value>
                <struct>
                    <member>
                        <name>user_status</name>
                        <value><int>1</int></value>
                    </member>
                    <member>
                        <name>advert_function</name>
                        <value><int>1</int></value>
                    </member>
                    <member>
                        <name>advert_price_unit</name>
                        <value><int>1</int></value>
                    </member>
                    <member>
                        <name>advert_lifetime</name>
                        <value><int>3</int></value>
                    </member>
                    <member>
                        <name>advert_price</name>
                        <value><int>10000</int></value>
                    </member>
                    <member>
                        <name>advert_type</name>
                        <value><int>3</int></value>
                    </member>
                    <member>
                        <name>advert_price_currency</name>
                        <value><int>1</int></value>
                    </member>
                    <member>
                        <name>seller_rkid</name>
                        <value><string>makléř01</string></value>
                    </member>
                    <member>
                        <name>description</name>
                        <value><string>Krásný slunný byt s výhledem na zahradu</string></value>
                    </member>
                    <member>
                        <name>locality_street</name>
                        <value><string>Radlická</string></value>
                    </member>
                    <member>
                        <name>locality_cp</name>
                        <value><int>2</int></value>
                    </member>
                    <member>
                        <name>locality_city</name>
                        <value><string>Praha</string></value>
                    </member>
                    <member>
                        <name>locality_inaccuracy_level</name>
                        <value><int>2</int></value>
                    </member>
                    <member>
                        <name>building_type</name>
                        <value><int>5</int></value>
                    </member>
                    <member>
                        <name>building_condition</name>
                        <value><int>1</int></value>
                    </member>
                    <member>
                        <name>usable_area</name>
                        <value><int>100</int></value>
                    </member>
                </struct>
            </value>
        </param>
    </params>
</methodCall>