Bevezető - Mi az a PK.API?

A PK.API egy internet alapú, M2M szolgáltatás, amiben társas vállalkozások és egyéni vállalkozások hatályos adatait lehet lekérdezni.

Egy meghatározott URL-re küldesz nekünk egy adótörzsszámot (az adószám első 8 számjegyét), mi pedig azonnal visza küldjük neked az adótörzsszámhoz tartozó hatályos adatokat.

A lekérdezés történhet adótörzsszám alapján és név alapján. A válasz urlencode-olt JSON szöveg.

cURL mintakód adószám alapú lekérdezésre:

curl -i -k "https://pkapi.hu/api/v1/companydata?key=vatnum&value=25566552" \
-H "access-token: 36223C6A73DD64B909EC8AEC83D031A2F9C8F643EA0E0D6E09B2289D2A014A7F" \
-H "userid: 12345678" \
-H "dkey: DMO"

Natív php+cURL mintakód adószám alapú lekérdezésre:

$curl = curl_init();

$headers = [
    'access-token: 36223C6A73DD64B909EC8AEC83D031A2F9C8F643EA0E0D6E09B2289D2A014A7F',
    'userid: 12345678',
    'dkey: DMO'
];

curl_setopt_array($curl, array(
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_URL => 'https://pkapi.hu/api/v1/companydata?key=vatnum&value=25566552',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_SSL_VERIFYPEER => false
));

$response = curl_exec($curl);

curl_close($curl);

echo $response;

Visual Basic .NET mintakód adószám alapú lekérdezésre:

Dim webClient As New System.Net.WebClient

webClient.Headers.Add("access-token", "36223C6A73DD64B909EC8AEC83D031A2F9C8F643EA0E0D6E09B2289D2A014A7F")
webClient.Headers.Add("userid", "12345678")
webClient.Headers.Add("dkey", "DMO")
webClient.Encoding = System.Text.Encoding.UTF8

Dim result As String = webClient.DownloadString(request)

Dim resarray = JsonConvert.DeserializeObject(result)

JSON válasz:

{
  "status":"1",
  "created":"2016-12-30 17:50:25",
  "bankname":"OTP Fi\u00f3k Hatvan(3000 Hatvan, Kossuth t\u00e9r 8. )",
  "finsihedproceedings":"0",
  "vatnumstatus":"1",
  "address":"3000 Hatvan, Balassi B\u00e1lint \u00fat 40.",
  "bankcount":"1",
  "email":"legal@sba.hu",
  "name":"SBA Group Zrt.",
  "pendingproceedings":"0",
  "vatnum":"25566552-2-10",
  "bankaccount":"11739054-21150007-00000000",
  "id":"25566552",
  "regnum":"10-10-020331",
  "modified":"2016-06-07",
  "type":"10"
}
Hitelesítő adatok - Hogyan integrálhatom Én is a PK.API szolgáltatást?

A PK.API használatához hitelesítő adatokra van szükség, amelyeket a szolgáltatásnak küldött kérések fejlécében kell elhelyezni.

Hitelesítő adatok:

access-token: your-access-token
userid: your-userid
dkey: your-distributor-key

Hitelesítő adatokat a kapcsolatfelvételi űrlapon tudsz igényelni Hitelesítő adatok igénylése menüpontban, azonban ahhoz, hogy leteszteld az integrációt, használhatod az alábbi DEMO hozzáférési adatokat.

DEMO hitelesítő adatok:

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

A DEMO hozzáférési adatokkal az adótörzsszám alapú lekérdezést tudod tesztelni a következő korlátozásokkal:

  • A visszaküldött adatokban csillagokkal helyettesítünk néhány karaktert.
  • 24 órán belül ugyan arról az IP címről maximum 50 lekérdezést küldhetsz.

A DEMO lekérdezés JSON válasza:

