Dokumentácia REST API

Ú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é),