Dokumentácia REST API

Dokumentácia VIES API REST

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

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 an API key, hodnota test_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 klientskej platformy API (v našich knižniciach je to verzia knižničného prostredia, napr. 17 pre JAVA alebo 7.4 pre PHP),
  • mime_type – Názov typu MIME, v ktorom sa má vrátiť odpoveď, sú podporované dva typy: text/xml a application/json, ak požiadavka neobsahuje hlavičku Accept, štandardne sa vráti XML.

Žiadosť o overenie

Autorizačné údaje musia byť pripravené v súlade s HTTP Authentication: MAC Access Authentication a toto je odporúčaná metóda overovania. Je tiež možné použiť HTTP autentifikácia: Základná autentifikácia metódu, avšak z bezpečnostných dôvodov ju prosím používajte len vtedy, keď použitie prvej metódy nie je z nejakého dôvodu možné.

Každý dotaz na našu webovú stránku musí byť overený jednou z dvoch dostupných metód.

Metóda 1 – HMAC (odporúčané)

Špecifikácia použitej autorizačnej metódy: HTTP Authentication: MAC Access Authentication. 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ždy viesapi.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

Metóda 2 – Základná autentifikácia

Špecifikácia tejto použitej autorizačnej metódy: HTTP autentifikácia: Základná autentifikácia.

Príklad 1

Vstupný reťazec funkcie Base64 je:

str = key_id + ':' + key

Kde:

  • key_id – identifikátor kľúča API (v prípade testovacieho prostredia, test_id reťazec),
  • key – API kľúč (v prípade testovacieho prostredia reťazec test_key).

Pre testovacie prostredie bude vstupný reťazec pre funkciu Base64:

str = "test_id:test_key"

Po použití funkcie Base64 dostaneme:

Base64(str) = dGVzdF9pZDp0ZXN0X2tleQ==

Táto hodnota by mala byť odoslaná ako Základná hodnota v hlavičke s údajmi na autorizáciu. Nakoniec:

Authorization: Basic dGVzdF9pZDp0ZXN0X2tleQ==

Príklad 2

Nasledujúci príklad ukazuje dotaz, ktorý je možné vyvolať v testovacom prostredí z webového prehliadača. Stačí ho skopírovať a prilepiť do panela s adresou prehliadača:

https://test_id:test_key@viesapi.eu/api-test/get/vies/euvat/PL7171642051

Kde:

  • test_id – overiť v inscenácii životné prostredie, parameter by mal obsahovať platný identifikátor kľúča používaný na autorizáciu,
  • test_key – overiť v inscenácii v prostredí, parameter by mal obsahovať platnú hodnotu kľúča použitého na autorizáciu.

Identifikátor kľúča a kľúč vygeneruje užívateľ po prihlásení sa do svojho účtu na viesapi.eu portál (API keys karta). See, dokumentáciu pre viac informácií o ID a generovaní kľúčov.

odpoveď

Ak je požiadavka spracovaná správne, vygeneruje sa nasledujúca odpoveď:

Podrobný popis vrátených atribútov:

  • uid – jedinečný identifikátor dopytu vygenerovaný viesapi.eu,
  • countryCode – kód krajiny, v ktorej je registrovaná spoločnosť spojená s EÚ IČ DPH uvedeným v dopyte,
  • vatNumber – IČ DPH overenej spoločnosti v EÚ uvedené v dopyte,
  • valid – odpoveď zo služby VIES, informujúca o aktuálnom stave EÚ DPH kontrolovaného subjektu:
    • true – je platné EÚ IČ DPH uvedené v dopyte,
    • false – IČ DPH EÚ uvedené v dopyte nie je platné,
  • traderName - obchodné meno spoločnosti,
  • traderCompanyType – vždy vrátil reťazec znakov „-“,
  • traderAddress - adresa spoločnosti, kde je spoločnosť registrovaná,
  • id – jedinečný identifikátor dopytu vygenerovaný systémom VIES
  • date – dátum vykonania dotazu
  • source – zdroj údajov, vždy: http://ec.europa.eu

Chybová odpoveď

V prípade akejkoľvek chyby súvisiacej s vybavovaním požiadavky sa vráti nasledujúce chybové hlásenie:

Chyba

Podrobný popis vrátených atribútov:

  • code – jedinečný chybový kód pre automatické spracovanie chýb,
  • description – popis chyby zachytiteľnej človekom,
  • details – mpodrobný popis chyby (voliteľné),

Chybové kódy

V tabuľke nižšie sú uvedené všetky možné chyby vrátené rozhraniami REST API a programovacími knižnicami:

Kód chyby Chybové hlásenie
8 Neplatný formát žiadosti
10 Neplatná cesta API
11 Interná chyba služby
22 IČ DPH EÚ je neplatné
23 Nepodarilo sa získať údaje zo systému VIES
26 Táto funkcia nie je dostupná v aktuálne vybranom pláne
27 Táto funkcia nepodporuje tento režim vyhľadávania
33 Dopyt na zadané údaje nie je v testovacom režime možný
35 Nevyžaduje sa žiadna autorizácia prístupového dotazu
36 Služba je dočasne nedostupná z dôvodu plánovaných technických prác
43 Počet používateľských dopytov za aktuálny mesiac sa nepodarilo získať
54 Nesprávny dátum alebo čas v počítači alebo systéme používateľa
55 Neplatná hodnota reťazca MAC v hlavičke s povereniami dopytu
57 Neplatná hodnota kľúča v hlavičke s povereniami dopytu
58 Dosiahol sa maximálny počet súbežných dopytov pre tento členský štát
59 Aplikácia v členskom štáte neodpovedá alebo nie je dostupná
101 Číslo IP pripojenia sa nezhoduje s číslom IP priradeným kľúču API
102 Kľúč API je zablokovaný
103 Neplatný kľúč API
104 Bol dosiahnutý maximálny počet dopytov dostupných pre vybratý plán
105 Účet je zablokovaný alebo odstránený
106 Neplatný typ účtu
107 Predplatený účet nebol zaplatený
108 Neplatné ID kľúča API
201 Nepodarilo sa pripojiť k službe VIES API
202 Odpoveď služby VIES API má neplatný formát
203 Neplatný typ čísla
204 NIP je neplatný
205 IČ DPH EÚ je neplatné
206 Funkcia vygenerovala výnimku
207 Dátum má neplatný formát
208 Neplatný vstupný parameter