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