{
  "status": "1",
  "created": "20*6-*2-*0 *7:*0:*5",
  "bankname": "OT* F*ók*Ha*va*(3*00*Ha*va*, *os*ut* t*r *. *",
  "finsihedproceedings": "0",
  "vatnumstatus": "1",
  "address": "30*0 *at*an* B*la*si*Bá*in* ú* 4*.",
  "bankcount": "1",
  "email": "le*al*sb*.h*",
  "name": "SB* G*ou* Z*t.",
  "pendingproceedings": "0",
  "vatnum": "25*66*52*2-*0",
  "bankaccount": "11*39*54*21*50*07*00*00*00",
  "id": "25*66*52",
  "regnum": "10*10*02*33*",
  "modified": "20*6-*6-*7",
  "type": "10"
}

Az API a szolgáltatott funkciókat jogosultsági csoportokba foglalja. A DEMO üzemmód kizárólag a  vatnum  funkciókhoz biztosít hozzáférést (azaz az adótörzsszám alapú lekérdezést), a név alapú lekérdezéshez  name  funkcionális jogosultság szükséges, a menedzsment funkciókhoz pedig  admin  funkcionális jogosultság szükséges. A jogosultságot szolgáltatótól kell igényelni.

Adótörzsszám 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=vatnum, a value pedig a keresendő adótörzsszám (a példa esetében a 25566552):

https://pkapi.hu/api/v1/companydata?key=vatnum&value=25566552

Fejléc (header) paraméterek:

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

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

{
  "status":"1",
  "created":"2016-12-30 17:50:25",
  "bankname":"OTP Fi\u00f3k Hatvan(3000 Hatvan, Kossuth t\u00e9r 8. )",
  "finsihedproceedings":"0",
  "vatnumstatus":"1",
  "address":"3000 Hatvan, Balassi B\u00e1lint \u00fat 40.",
  "bankcount":"1",
  "email":"legal@sba.hu",
  "name":"SBA Group Zrt.",
  "pendingproceedings":"0",
  "vatnum":"25566552-2-10",
  "bankaccount":"11739054-21150007-00000000",
  "id":"25566552",
  "regnum":"10-10-020331",
  "modified":"2016-06-07",
  "type":"10",
  "pksub":"2016-12-31",
  "posub":"2016-12-31",
  "subscribed":"0000-00-00"
}

A válaszban található változók megnevezésének darabszáma és sorrendje nem konstans. Ha például nincs a cégnek bankszámlája, akkor az a mező nem kerül visszaadásra, illetve nem törvényszerű, hogy minden esetben a "status" mező az első a JSON szövegben.

A válaszban mindig visszaadott adatok:
    - id
    - type
    - status
    - vatnumstatus
    - name
    - address
    - vatnum
    - finsihedproceedings
    - pendingproceedings
    - created
    - modified
    - pksub
    - posub
    - subscribed

Válasz séma:

{
  "id": "adótörzsszám",
  "type": "társasági forma [lásd: Társasági formák jelölése]",
  "status": "működő=1, nem működő=2, szüneteltetett=3",
  "vatnumstatus": "adószám státusza, érvényes=1, érvénytelen=0",
  "name": "név",
  "address": "székhely cím",
  "email": "email cím",
  "vatnum": "adószám [NNNNNNNN-N-NN]",
  "regnum": "EV esetében regisztrációs szám, cég esetében cégjegyzék szám",
  "euvatnum": "közösségi adószáma",
  "bankname": "bankszámla vezető fiók neve és címe",
  "bankaccount": "bankszámla szám",
  "bankcount": "hány bankszámla száma van a cégnek",
  "finsihedproceedings": "befejezett eljárások, van=1, nincs=0",
  "pendingproceedings": "folyamatban lévő eljárások, van=1, nincs=0",
  "created": "létrehozás dátuma",
  "modified": "legutolsó módosítás dátuma [YYYY-MM-DD]",
  "pksub": "Partnerkövető szolgáltatás előfizetés érvényessége",
  "posub": "Partnerfigyelő szolgáltatás előfizetés érvényessége",
  "subscribed": "Első előfizetés dátuma (0000-00-00 azt jelenti, hogy demó felhasználó)"
}

