JSON API áttekintés

Bevezetés

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

Fontos

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

JSON feldolgozó végpont: https://ingatlanok.hu/api/json/v3

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

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

Az adatoknak minden esetben UTF-8 kódolásúnak kell lenniük.

Hitelesítés

A kéréseket HTTP Basic Authentication fejléccel kell elküldeni a rendszernek, ahol 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ó!

Végpontok

Megjegyzés

A megadott példákban nem valós azonosítók vannak.

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)
• "object": JSON objektum

POST és PUT végpontoknál a JSON adatokat az üzenet tartalmi részében (body) kell elküldeni, a kérés ebben az esetben application/json mime típusként kell érkezzen a szerverre.

Ingatlanok

Metódus	URI	Content-Type	Funkció
GET	/property		Ingatlanok listázása
POST	/property	application/json	Új ingatlanok felvétele
PUT	/property	application/json	Ingatlanok módosítása
DELETE	/property		Ingatlanok törlése
POST	/property/image	application/json	Új ingatlan képek felvétele
PUT	/property/image	application/json	Ingatlan képek módosítása
DELETE	/property/image		Ingatlan képek törlése

Értékesítők

Metódus	URI	Content-Type	Funkció
GET	/seller		Értékesítők listázása
POST	/seller	application/json	Új értékesítők felvétele
PUT	/seller	application/json	Értékesítők módosítása
DELETE	/seller		Értékesítől törlése
POST	/seller/image	application/json	Új értékesítő képek felvétele
PUT	/seller/image	application/json	Értékesítő képek módosítása
DELETE	/seller/image		Értékesítő képek törlése

Irodák

Metódus	URI	Content-Type	Funkció
GET	/office		Irodák listázása

Régiók

Metódus	URI	Content-Type	Funkció
GET	/region		Régiók listázása

Tömeges kérések

Metódus	URI	Content-Type	Funkció
POST	/batch	application/json	Tömeges kérések

Egyszerre legfeljebb 100 kérés küldhető be egy híváson belül.

A kérésekben a végpontoknál megadott HTTP paramétereket kell megadni, a válaszok mezői is megfelelnek a HTTP válaszok mezőinek.

Kérés

Példa

POST /batch

[
    {
        "method": "GET",
        "uri": "/property?part=id,map&created_after=2009-03-05T12:23:01"
    },
    {
        "method": "PUT",
        "uri": "/seller?id=123",
        "body": {
            "id": {
                "transfer_id": "ert123"
            },
            "seller": {
                "name": "Gipsz II. Jakab"
            }
        },
    }
]

Kötelező mező	Leírás
method	string A végpont metódusa (csupa nagybetűvel).
uri	string A végpont útvonala, az esetleges query paraméterekkel együtt.
Opcionális mező	Leírás
body	object A kérés tartalmi része, ha a végponton értelmezett.

Válasz

Példa

HTTP/1.1 207 Multi-Status

[
    {
        "status": 200,
        "body": {

        }
    }
    {
        "status": 400,
        "body": {
            "error_code": 24,
            "error_description": "Már van ilyen átviteli azonosító felvéve"
        }
    }
]

Mező	Leírás
status	uint A HTTP válasz kódja.
body	object A válasz tartalmi része.

Korlátozások

• Az elérhető műveletekből legfeljebb 100 darabot lehet megadni egy tömeges kérésben. Így például ha 327 darab ingatlant szeretnénk felvenni, akkor legalább 4 tömeges 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 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 hibát ad 12-es kóddal.
• Egy ingatlan módosítására az Ingatlan módosítása 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.