XML API (régi) áttekintés

Figyelem

Ez az API már elévült, újonnani beépítését nem javasoljuk!

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/v2

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

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/v2?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/v2

Példa: fájl

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

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/v2?xml=https%3A%2F%2Fwww.example.com%2Frequest.xml

Példa: azonosítással

$ curl https://ingatlanok.hu/api/xml/v2?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_v2.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.