Társasági formák jelölése:

1  'Vállalat'
2  'Szövetkezet'
3  'Közkereseti társaság'
4  'Gazdasági munkaközösség'
5  'Jogi személy felelősségvállalásával működő gazdasági munkaközösség'
6  'Betéti társaság'
7  'Egyesülés'
8  'Közös vállalat'
9  'Korlátolt felelősségű társaság'
10 'Részvénytársaság'
11 'Egyéni cég'
12 'Külföldiek magyarországi közvetlen kereskedelmi képviselete'
13 'Oktatói munkaközösség'
14 'Közhasznú társaság'
15 'Erdőbirtokossági társulat'
16 'Vízgazdálkodási társulat'
17 'Külföldi vállalkozás magyarországi fióktelepe'
18 'Végrehajtói iroda'
19 'Európai gazdasági egyesülés'
20 'Európai részvénytársaság'
21 'Közjegyzői iroda'
22 'Külföldi székhelyű európai gazdasági egyesülés magyarországi telephelye'
23 'Európai szövetkezet'
99 'Egyéni vállalkozás'

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": "No record found based on the requested data."
}
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/v1/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:

{
  "26869700": {
    "vatnum": "26869700",
    "name": "\u00c1RV\u00cdZ Bt.",
    "address": "9912 Molnaszecs\u0151d, Kossuth L. u. 53."
  },
  "21100507": {
    "vatnum": "21100507",
    "name": "\u00c1RV\u00cdZ 93 Bt.",
    "address": "1039 Budapest, Hadri\u00e1nus u. 3. 9. em. 85."
  }
}

A válasz egy maximum 25 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:

    {
      "26869700": {
        "vatnum": "adótörzsszám",
        "name": "név",
        "address": "székhely cím"
    }, {
        ...
    }
      "21100507": {
        "vatnum": "adótörzsszám",
        "name": "név",
        "address": "székhely cím"
      }
    }

Ha találatok száma több mint 25, akkor lehetőség van székhely cím adattal szűkíteni a találati listát. Ebben az esetben 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/v1/companydata?key=name&value=%C3%81rv%C3%ADz&constrict=1039

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."
}
Felhasználó létrehozása

A felhasználó létrehozás egy automatizált folyamat, ami úgy lett megtervezve, hogy az API szolgáltatásait integráló szoftverfejlesztőnek lehetősége legyen a szoftverének minden példányában elérhetővé tenni ezt a szolgáltatást.

Felhasználó létrehozása gyakorlatilag egy adószámos (Adótörzsszám alapú lekérdezés) vagy név alapú lekérdezés (Név alapú lekérdezés) kezdeményezésé egy olyan felhasználó azonosítóval (userid) amivel még sosem küldtünk lekérdezést a rendszernek.


Példa natív alkalmazás fejlesztőknek:

Klasszikusan minden program példány rendelkezik egy azonosítóval, kulccsal, amit önmagában tárol is az aktiválás után. Mivel ez az azonosító köti össze a vevőt a programmal, célszerű ezt használni userid-ként és elküldeni a kéréssel.

Példa multitenancy (SasS) alkalmazás fejlesztőknek

Ilyen alkalmazásoknál az előfizető rendelkezik egy egyedileg generált (általában valami inkrementális elsődleges kulcs) azonosítóval. Mivel ez az azonosító köti össze az előfizetőt a fiókjával, célszerű ezt használni userid-ként és elküldeni a kéréssel.

A felhasználó úgy jön létre, hogy azonnal használni tudja az adószám alapú lekérdezést, korlátozások nélkül egy hónapig (ez az ASZF szerint változhat), a név alapú lekérdezést pedig utólag (szerződés szerint) aktiválja szolgáltató.

Figyelés indítása

A szolgáltatás használatához érvényes előfizetés szükséges. Az előfizetés nem része a Partnerkövető szolgáltatásnak, ha van érvényes Partnerkövető szolgáltatásunk, attól még a Partnerfigyelő szolgáltatás nem fog működni!

