REST API dokumentáció

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 (egy API key, érték test_key a 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 és application/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 (mindig viesapi.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_id húr),
  • key – API kulcs (tesztkörnyezet esetén string test_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 webböngészőből tesztkörnyezetben meghívható lekérdezést mutat be. 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.

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ég be van jegyezve,
  • id – a VIES rendszer által generált egyedi lekérdezési azonosító
  • date – a lekérdezés végrehajtásának dátuma
  • source – 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:

Hiba

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
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