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