Dokumentace REST API

Úvod

Námi poskytované API používá standardní HTTP protokol. Všechny funkce API používají metodu HTTP GET. Každé volání funkce vyžaduje autorizaci dotazu. Data pro autorizaci dotazu jsou odesílána v HTTP hlavičce.

Produkční služba

Je nutná registrace subjektu, který chce využívat funkcionalitu systému viesapi.eu. Chcete-li to provést, přejděte na stránku Registrace stránku a vyplňte příslušný formulář. Předpokladem pro používání systému viesapi.eu je přijetí Podmínky služby. Správně vyplňte formulář a klikněte na Registrovat tlačítko vytvoří účet v systému viesapi.eu a jeho automatickou aktivaci.

Při prvním přihlášení se spolu s odpovídajícím klíčem automaticky vygeneruje identifikátor. Identifikátor je veřejný a nevyžaduje ochranu, zatímco klíč je soukromý a neměl by být zpřístupněn třetím stranám.

Adresa výrobního servisu: https://viesapi.eu/api

Testovací služba

Plnou funkčnost všech sdílených knihoven lze zkontrolovat pomocí sdílené Otestujte VIES API. Pomocí testovacího API je možné zkontrolovat všechny funkce nabízené v placených plánech bez nutnosti vytvoření účtu.

Adresa testovacího servisu: https://viesapi.eu/api-test

Definice rozhraní API

Podrobná definice API je k dispozici ve formátu kompatibilním s OpenAPI a lze ji stáhnout jako soubor YAML tady.

API je k dispozici také jako klientské rozhraní Uživatelské rozhraní Swagger.

Provedení dotazu

Příklad vytvoření dotazu na testovací web:

ZÍSKEJTE /api-test/get/vies/euvat/PL7171642051 HTTP/1.1
Hostitel: viesapi.eu:443
Autorizace: MAC id="api_key_id", ts="unix_timestamp", nonce="random_str", mac="b64_calculated_mac_value"
User-Agent: VIESAPIClient/verze_klienta název_platformy/verze_platformy

Kde:

  • api_key_id – identifikátor API klíče (v produkčním prostředí hodnota identifikátoru vygenerovaného při registraci, v testovacím prostředí hodnota test_id),
  • unix_timestamp – aktuální čas v podobě počtu sekund z tzv unixová epocha,
  • random_str – náhodný řetězec, pro každý dotaz jiný (min. 8 znaků, max. 16 znaků),
  • b64_calculated_mac_value – vypočítaný HMAC (pomocí an API key, hodnota test_key v testovacím prostředí),
  • client_version – klientská verze (v našich knihovnách je to verze naší API knihovny, např. 1.2.3),
  • platform_name – název klientské platformy API (v našich knihovnách je to název jazyka knihovny, např. JAVA, PHP, .NET, Python),
  • platform_version – Verze platformy API klienta (v našich knihovnách je to verze prostředí knihovny, např. 17 pro JAVA nebo 7.4 pro PHP).

Všechny odpovědi vrácené webem jsou ve formátu XML.

Žádost o ověření

Autorizační údaje musí být připraveny v souladu s HTTP Authentication: MAC Access Authentication a toto je doporučená metoda ověřování. Je také možné použít HTTP Authentication: Základní Authentication metodu, avšak z bezpečnostních důvodů ji prosím používejte pouze v případě, že použití první metody není z nějakého důvodu možné.

Každý dotaz na naše webové stránky musí být ověřen pomocí jedné ze dvou dostupných metod.

Metoda 1 – HMAC (doporučeno)

Specifikace použitého způsobu autorizace: HTTP Authentication: MAC Access Authentication. Autorizace spočívá ve výpočtu HMAC SHA256 ze správně připraveného řetězce a odeslání výsledku v HTTP hlavičce.

Příklad

Vstupní řetězec funkce HMAC je:
ts + '\n' + nonce + '\n' + method + '\n' + path + '\n' + host + '\n' + port + '\n\n'

Kde:

  • ts – aktuální čas v podobě počtu sekund z tzv unixová epocha, měli byste vždy uvést aktuální čas provádění dotazu (tolerance serveru +/- 10 min ve vztahu k aktuálnímu času),
  • nonce – náhodný řetězec, pro každý dotaz jiný (min. 8 znaků, max. 16 znaků),
  • method – název metody HTTP (vždy GET),
  • path – URL cesta dotazu, který se má provést,
  • host – Název serveru VIES API (vždy viesapi.eu),
  • port – Číslo portu serveru VIES API (vždy 443),
  • ’\n’ – znak nového řádku (ASCII kód 10, 0x0A).

