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ő.
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." }