A szolgáltatás címe, ahova POST kérést kell küldeni vatnum változóval. A vatnum a figyelendő adótörzsszám (a példa esetében a 25566552):

https://pkapi.hu/api/v1/observer/observ?vatnum=25566552

Fejléc (header) paraméterek:

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

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

{
  "observed": "2017-01-24 19:22:37"
}

A válaszban az API visszaadja a megfigyelés kezdetét. Ha még nem volt figyelve az adótörzsszám, akkor az aktuális dátumot és időt adja vissza, ha már meg volt figyelve, akkor azt a dátumot és időt, amikor a megfigyelés el lett indítva.

Válasz séma:

{
  "observed": "ÉÉÉÉ-HH-NN ÓÓ:PP:MM"
}
Figyelés megszüntetése

A szolgáltatás címe, ahova PUT kérést kell küldeni vatnum változóval. A vatnum a tovább már nem figyelendő adótörzsszám (a példa esetében a 25566552):

https://pkapi.hu/api/v1/observer/unobserv?vatnum=25566552

Fejléc (header) paraméterek:

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

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

{
  "unobserved": "2017-02-07 13:49:13"
}

A válaszban az API visszaadja a megfigyelés befejezésének dátumát és időpontját.

Válasz séma:

{
  "unobserved": "ÉÉÉÉ-HH-NN ÓÓ:PP:MM"
}
Figyelés állapota

A szolgáltatás címe, ahova GET kérést kell küldeni vatnum változóval. A vatnum megfigyelt adótörzsszám (a példa esetében a 25566552):

https://pkapi.hu/api/v1/observer/status?vatnum=25566552

Fejléc (header) paraméterek:

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

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

{
    "created": "2018-05-08",
    "hits": {
        "1016146629": {
            "hitid": "1016146629",
            "hitdate": "2016-11-04",
            "heading": "32",
            "chapter": "2"
        },
        "1017459520": {
            "hitid": "1017459520",
            "hitdate": "2017-12-12",
            "heading": "8,13,45",
            "chapter": "2"
        }
    }
}

A válaszban az API visszaadja a megfigyelés kezdetének dátumát és a tárgy évet megelőző év január elseje óta bekövetkezett változások azonosítóit és dátumait.

Válasz séma:

{
  "created": "ÉÉÉÉ-HH-NN",
  "hits": [
    {
        "hitid": {
            "hitid": "Egész szám",
            "hitdate": "ÉÉÉÉ-HH-NN",
            "heading": "Vesszővel tagolt egész számok",
            "chapter": "Egész szám"
        },
        "hitid": {
            ...
        },
        "hitid": {
            "hitid": "Egész szám",
            "hitdate": "ÉÉÉÉ-HH-NN",
            "heading": "Vesszővel tagolt egész számok",
            "chapter": "Egész szám"
        }
    }
  ]
}
Összes figyelés

A szolgáltatás címe, ahova GET kérést kell küldeni:

https://pkapi.hu/api/v1/observer/observing

Fejléc (header) paraméterek:

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

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

{
  "11333579": "2017-01-24 19:22:29",
  "22699701": "2017-01-24 19:22:42",
  "25566552": "2017-01-24 19:22:37",
  "26970989": "2017-01-25 09:04:21"
}

A válaszban az API visszaadja az összes megfigyelt adótörzsszámot és az egyes megfigyelés kezdetéhez tartozó dátumot és időt.

Válasz séma:

{
  "NUM": "ÉÉÉ-HH-NN ÓÓ:PP:MM",
  ...
  "NUM": "ÉÉÉ-HH-NN ÓÓ:PP:MM",
}
Találat letöltése

A szolgáltatás címe, ahova GET kérést kell küldeni hitid változóval, ami a találat azonosítója:

https://cjpdf.hu/api/v1/servepdf?hitid=1015558568

Fejléc (header) paraméterek:

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

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

