XML API áttekintés

Bevezetés

Az XML API segítségével az Ingatlanok.hu adminisztrációs felületének egyes műveleteit lehet végrehajtani programosan, XML formátumú kommunikációs protokollal.

Fontos

Az API használata előtt célszerű elolvasni a korlátozások listáját.

XML feldolgozó végpont: https://ingatlanok.hu/api/xml/v3

Tesztrendszer végpont: https://sandbox.ingatlanok.hu/api/xml/v3

A tesztrendszerhez való hozzáféréshez kérjük, érdeklődjön az api@ingatlanok.hu címen.

Az XML-eknek UTF-8 kódolásúnak kell lenniük, a "kényes" elemek - melyekben az XML értelmezők számára speciális karakterek, mint pl. '&', '<' stb. szerepelhetnek - tartalmát <![CDATA[ és ]]> közé kell tenni.

Példa

<leirasok>
    <leiras nyelv="hu"><![CDATA[
        Lorem ipsum & dolor sit amet.
    ]]></leiras>
<leirasok>        

A pretty=1 GET paraméterrel a visszaadott XML tabulálva lesz, sortörésekkel, a könnyebb olvashatóság érdekében.

Példa

$ curl -F xml=@/path/to/request.xml https://ingatlanok.hu/api/xml/v3?pretty=1

Kommunikáció

XML közvetlen beküldése

Az XML feldogozó végpontot ekkor POST metódussal kell meghívni. A küldendő XML-t a body részben, vagy fájlként (multipart/form-data formában) az xml paraméterben kell beküldeni.

Példa: body

$ curl -X POST -H "Content-Type: application/xml" --data-binary "@/path/to/request.xml" https://ingatlanok.hu/api/xml/v3

Példa: fájl

$ curl -F xml=@/path/to/request.xml https://ingatlanok.hu/api/xml/v3

Távoli XML feldolgozása

Az XML feldolgozó végpontot ekkor GET metódussal kell meghívni. A feldolgozandó XML URL-jét az xml paraméterben kell megadni. Az API erről a címről fogja letölteni, majd feldolgozni az XML-t.

Ha az URL védve van felhasználónévvel, ill. jelszóval, akkor a htaccessuser és htaccesspassword paraméterekben kell megadni a hozzáféréshez szükséges adatokat.

Példa: azonosítás nélkül

$ curl https://ingatlanok.hu/api/xml/v3?xml=https%3A%2F%2Fwww.example.com%2Frequest.xml

Példa: azonosítással

$ curl https://ingatlanok.hu/api/xml/v3?xml=https%3A%2F%2Fwww.example.com%2Frequest.xml&htaccessuser=ingatlanok&htaccesspassword=secret

XML felépítése

Minden XML fájl két részből tevődik össze: hitelesítés és parancsok.

Példa

<?xml version="1.0" encoding="UTF-8"?>
<api xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://ingatlanok.hu/api/xml/api_v3.xsd">
    <hitelesites>
        <felhasznalo>demo</felhasznalo>
        <jelszo>da39a3ee5e6b4b0d3255bfef95601890afd80709</jelszo>
    </hitelesites>
    <parancsok>
        <ingatlan_torles>
            <azonositas>
                <atviteli_azonosito>a123</atviteli_azonosito>
            </azonositas>
            <iroda_azonosito>10</iroda_azonosito>
        </ingatlan_torles>
        <ingatlan_torles>
            <azonositas>
                <id>9</id>
            </azonositas>
            <iroda_azonosito>10</iroda_azonosito>
        </ingatlan_torles>
    </parancsok>
</api>        

Hitelesítés

Itt az adminisztrációs felülethez szükséges felhasználónév és külön XML/JSON jelszó párost kell megadni. Az utóbbit az adminisztrációs oldalon belépve az adminisztrátor adatlapján lehet megtalálni.

Új adminisztrátor felvételekor automatikusan generálódik egy új XML/JSON jelszó!

Parancsok

A küldhető parancsok listáját és egyben az XML szintaktikai leírását az XML séma tartalmazza. A legfontosabb, nem egyértelmű tagek magyar nyelvű szöveges leírással vannak ellátva.

Az api.xsd és answer.xsd fájlok összetettségük miatt nehezen átláthatóak, ezért javasoljuk jelen dokumentáció tanulmányozását, ahol minden parancsra külön kitérünk, példákkal.

• API XML séma: api.xsd
• API válasz XML séma: answer.xsd

Megjegyzés

A megadott példákban nem valós azonosítók vannak. A példáknál csak a <parancsok> elemen belüli részeket közöljük.

Opcionális elemeknél az alapértelmezett értékek félkövérrel jelennek meg a leírásban.

Típusdefiníciók:

• "string(1-40)": legalább 1, legfeljebb 40 karakteres szöveg
• "string(255)": legfeljebb 255 karakteres szöveg
• "uint(8)": legfeljebb 8 számjegyű pozitív egész szám
• "uint{50-500}": legalább 50, legfeljebb 500 értékű pozitív egész szám
• "double{15-24}": legalább 15, legfeljebb 24 értékű lebegőpontos szám
• "decimal(18, 2)": legfeljebb 18 számjegyű decimális szám, 2 tizedesjegy pontossággal
• "datetime": dátum (ISO 8601)
• "sdatetime": dátum (éééé-hh-nn óó:pp:mm)

Korlátozások

• Az elérhető műveletekből legfeljebb 100 darabot lehet megadni egy XML kérésben. Így például ha 327 darab ingatlant szeretnénk felvenni, akkor legalább 4 kérést kell küldeni a szervernek.
• Egy órán belül legfeljebb 100 darab (1-es vagy 2-es típusú) hibás XML kérést lehet elküldeni az API felé egy IP címről. Ezen korlát túllépése esetén az API a további kérésekre standard hibát ad 12-es kóddal.
• Egy ingatlan módosítására az ingatlan_modositasa parancs használata ajánlott. Egy ingatlan rövid időn belüli törlését és újralétrehozását a rendszer duplikációként érzékeli.