Kihagyás

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.