{
    "pdf": "http://cjpdf.hu/api/v1/viewpdf/2y100XbtGXo54Vho4ILvlKs8puxlN97poiW1bMpxusidQYuLvz2lN3a2",
    "filename": "1-5558568.pdf"
}

A válaszban az API visszaad egy időkorlátos URL-t, ahonnan a PDF fájl letölthető, valamint egy javasolt fájl nevet.

Értesítés találatról

A szolgáltatás naponta egyszer (munkanapokon) egy, a disztribútor által előre meghatározott címre (végpontra) értesítést küld a bekövetkezett változásokról. Példa egy ilyen címre:

https://username:password@domain.tld

A végpont elkészítése és a hitelesítési adatok létrehozása a disztributor feladata.

Az elküldött értesítés ugyanazokat az adatokat tartalmazza JSON formtumban, amit akkor kapunk vissza az API-tól, ha egy adótörzsszám státuszát kérdezzük le.

A szolgáltatás adótörzsszámonként küld értesítést a disztribútornak, aki ez alapján értesítheti az érintett felhasználóit (azokat, akik megfigyelik azt az adótörzsszámot). Értelem szerűen a találatok minden felhasználó és adótörzsszám kombinációban elérhetőek, ugyanazon a találati azonosítón.

Menedzsment funkciók

A PK.API-hoz tartoznak menedzsment funkciók, azonban fontos, hogy megértsd pontosan, nem minden esetben szükséges a menedzsment funkciókat integrálnod.

A szolgáltatás felhasználásához nem kötelező ezeket a funkciókat integrálnod, minden funkciót elérsz az adminisztrációs felületeden, amit bejelentkezés után a baloldali menüben találsz!

Amit a menedzsment funkciókkal csinálni lehet:

  • Összes felhasználó adatainak lekérdezése
  • Egy felhasználó adatainak lekérdezése, beleértve a lekérdezési statisztikáját is
  • Felhasználó előfizetésének érvényességét tudod állítani
  • Felhasználó funkcionális jogosultságát tudod állítani (  vatnum  vagy  name  )

Amint látható, a menedzsment funkciók üzletileg nem minden esetben illeszkednek az alapvető integrációs modellbe. Klasszikusan az a program, amivel a felhasználó használja a PK.API szolgáltatásait, nem azonos azzal, ahonnan az előfizetés érvényességét és a lekérdezési statisztikáit kezeljük.

A további könnyebb megértés érdekében néhány példa menedzsment funkció integrálására:

Natív CRM rendszer pénzügyi modullal, ahol azt tartjuk nyilván, hogy a felhasználónak kiment a díjbekérő a PK.API szolgáltatásra vonatkozóan. Mikor a díjbekérő teljesítésre kerül, akkor akár automatikusan, akár gombnyomásra beállítható a felhasználó előfizetésének érvényessége.

A gördülékeny pénzügyi elszámolás érdekében minden hónap első napján egy automatizmus lekérdezi az összes felhasználó előző havi lekérdezési statisztikáját és készít belőle neked egy kimutatást.

A menedzsment funkciók eléréséhez  admin  funkcionális jogosultság szükséges, amelyet a szolgáltatótól igényelhetsz és egy felhasználóra kerül kiosztásra. Az igényléskor célszerű megírnod, hogy melyik felhasználód lesz a menedzser.

Felhasználók listája

A szolgáltatás címe, ahova GET kérést kell küldeni:

https://pkapi.hu/api/v1/users

Fejléc (header) paraméterek:

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

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

[
  {
    "created": "2017-01-04 15:17:22",
    "userid": "DMO0000001",
    "pksub": "2017-02-04"
  },
  {
    "created": "2017-01-04 15:17:22",
    "userid": "DMO0000009",
    "pksub": "2017-02-04"
    "pksub": "0000-00-00"
  },
  {
    "created": "2017-01-04 15:17:22",
    "userid": "DMO0000018",
    "pksub": "2017-02-04"
  },
  {
    "created": "2017-01-04 15:17:22",
    "userid": "DMO0580001",
    "pksub": "2017-02-04"
    "pksub": "0000-00-00"
  },
  {
    "created": "2017-01-04 15:17:22",
    "userid": "DMO0015001",
    "pksub": "2017-02-04"
  },
]

