VIES API REST dokumentáció
Bevezetés
Az általunk biztosított API a szabványos HTTP protokollt használja. Minden API-funkció a HTTP GET metódusát használja. Minden függvényhívás lekérdezési jogosultságot igényel. A lekérdezés engedélyezésére szolgáló adatok a HTTP-fejlécben kerülnek elküldésre.
Gyártási szolgáltatás
A viesapi.eu rendszer funkcióit használni kívánó entitás regisztrációja szükséges. Ehhez lépjen a Bejegyzés oldalt, és töltse ki a megfelelő űrlapot. A viesapi.eu rendszer használatának előfeltétele a Szolgáltatási feltételek. Az űrlap helyes kitöltése és a gombra kattintva Regisztráció gomb megnyomásával fiókot hoz létre a viesapi.eu rendszerben és annak automatikus aktiválását.
Az első bejelentkezéskor automatikusan generál egy azonosítót a megfelelő kulccsal együtt. Az azonosító nyilvános és nem igényel védelmet, míg a kulcs privát, és nem szabad harmadik fél számára hozzáférhetővé tenni.
Gyártási szolgáltatás címe: https://viesapi.eu/api
Teszt szolgáltatás
Az összes megosztott könyvtár teljes funkcionalitása ellenőrizhető a megosztott segítségével Tesztelje a VIES API-t. A teszt API használatával lehetőség nyílik a fizetős csomagokban kínált összes funkció ellenőrzésére fiók létrehozása nélkül.
Teszt szerviz címe: https://viesapi.eu/api-test
API interfész definíció
Az API részletes meghatározása OpenAPI-kompatibilis formátumban érhető el, és letölthető YAML-fájlként itt.
Az API kliens felületként is elérhető Swagger UI.
A lekérdezés végrehajtása
Példa a tesztoldal lekérdezésére:
GET /api-test/get/vies/euvat/PL7171642051 HTTP/1.1
Host: viesapi.eu:443
Authorization: MAC id="api_key_id", ts="unix_timestamp", nonce="random_str", mac="b64_calculated_mac_value"
User-Agent: VIESAPIClient/client_version platform_name/platform_version
Accept: mime_type
Ahol:
api_key_id– API kulcs azonosító (éles környezetben a regisztráció során generált azonosító értéke, tesztkörnyezeten a test_id értéke),unix_timestamp– az aktuális idő másodpercszám formájában az ún unix korszak,random_str– véletlenszerű karakterlánc, lekérdezésenként eltérő (min. 8 karakter, max. 16 karakter),b64_calculated_mac_value– számított HMAC (egyAPI key, értéktest_keya tesztkörnyezetben),client_version– kliens verzió (könyvtárainkban az API könyvtárunk verziója, pl. 1.2.3),platform_name– az API kliens platform neve (könyvtárainkban a könyvtári nyelv neve, pl. JAVA, PHP, .NET, Python),platform_version– API kliens platform verziója (könyvtárainkban ez a könyvtári környezet verziója, pl. 17 JAVA-hoz vagy 7.4 PHP-hez),mime_type– MIME típusnév, amelyben a választ vissza kell adni, két típus támogatott:text/xmlésapplication/json, ha a kérés nem tartalmazza az Accept fejlécet, akkor alapértelmezés szerint XML-t ad vissza.
Hitelesítési kérés
szerint kell elkészíteni az engedélyezési adatokat HTTP hitelesítés: MAC hozzáférési hitelesítés és ez az ajánlott hitelesítési módszer. Lehetőség van arra is, hogy a HTTP hitelesítés: Alapszintű hitelesítés módszert, azonban biztonsági okokból csak akkor használja, ha az első módszer használata valamilyen okból nem lehetséges.
Minden weboldalunkra irányuló lekérdezést hitelesíteni kell a két elérhető módszer valamelyikével.
1. módszer – HMAC (ajánlott)
Az alkalmazott engedélyezési módszer leírása: HTTP hitelesítés: MAC hozzáférési hitelesítés. Az engedélyezés a HMAC SHA256 kiszámításából áll egy megfelelően előkészített karakterláncból, és az eredmény elküldéséből a HTTP fejlécben.
Példa
A HMAC függvény bemeneti karakterlánca a következő:
ts + '\n' + nonce + '\n' + method + '\n' + path + '\n' + host + '\n' + port + '\n\n'
Ahol:
ts– az aktuális idő másodpercszám formájában az ún unix korszak, mindig meg kell adnia az aktuális lekérdezés végrehajtási idejét (a szerver tolerancia +/- 10 perc az aktuális időhöz képest),nonce– véletlenszerű karakterlánc, lekérdezésenként eltérő (min. 8 karakter, max. 16 karakter),method– HTTP metódus neve (mindig GET),path– a végrehajtandó lekérdezés URL elérési útja,host– VIES API szerver neve (mindigviesapi.eu),port– VIES API szerver portszáma (mindig 443),’\n’– újsor karakter (ASCII kód 10, 0x0A).
A tesztszolgáltatásnak 2019-11-25 00:00:00 UTC-n küldött PL7171642051 adószámra vonatkozó lekérdezés esetén a HMAC függvény bemeneti karakterlánca így fog kinézni:
str = "1574640000\ndt831hs59s\nGET\n/api-test/get/vies/euvat/PL7171642051\nviesapi.eu\n443\n\n"
A példa input string fájlja letölthető itt.
Az elkészített karakterláncból a HMAC SHA256-ot számítjuk ki, HMAC jelszóként megadjuk a API key, azaz a teszt API esetén az értéke test_key:
HMAC_SHA256(str, "test_key") = 7776a12b958233ce60dd0f16b8d141e80472a1ee3b1e1fb136d7abe34cb59306
A HMAC SHA256 függvény 32 bináris bájtot ad vissza (fent a hex karakterlánc az olvashatóság érdekében). Bináris értékű fájl letöltése itt.
A számított HMAC bináris értékét a Base64 algoritmussal kell kódolni, így kapjuk:
d3ahK5WCM85g3Q8WuNFB6ARyoe47Hh+xNter40y1kwY=
Ezt az értéket MAC-értékként kell elküldeni az engedélyezési adatokkal együtt a fejlécben. Végül:
Authorization: MAC id="test_id", ts="1574640000", nonce="dt831hs59s", mac="d3ahK5WCM85g3Q8WuNFB6ARyoe47Hh+xNter40y1kwY="
Linuxos gépen a szükséges MAC érték egy lépésben kiszámítható a következő paranccsal:
$ echo -e -n "1574640000\ndt831hs59s\nGET\n/api-test/get/vies/euvat/PL7171642051\nviesapi.eu\n443\n\n" | openssl dgst -sha256 -hmac "test_key" -binary | openssl enc -base64
2. módszer – Alapszintű hitelesítés
Az alkalmazott engedélyezési módszer leírása: HTTP hitelesítés: Alapszintű hitelesítés.
1. példa
A Base64 függvény bemeneti karakterlánca a következő:
str = key_id + ':' + key
Ahol:
key_id– API kulcs azonosító (tesztkörnyezet esetén,test_idhúr),key– API kulcs (tesztkörnyezet esetén stringtest_key).
A tesztkörnyezetben a Base64 függvény bemeneti karakterlánca a következő lesz:
str = "test_id:test_key"
A Base64 függvény alkalmazása után a következőket kapjuk:
Base64(str) = dGVzdF9pZDp0ZXN0X2tleQ==
Ezt az értéket Basic értékként kell elküldeni a fejlécben az engedélyezési adatokkal együtt. Végül:
Authorization: Basic dGVzdF9pZDp0ZXN0X2tleQ==
2. példa
A következő példa egy olyan lekérdezést mutat be, amelyet a Tesztkörnyezet webböngészőből. Csak másolja ki és illessze be a böngésző címsorába:
https://test_id:test_key@viesapi.eu/api-test/get/vies/euvat/PL7171642051
Ahol:
test_id– hitelesíteni egy produkcióban környezet, a paraméternek tartalmaznia kell az engedélyezéshez használt érvényes kulcsazonosítót,test_key– hitelesíteni egy produkcióban környezetben, a paraméternek tartalmaznia kell az engedélyezéshez használt kulcs érvényes értékét.
A kulcsazonosítót és a kulcsot a felhasználó állítja elő, miután bejelentkezett a fiókjába viesapi.eu portál (API keys lap). See az dokumentáció oldalon talál további információkat az azonosítóról és a kulcsgenerálásról.
getVIESData válasz
Ha a kérést megfelelően kezelték, a következő válasz jön létre:
A visszaadott attribútumok részletes leírása:
uid– a viesapi.eu által generált egyedi lekérdezési azonosító,countryCode– országkód, amelyben a megkeresésben megadott EU-adószámmal összefüggő céget bejegyezték,vatNumber– a megkeresésben megadott ellenőrzött cég EU adószáma,valid– a VIES szolgáltatás válasza, amely tájékoztat az ellenőrzött entitás aktuális EU ÁFA státuszáról:true– a megkeresésben megadott EU adószám érvényes,false– a megkeresésben megadott EU adószám nem érvényes,
traderName- a cég kereskedelmi neve,traderCompanyType– mindig egy „-” karakterláncot adott vissza,traderAddress– a cég címe, ahol a céget bejegyezték (eredeti formátum),traderAddressComponent– komponens csoportosítási cím adatai – opcionális attribútum, soha nem ad vissza ebben a függvényben.id– a VIES rendszer által generált egyedi lekérdezési azonosító (Konzultációs szám),date– a lekérdezés végrehajtásának dátumasource– adatforrás, mindig: http://ec.europa.eu
getVIESDataParsed válasz
Ha a kérést megfelelően kezelték, a következő válasz jön létre:
A visszaadott attribútumok részletes leírása:
uid– a viesapi.eu által generált egyedi lekérdezési azonosító,countryCode– országkód, amelyben a megkeresésben megadott EU-adószámmal összefüggő céget bejegyezték,vatNumber– a megkeresésben megadott ellenőrzött cég EU adószáma,valid– a VIES szolgáltatás válasza, amely tájékoztat az ellenőrzött entitás aktuális EU ÁFA státuszáról:true– a megkeresésben megadott EU adószám érvényes,false– a megkeresésben megadott EU adószám nem érvényes,
traderName– cégbejegyzési név (eredeti formátum),traderNameComponents– az alkotóelem-csoportosulás társasági formája:name– cégnév a kereskedőNevéből (jogi forma nélkül),legalForm– a kereskedő neve alapján kinyert jogi forma neve (cégnév nélkül),legalFormCanonicalId– a jogi forma szótári azonosítója,legalFromCanonicalName– a jogi forma szótári neve,
traderCompanyType– mindig egy „-” karakterláncot adott vissza,traderAddress– a cég címe, ahol a céget bejegyezték (eredeti formátum),traderAddressComponent– komponenscsoport címének részletei:country– a kereskedő országának neve a nemzeti nyelvén,postalCode– a kereskedő címének irányítószáma,city– a kereskedő címének városa,street- a kereskedő címének utcaneve,streetNumber– a kereskedő címének házszáma,houseNumber– a kereskedő címének házszáma,
id– a VIES rendszer által generált egyedi lekérdezési azonosító (Konzultációs szám),date- a lekérdezés végrehajtásának dátuma,source– adatforrás, mindig: http://ec.europa.eu
| jogi űrlap Kanonikus azonosító | jogi űrlap Kanonikus név | könyvtár enum neve |
| 0 | Ismeretlen | ISMERETLEN |
| 1 | Egyéni vállalkozás | EGYÉNI TULAJDONOS |
| 2 | Korlátolt felelősségű társaság | KORLÁTOLT FELELŐSSÉGŰ_TÁRSASÁG |
| 3 | Közkereseti társaság | ÁLTALÁNOS PARTNERSÉG |
| 4 | Részvénytársaság | KÖZÖS_RÉSZVÁLLALAT |
| 5 | Betéti társaság | KORLÁTOZOTT PARTNERSÉG |
| 6 | Korlátolt felelősségű társaság | KORLÁTOZOTT FELELŐSSÉGŰ MAGÁNSZEMÉLYES VÁLLALAT |
| 7 | Egyszemélyes részvénytársaság | EGYTAGOS_KÖZÖS_RÉSZVÉNYTÁRSASÁG |
| 8 | Egyszerű korlátolt felelősségű társaság | EGYSZERŰ_KORLÁTOZOTT_FELELŐSSÉGŰ_VÁLLALAT |
| 9 | Egyszemélyes korlátolt felelősségű társaság | EGYTAGÚ_KORLÁTOZOTT_FELELŐSSÉGŰ_VÁLLALAT |
| 10 | Egyszerűsített részvénytársaság | EGYSZERŰSÍTETT_KÖZÖS_RÉSZVÉNYTÁRSASÁG |
| 11 | Kisvállalat | KIS_VÁLLALAT |
| 12 | Korlátolt felelősségű társaság | KORLÁTOLT_RÉSZVÉNY_PARTNERSÉG |
| 13 | Szakmai partnerség | SZAKMAI_PARTNERSÉG |
| 14 | Korlátolt felelősségű társaság | KORLÁTOZOTT_FELELŐSSÉGŰ_TÁRSASÁG |
| 15 | Magánpartnerség | MAGÁN_PARTNERSÉG |
| 16 | Korlátolt felelősségű társaság Betéti társaság | KORLÁTOZOTT_FELELŐSSÉGŰ_TÁRSASÁG_KORLÁTOZOTT_PARTNERSÉG |
| 17 | Korlátolt felelősségű társaság Korlátolt felelősségű társaság | KORLÁTOLT_FELELŐSSÉGŰ_TÁRSASÁG_KORLÁTOLT_FELMÉRÉSŰ_KÖZÖS_RÉSZVÉNYTÁRSASÁG |
| 18 | Közintézmény | KÖZINTÉZMÉNY |
Fontos Jogi nyilatkozat!
Az elemző funkció külső mesterséges intelligencia algoritmusokat és API-kat használ az olyan attribútumok automatikus kinyerésére, mint: város, irányítószám, utca utcaszámmal (épületszám) és házszám, így nem tudjuk garantálni az 100% megfelelő működését.
getVIESDataAsync válasz
Ha a kérést megfelelően kezelték, a következő válasz jön létre:
A visszaadott attribútumok részletes leírása:
token– a viesapi.eu által generált batch token (guid), a getVIESDataAsync (2-3 perc múlva) függvény meghívására kell használni az eredmények eléréséhez.
getVIESDataAsyncResult válasz
Ha a kérést megfelelően kezelték, a következő választ kell generálni, amely tartalmazza a VIES által visszaadott adatokkal rendelkező objektumok listáját:
A visszaadott attribútumok részletes leírása:
numbers– objektumok tömbje a VIES által visszaadott eredményekkel, amelyek megfelelnek a getVIESDataAsync függvényhívási kérésben elküldött EU adószámoknakuid– a viesapi.eu által generált egyedi lekérdezési azonosító,countryCode– országkód, amelyben a megkeresésben megadott EU-adószámmal összefüggő céget bejegyezték,vatNumber– a megkeresésben megadott ellenőrzött cég EU adószáma,valid– a VIES szolgáltatás válasza, amely tájékoztat az ellenőrzött entitás aktuális EU ÁFA státuszáról:true– a megkeresésben megadott EU adószám érvényes,false– a megkeresésben megadott EU adószám nem érvényes,
traderName- a cég kereskedelmi neve,traderCompanyType– mindig egy „-” karakterláncot adott vissza,traderAddress– a cég címe, ahol a céget bejegyezték (eredeti formátum),id– a VIES rendszer által generált egyedi lekérdezési azonosító (Konzultációs szám),date– a lekérdezés végrehajtásának dátumasource– adatforrás, mindig: http://ec.europa.eu
errors– a VIES által a getVIESDataAsync függvényhívási kérésben elküldött EU adószámadatokhoz hibás objektumok tömbjeuid– a viesapi.eu által generált egyedi lekérdezési azonosító,countryCode– országkód, amelyben a megkeresésben megadott EU-adószámmal összefüggő céget bejegyezték,vatNumber– a megkeresésben megadott ellenőrzött cég EU adószáma,error– az erre a konkrét EU-adószámra visszaküldött hiba részleteitdate– a lekérdezés végrehajtásának dátumasource– adatforrás, mindig: http://ec.europa.eu
Hiba válasz
A kérelem kezelésével kapcsolatos bármilyen hiba esetén a következő hibaüzenet jelenik meg:
A visszaadott attribútumok részletes leírása:
code- egyedi hibakód az automatikus hibakezeléshez,description– ember által felfogható hibaleírás,details– mrészletes hibaleírás (opcionális),
Hibakódok
Az alábbi táblázat felsorolja a REST API-k és programkönyvtárak által visszaadott összes lehetséges hibát:
| Hibakód | Hibaüzenet |
| 8 | Érvénytelen kérésformátum |
| 10 | Érvénytelen API-útvonal |
| 11 | Belső szolgáltatási hiba |
| 22 | Az EU-s adószám érvénytelen |
| 23 | Nem sikerült lekérni az adatokat a VIES rendszerből |
| 26 | Ez a funkció nem érhető el a jelenleg kiválasztott csomagban |
| 27 | Ez a funkció nem támogatja ezt a keresési módot |
| 33 | A megadott adatok lekérdezése teszt módban nem lehetséges |
| 35 | Nincs szükség hozzáférési lekérdezési jogosultságra |
| 36 | A szolgáltatás ütemezett műszaki munkák miatt átmenetileg nem elérhető |
| 43 | Az aktuális hónap felhasználói lekérdezések számát nem sikerült lekérni |
| 54 | Helytelen dátum vagy idő a felhasználó számítógépén vagy rendszerén |
| 55 | Érvénytelen MAC karakterlánc-érték a fejlécben a lekérdezési hitelesítő adatokkal |
| 57 | Érvénytelen kulcsérték a fejlécben a lekérdezési hitelesítő adatokkal |
| 58 | Elérte az egyidejű lekérdezések maximális számát ebben a tagállamban |
| 59 | A tagállamban benyújtott kérelem nem válaszol, vagy nem érhető el |
| 62 | A köteg feldolgozása még folyamatban van, próbálkozzon újra későn |
| 63 | Elérte a kötegelt kérések maximális számát, kérjük, küldje be újra kérését később |
| 101 | A kapcsolat IP-száma nem egyezik az API-kulcshoz rendelt IP-számmal |
| 102 | Az API kulcs le van tiltva |
| 103 | Érvénytelen API-kulcs |
| 104 | Elérte a kiválasztott tervhez elérhető lekérdezések maximális számát |
| 105 | Fiók blokkolva vagy törölve |
| 106 | Érvénytelen fióktípus |
| 107 | Az előre fizetett számlát nem fizették ki |
| 108 | Érvénytelen API-kulcsazonosító |
| 201 | Nem sikerült csatlakozni a VIES API szolgáltatáshoz |
| 202 | A VIES API-szolgáltatás válaszának formátuma érvénytelen |
| 203 | Érvénytelen számtípus |
| 204 | A NIP érvénytelen |
| 205 | Az EU-s áfaazonosító érvénytelen |
| 206 | A függvény kivételt generált |
| 207 | A dátum formátuma érvénytelen |
| 208 | Érvénytelen bemeneti paraméter |
| 209 | Kötegméret-korlát túllépve [3-99] |