REST API 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
Házigazda: viesapi.eu:443
Engedélyezés: 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

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. JAVA esetén 17, PHP esetén 7.4).

A webhely által visszaküldött összes válasz XML formátumban van.

Hitelesítési kérés

Az alkalmazott engedélyezési módszer leírása: HTTP hitelesítés: MAC hozzáférési hitelesítés. Minden weboldalunkra irányuló lekérdezést hitelesíteni kell ezzel a módszerrel. 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=

This value should be sent as MAC value in the header with data for authorization. Finally:

Authorization: MAC id="test_id", ts="1574640000", nonce="dt831hs59s", mac="d3ahK5WCM85g3Q8WuNFB6ARyoe47Hh+xNter40y1kwY="

On Linux machine required MAC value can be calculated in one step using this command:

$ 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