Válasz séma:

[
  {
    "created": "felhasználó létrehozásának dátuma",
    "userid": "a felhasználó azonosítója a viszonteladó kulccsal az elején",
    "pksub": "Partnerkövető szolgáltatás érvényessége",
    "posub": "Partnerfigyelő szolgáltatás érvényessége"
  },
  ...
  {
    "created": "felhasználó létrehozásának dátuma",
    "userid": "a felhasználó azonosítója a viszonteladó kulccsal az elején",
    "pksub": "Partnerkövető szolgáltatás érvényessége ÉÉÉÉ-HH-NN",
    "posub": "Partnerfigyelő szolgáltatás érvényessége ÉÉÉÉ-HH-NN"
  },
]

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."
}
Felhasználó adatai

A szolgáltatás címe, ahova GET kérést kell küldeni:

https://pkapi.hu/api/v1/user?userid=DMO00000000

Fejléc (header) paraméterek:

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

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

{
  "1612": "924",
  "1701": "224",
  "updated": "2017-01-04 15:16:57",
  "valid": "2017-12-31",
  "userid": "DMO00000000",
  "permission": [
    "admin",
    "name",
    "vatnum"
  ],
  "created": "2017-01-04 00:20:44"
}

Válasz séma:

{
  "1612": "ÉÉHH lekérdezések darabszáma (példa szerint 2016 december)",
  "1701": "ÉÉHH lekérdezések darabszáma (példa szerint 2017 január)",
  "updated": "legutolsó módosítás dátuma",
  "valid": "előfizetés érvényessége, ÉÉÉÉ-HH-NN formában2,3",
  "userid": " DMO00000000",
  "permission": [
    "bállított funkcionális jogosultságok"
  ],
  "created": "létrehozás dátuma ÉÉÉÉ-HH-NN OO:PP:MM formában"
}

A lekérdezési statisztika havi bontásban gyűlik. Az előfizetés felhasználásának indikátor száma, azaz nem csak az számít az elszámolási időszakban, hogy be volt-e állítva a valid mező dátuma érvényesre, hanem az is, hogy adott időszakban volt-e lekérdezés.

2 Ha a valid értéke 0000-00-00 akkor a felhasználó olyan választ kap, amiben minden harmadik karakter csillagra kerül lecserélésre, így egy próbaidőszak után tovább működhet a szolgáltatás, csak értéktelenné válnak az adtok.

3 Ha a valid értéke korábbi, mint a mai dátum, akkor az előfizetés lejárt.

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."
}
Felhasználó előfizetésének beállítása

Ezzel a funkcióval felülírod a felhasználó előfizetésének érvényességét! Mikor adatot módosítasz, legyél körültekintő.

A szolgáltatás címe, ahova PUT kérést kell küldeni  userid   valid   observing  és  subscribed  változókkal:

https://pkapi.hu/api/v1/user?userid=DMO00000000&valid=20171231&observing=20171231&subscribed=20170101

   userid  - felhasználó azaonsító
   valid  - előfizetés érvényessége
   observing  - figyelő szolgáltatás érvényessége
   subscribed  - első előfizetés dátuma

Fejléc (header) paraméterek:

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

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

{
  "1612": "924",
  "1701": "224",
  "updated": "2017-01-04 15:16:57",
  "valid": "2017-12-31",
  "userid": "DMO00000000",
  "permission": [
    "admin",
    "name",
    "vatnum"
  ],
  "created": "2017-01-04 00:20:44"
}

Válasz séma:

