Elnevezés alapú lekérdezés

A szolgáltatás címe, ahova GET kérést kell küldeni, key és value változókkal, ahol a key=name, a value pedig a keresendő név urlencode-olva (a példa esetében az Árvíz urlencode-olt megfelelője: %C3%81rv%C3%ADz):

https://pkapi.hu/api/v2/companydata?key=name&value=%C3%81rv%C3%ADz

Fejléc (header) paraméterek:

access-token: 36223C6A73DD64B909EC8AEC83D031A2F9C8F643EA0E0D6E09B2289D2A014A7F
userid: 12345678
dkey: DMO

A válasz JSON szöveg URL encode-olva:

{
    "hits": 18,
    "taken": 18,
    "results": {
        "26869700": {
            "score": 8.154112,
            "vatnum": "26869700",
            "name": "\u00c1RV\u00cdZ Bt.",
            "address": "9912 Molnaszecs\u0151d, Kossuth L. u. 53.",
            "status": 1
        },
        "21100507": {
            "score": 8.07316,
            "vatnum": "21100507",
            "name": "\u00c1RV\u00cdZ 93 Bt.",
            "address": "1039 Budapest, Hadri\u00e1nus u. 3. 9. em. 85.",
            "status": 1
        }
    },
    "validity": {
        "pksub": "2017-12-31",
        "posub": "0000-00-00",
        "subscribed": "0000-00-00"
    }
}

A válasz egy maximum 50 darab lehetséges találatot tartalmaz, ami megfelel a kereséséi feltételnek. Minden találat indexe a találat adótörzsszáma, így a kiválasztása után az adótörzsszám alapú lekérdezéssel lekérdezhetők hozzá az adatok.

Ajánlás: a név alapú keresés egy olyan listát produkáljon UI-on, amiből a felhasználó kattintással (vagy enterrel) kiválaszthat egy darabot. A kiválasztott elemre kattintás (vagy enter megnyomása) váltsa ki azt az eseményt, mintha megadta volna az adótörzsszámát egy cégnek keresésre és ugyanazt az eljárást futtassad.

Válasz séma:

    {
        "hits": "az összes lehetséges találat száma",
        "taken": "a viszaadott találatok száma, ami maximum 50",
        "results": {
            "26869700": {
                "score": "relevancia pontszám",
                "vatnum": "adótörzsszám",
                "name": "név",
                "address": "székhely cím",
                "status": "működés státusza [1: működik, 2: nem működik, 3: szüneteltetett]"
            },
            ...
            "21100507": {
                "score": "relevancia pontszám",
                "vatnum": "adótörzsszám",
                "name": "név",
                "address": "székhely cím",
                "status": "működés státusza [1: működik, 2: nem működik, 3: szüneteltetett]"
            }
        },
        "validity": {
            "pksub": "2017-12-31",
            "posub": "0000-00-00",
            "subscribed": "0000-00-00"
        }
    }

Ha találatok száma több mint 50, akkor lehetőség van székhely cím adattal vagy a vállalkozás működésének státuszával szűkíteni a találati listát.

A székegylre szűkítés esetében egy további változót (constrict) kell a lekérdezéssel küldeni. A tartalma a székhely cím egy részével egyező urlencode-olt szöveg:

https://pkapi.hu/api/v2/companydata?key=name&value=%C3%81rv%C3%ADz&constrict=1039

A vállalkozás státusza szerinti szűkítés hasonlóan, a székhelyre történő szűkítéshez egy változó küldését jelenti. A változó a status, értéke pedig: - 1: csak a működő vállalkozásokat adja vissza - 2: csak a nemműködő vállalkozásokat adja vissza - 3: csak a szüneteltetett egyéni vállalkozásokat adja vissza

https://pkapi.hu/api/v2/companydata?key=name&value=%C3%81rv%C3%ADz&constrict=1039&status=1

Amennyiben a válasz státuszkódja (htttp_status) 200, abban az esetben a szolgáltatás sikeresen kiszolgálta a kérést, minden egyéb esetben a válasz az RFC2616 irányelveinek megfelelően kezelendő.

  • 200: Sikeres lekérdezés
  • 400: Hiányzó vagy hibás adatok, nem megfelelő kérés.
  • 401: Hozzáférés megtagadva.
  • 404: A lekérdezés alapján nem található adat.
  • 500: Rendszerhiba.

A hibaüzenetek is JSON szövegként kerülnek visszaadásra ebben a struktúrában.

JSON hiba válasz:

{
  "error": "Not Found",
  "error_description": "The requested search resulted 0 matches."
}