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.