{
  "1612": "ÉÉHH lekérdezések darabszáma (példa szerint 2016 december)",
  "1701": "ÉÉHH lekérdezések darabszáma (példa szerint 2017 január)",
  "updated": "legutolsó módosítás dátuma",
  "valid": "előfizetés érvényessége, ÉÉÉÉ-HH-NN formában2,3",
  "userid": " DMO00000000",
  "permission": [
    "beállított funkcionális jogosultságok"
  ],
  "created": "létrehozás dátuma ÉÉÉÉ-HH-NN OO:PP:MM formában"
}

A lekérdezési statisztika havi bontásban gyűlik. Az előfizetés felhasználásának indikátor száma, azaz nem csak az számít az elszámolási időszakban, hogy be volt-e állítva a valid mező dátuma érvényesre, hanem az is, hogy adott időszakban volt-e lekérdezés.

2 Ha a valid értéke 0000-00-00 akkor a felhasználó olyan választ kap, amiben minden harmadik karakter csillagra kerül lecserélésre, így egy próbaidőszak után tovább működhet a szolgáltatás, csak értéktelenné válnak az adtok.

3 Ha a valid értéke korábbi, mint a mai dátum, akkor az előfizetés lejárt.

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."
}
Hibakódok

A szolgáltatás által visszaadott hibakódokat előidézhetjük, hogy könnyebben integrálhatóak legyenek a UI interakciók. Egy hiba generálásához az alábbi címre kell GET kérést küldeni az errorcode változóval (a példában a 1015 hibakóddal):

https://pkapi.hu/api/v1/throwerror?errorcode=1015

Fejléc (header) paraméterek:

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

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

{
  "code": "1015",
  "error": "Not Found",
  "error_description": "The requested search resulted 0 matches."
}
Hibakód Leírás
1001Érvénytelen disztribútor kulcs.
1002Érvénytelen végfelhasználói előfizetés.
1003Érvénytelen disztribútori előfizetés.
1004Rendszerhiba, többszörös felhasználó azonosító.
1005Nem jogosult a rendszer felhasználására.
1006Kötelező adatok hiányoznak a kérés fejlécéből.
1007Érvénytelen hitelesítő adatok.
1008Funkció hozzáférés megtagadva, nincs jogosultság az adószám alapú lekérdezéshez.
1009A megadott adótörzsszámhoz nem található adat.
1010Funkció hozzáférés megtagadva, nincs jogosultság az elnevezés alapú lekérdezéshez.
1011Az elnevezés alapú keresési feltételnek több mint 50 találat felel meg.
1012Az elnevezés alapú keresési feltételnek megfelelő találat nincs.
1013A megadott mezőnév érvénytelen, csak az alábbiak valamelyikét tartalmazhatja: vatnum, name.
1014Kötelező adatok hiányoznak a kérésből (key, value).
1015A megadott azonosítóval nem található felhasználó.
1016A lekérdezést küldő felhasználónak nincs jogosultsága a funkcióhoz.
1017Kötelező adatok hiányoznak a kérésből (userid).
1018Kötelező adatok hiányoznak a kérésből (userid, dkey).
1019Érvénytelen dátum formátum.
1020Hiányzó adat (userid, dkey), vagy érvénytelen dátum formátum (valid, observing, subscribed).
1021Kötelező adatok hiányoznak a kérésből (dkey, userid, vatnum, name, manager, admin).
1022Kötelező adatok hiányoznak a kérésből (vatnum, name, manager, admin).
1023Kötelező adatok hiányoznak a kérésből (dkey).
1024Hibakód nem található.
2001Érvénytelen disztribútor kulcs.
2002Érvénytelen végfelhasználói előfizetés.
2003Événytelen disztribútori előfizetés.
2004Rendszer hiba, többszörös disztribútor azonosító.
2005Nem jogosult a rendszer felhasználására.
2006Kötelező adatok hiányoznak a kérés fejlécéből.
2007Érvénytelen hitelesítő adatok.
2008A megadott adótörzsszámhoz nem található adat.
2009A kért PDF fájl nem található.
2010A megadott azonosítóval nem található adat.
2011Jogosultság megtagadva, ennek a felhasználónak ez a dokumentum nem nyitható meg.