Úvod
Nami poskytované API používa štandardný HTTP protokol. Všetky funkcie API používajú metódu HTTP GET. Každé volanie funkcie vyžaduje autorizáciu dotazu. Údaje na autorizáciu dotazu sa odosielajú v hlavičke HTTP.
Výrobná služba
Vyžaduje sa registrácia subjektu, ktorý chce využívať funkcionalitu systému viesapi.eu. Ak to chcete urobiť, prejdite na stránku Registrácia stránku a vyplňte príslušný formulár. Predpokladom používania systému viesapi.eu je akceptácia Podmienky služby. Správne vyplňte formulár a kliknite na Registrovať tlačidlo vytvorí účet v systéme viesapi.eu a jeho automatickú aktiváciu.
Pri prvom prihlásení sa spolu s príslušným kľúčom automaticky vygeneruje identifikátor. Identifikátor je verejný a nevyžaduje ochranu, zatiaľ čo kľúč je súkromný a nemal by byť sprístupnený tretím stranám.
Adresa výrobnej služby: https://viesapi.eu/api
Testovacia služba
Úplnú funkčnosť všetkých zdieľaných knižníc je možné skontrolovať pomocou zdieľaných knižníc Otestujte VIES API. Pomocou testovacieho API je možné skontrolovať všetky funkcie ponúkané v platených plánoch bez nutnosti vytvorenia účtu.
Adresa testovacej služby: https://viesapi.eu/api-test
Definícia rozhrania API
Podrobná definícia API je k dispozícii vo formáte kompatibilnom s OpenAPI a možno si ju stiahnuť ako súbor YAML tu.
API je dostupné aj ako klientske rozhranie Swagger UI.
Vykonanie dotazu
Príklad vytvorenia dotazu na testovaciu lokalitu:
GET /api-test/get/vies/euvat/PL7171642051 HTTP/1.1
Hostiteľ: viesapi.eu:443
Autorizácia: MAC id="api_key_id", ts="unix_timestamp", nonce="random_str", mac="b64_calculated_mac_value"
User-Agent: VIESAPIClient/client_version názov_platformy/verzia_platformy
Kde:
api_key_id
– identifikátor kľúča API (v produkčnom prostredí hodnota identifikátora vygenerovaného pri registrácii, v testovacom prostredí hodnota test_id),unix_timestamp
– aktuálny čas v tvare počtu sekúnd z tzv unixová epocha,random_str
– náhodný reťazec, odlišný pre každý dopyt (min. 8 znakov, max. 16 znakov),b64_calculated_mac_value
– vypočítaný HMAC (pomocou anAPI key
, hodnotatest_key
v testovacom prostredí),client_version
– verzia klienta (v našich knižniciach je to verzia našej API knižnice, napr. 1.2.3),platform_name
– názov klientskej platformy API (v našich knižniciach je to názov jazyka knižnice, napr. JAVA, PHP, .NET, Python),platform_version
– Verzia platformy API klienta (v našich knižniciach je to verzia knižničného prostredia, napr. 17 pre JAVA alebo 7.4 pre PHP).
Všetky odpovede vrátené webovou stránkou sú vo formáte XML.
Žiadosť o overenie
Špecifikácia použitej autorizačnej metódy: HTTP Authentication: MAC Access Authentication. Každý dotaz na našu webovú stránku musí byť overený touto metódou. Autorizácia spočíva vo výpočte HMAC SHA256 zo správne pripraveného reťazca a odoslaní výsledku v HTTP hlavičke.
Príklad
Vstupný reťazec funkcie HMAC je:
ts + '\n' + nonce + '\n' + method + '\n' + path + '\n' + host + '\n' + port + '\n\n'
Kde:
ts
– aktuálny čas v tvare počtu sekúnd z tzv unixová epocha, mali by ste vždy uviesť aktuálny čas vykonania dotazu (tolerancia servera +/- 10 minút vo vzťahu k aktuálnemu času),nonce
– náhodný reťazec, odlišný pre každý dopyt (min. 8 znakov, max. 16 znakov),method
– názov metódy HTTP (vždy GET),path
– URL cesta dotazu, ktorý sa má vykonať,host
– Názov servera VIES API (vždyviesapi.eu
),port
– číslo portu servera VIES API (vždy 443),’\n’
– znak nového riadku (ASCII kód 10, 0x0A).
Pre dopyt na DIČ PL7171642051 odoslaný do testovacej služby dňa 2019-11-25 00:00:00 UTC bude vstupný reťazec do funkcie HMAC vyzerať takto:
str = "1574640000\ndt831hs59s\nGET\n/api-test/get/vies/euvat/PL7171642051\nviesapi.eu\n443\n\n"
Súbor vstupného reťazca pre tento príklad je možné stiahnuť tu.
Z pripraveného reťazca vypočítame HMAC SHA256, ako heslo HMAC zadáme API key
, teda v prípade testovacieho API hodnotu test_key
:
HMAC_SHA256(str, "test_key") = 7776a12b958233ce60dd0f16b8d141e80472a1ee3b1e1fb136d7abe34cb59306
Funkcia HMAC SHA256 vracia 32 binárnych bajtov (zobrazené vyššie ako a hex
reťazec pre čitateľnosť). Stiahnite si súbor s binárnou hodnotou tu.
Binárna hodnota vypočítaného HMAC by mala byť zakódovaná pomocou algoritmu Base64, dostaneme:
d3ahK5WCM85g3Q8WuNFB6ARyoe47Hh+xNter40y1kwY=
Táto hodnota by mala byť odoslaná ako hodnota MAC v hlavičke s údajmi na autorizáciu. Nakoniec:
Authorization: MAC id="test_id", ts="1574640000", nonce="dt831hs59s", mac="d3ahK5WCM85g3Q8WuNFB6ARyoe47Hh+xNter40y1kwY="
Na počítači so systémom Linux možno požadovanú hodnotu MAC vypočítať v jednom kroku pomocou tohto príkazu:
$ 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