Pro dotaz na DIČ PL7171642051 odeslaný do testovací služby dne 2019-11-25 00:00:00 UTC bude vstupní řetězec do funkce HMAC vypadat takto:
str = "1574640000\ndt831hs59s\nGET\n/api-test/get/vies/euvat/PL7171642051\nviesapi.eu\n443\n\n"

Soubor vstupního řetězce pro tento příklad lze stáhnout tady.

Z připraveného řetězce vypočítáme HMAC SHA256, jako heslo HMAC zadáme API key, tedy v případě testovacího API hodnotu test_key:

HMAC_SHA256(str, "test_key") = 7776a12b958233ce60dd0f16b8d141e80472a1ee3b1e1fb136d7abe34cb59306

Funkce HMAC SHA256 vrací 32 binárních bajtů (viz výše jako a hex řetězec pro čitelnost). Stáhnout soubor s binární hodnotou tady.

Binární hodnota vypočteného HMAC by měla být zakódována pomocí algoritmu Base64, dostaneme:

d3ahK5WCM85g3Q8WuNFB6ARyoe47Hh+xNter40y1kwY=

Tato hodnota by měla být odeslána jako MAC hodnota v hlavičce s daty pro autorizaci. Konečně:

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

Na počítači se systémem Linux lze požadovanou hodnotu MAC vypočítat v jednom kroku pomocí tohoto pří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

Metoda 2 – Základní autentizace

Specifikace tohoto použitého způsobu autorizace: HTTP Authentication: Základní Authentication.

Příklad 1

Vstupní řetězec funkce Base64 je:

str = key_id + ':' + klíč

Kde:

  • key_id – identifikátor klíče API (v případě testovacího prostředí, test_id tětiva),
  • key – API klíč (v případě testovacího prostředí řetězec test_key).

Pro testovací prostředí bude vstupní řetězec pro funkci Base64:

str = "test_id:test_key"

Po použití funkce Base64 dostaneme:

Base64(str) = dGVzdF9pZDp0ZXN0X2tleQ==

Tato hodnota by měla být odeslána jako Základní hodnota v hlavičce s daty pro autorizaci. Nakonec:

Oprávnění: Základní dGVzdF9pZDp0ZXN0X2tleQ==

Příklad 2

Následující příklad ukazuje dotaz, který lze vyvolat v testovacím prostředí z webového prohlížeče. Stačí jej zkopírovat a vložit do adresního řádku prohlížeče:

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

Kde:

  • test_id – ověřit v produkci životní prostředí, parametr by měl obsahovat platný identifikátor klíče použitý pro autorizaci,
  • test_key – ověřit v produkci prostředí by měl parametr obsahovat platnou hodnotu klíče použitého pro autorizaci.

Identifikátor klíče a klíč vygeneruje uživatel po přihlášení ke svému účtu na viesapi.eu portál (API keys karta). See, dokumentace Další informace o generování ID a klíčů najdete na stránce.

Odezva

Pokud je požadavek zpracován správně, vygeneruje se následující odpověď:

Podrobný popis vrácených atributů:

  • uid – jedinečný identifikátor dotazu generovaný viesapi.eu,
  • countryCode – kód země, ve které je registrována společnost spojená s EU DIČ uvedeným v dotazu,
  • vatNumber – EU DIČ ověřené společnosti uvedené v dotazu,
  • valid – odpověď ze služby VIES, informující o aktuálním stavu EU DPH kontrolovaného subjektu:
    • true – je platné EU DIČ uvedené v dotazu,
    • false – DIČ EU uvedené v dotazu není platné,
  • traderName - obchodní jméno společnosti,
  • traderCompanyType – vždy vrátil řetězec znaků '-',
  • traderAddress - adresa společnosti, kde je společnost registrována,
  • id – jedinečný identifikátor dotazu generovaný systémem VIES
  • date – datum provedení dotazu
  • source – zdroj dat, vždy: http://ec.europa.eu

Odezva na chybu

V případě jakékoli chyby související s vyřízením požadavku se vrátí následující chybová zpráva:

Chyba

Podrobný popis vrácených atributů:

  • code – jedinečný chybový kód pro automatické zpracování chyb,
  • description – popis chyby zachytitelné člověkem,
  • details – mpodrobný popis chyby (volitelné),