Importní rozhraní manuál

Adresa importního serveru

Serverové rozhraní XML-RPC se nachází na adrese http://import.realitnitrznice.cz/ a slouží k importu http://www.xmlrpc.com/spezakázek realitních kanceláří do systému Realitní tržnice.

Základní informace

Veškerá komunikace se serverem a zpět probíhá v kódování UTF-8. Na adrese http://www.xmlrpc.com/spec 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, doporučujeme si přepnout na testovací účet.

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. Ta slouží pro potvrzení přihlášení, které se předá zakódované heslo v MD5 a softwarový klíč. Pokud přihlášení proběhne v pořádku, vrátí metoda status 200.

Názvosloví

  • klient - z pohledu importního rozhraní je klientem realitní kancelář
  • password - heslo na import potřebné k přístupu, lze nastavit v zde
  • software_key - SW klíč řetězec, identifikující použitý software
  • hash – řetězec znaků a čísel, který slouží k zakódování hesla
  • session_id - řetězec znaků a čísel, který identifikuje konkrétní importní session
  • rkid - importní id, id z realitní kanceláře
  • seller - makléř RK
  • topování inzerátu placené zvýhodnění pozice v hledání na webu Realitní tržnice

Identifikace inzerátů

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

  • _id - interní id v databázi Seznamu - 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

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.

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