Dokumentace REST API

Dokumentace VIES API REST

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

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 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),
  • mime_type – Název typu MIME, ve kterém má být vrácena odpověď, jsou podporovány dva typy: text/xml a application/json, pokud požadavek neobsahuje hlavičku Accept, je standardně vráceno 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 + ':' + key

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:

Authorization: Basic dGVzdF9pZDp0ZXN0X2tleQ==

Příklad 2

Následující příklad ukazuje dotaz, který lze vyvolat v a Testovací 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.

getVIESData odpověď

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

vies api - getVIESDataParsed

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 (originální formát),
  • traderAddressComponent – detaily adresy seskupení komponent – volitelný atribut, nebude v této funkci nikdy vrácen.
  • id – jedinečný identifikátor dotazu generovaný systémem VIES (Consultation Number),
  • date – datum provedení dotazu
  • source – zdroj dat, vždy: http://ec.europa.eu

getVIESDataParsed odpověď

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

vies api - getVIESDataParsed

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 (originální formát),
  • traderAddressComponent – detaily adresy seskupení komponent
    • country – název země obchodníka v jejím národním jazyce
    • postalCode – PSČ adresy obchodníka
    • city – město adresy obchodníka
    • street -ulice adresy obchodníka
    • streetNumber – číslo adresy obchodníka
    • houseNumber – číslo domu adresy obchodníka
  • id – jedinečný identifikátor dotazu generovaný systémem VIES (Consultation Number),
  • date - datum provedení dotazu,
  • source – zdroj dat, vždy: http://ec.europa.eu

Důležité upozornění!

Funkce analýzy používá externí algoritmy AI a rozhraní API k automatickému extrahování atributů, jako jsou: město, PSČ, ulice s číslem ulice (číslo budovy) a číslo domu, takže nemůžeme zaručit správné fungování jeho 100%.

getVIESDataAsync odpověď

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

Odpověď getVIESDataAsync rozhraní VIES API

Podrobný popis vrácených atributů:

  • token – dávkový token (guid) generovaný viesapi.eu, by měl být použit k volání funkce getVIESDataAsync (po 2-3 minutách), aby se získaly výsledky.

getVIESDataAsyncResult odpověď

Pokud je požadavek správně zpracován, měla by být vygenerována následující odpověď obsahující seznam objektů s daty vrácenými VIES:

přes api getVIESDataAsyncResults

Podrobný popis vrácených atributů:

  • numbers – pole objektů s výsledky vrácenými VIES odpovídajícími číslům DPH EU odeslaným v žádosti o volání funkce getVIESDataAsync
    • 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 (originální formát),
    • id – jedinečný identifikátor dotazu generovaný systémem VIES (Consultation Number),
    • date – datum provedení dotazu
    • source – zdroj dat, vždy: http://ec.europa.eu
  • errors – pole objektů s chybami vrácenými VIES pro údaje o DIČ EU odeslané v žádosti o volání funkce getVIESDataAsync
    • 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,
    • error – podrobnosti o chybě vrácené pro toto konkrétní číslo DPH EU
    • 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:

vies rest api error response

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

Kódy chyb

Níže uvedená tabulka uvádí všechny možné chyby vrácené rozhraními REST API a programovacími knihovnami:

Kód chyby Chybová zpráva
8 Neplatný formát požadavku
10 Neplatná cesta API
11 Chyba interní služby
22 DIČ EU je neplatné
23 Nepodařilo se získat data ze systému VIES
26 Tato funkce není v aktuálně vybraném plánu dostupná
27 Tato funkce nepodporuje tento režim vyhledávání
33 Dotazování na zadaná data není v testovacím režimu možné
35 Není vyžadována žádná autorizace dotazu na přístup
36 Služba je dočasně nedostupná z důvodu plánovaných technických prací
43 Počet uživatelských dotazů za aktuální měsíc se nepodařilo načíst
54 Nesprávné datum nebo čas v počítači nebo systému uživatele
55 Neplatná hodnota řetězce MAC v záhlaví s přihlašovacími údaji dotazu
57 Neplatná hodnota klíče v záhlaví s přihlašovacími údaji dotazu
58 Bylo dosaženo maximálního počtu souběžných dotazů pro tento členský stát
59 Aplikace v členském státě neodpovídá nebo není dostupná
62 Dávka se stále zpracovává, zkuste to znovu později
63 Bylo dosaženo maximálního počtu dávkových požadavků, odešlete svůj požadavek znovu později
101 Číslo IP připojení neodpovídá číslu IP přiřazenému klíči API
102 Klíč API je blokován
103 Neplatný klíč API
104 Bylo dosaženo maximálního počtu dotazů dostupných pro vybraný plán
105 Účet zablokován nebo smazán
106 Neplatný typ účtu
107 Předplacený účet nebyl zaplacen
108 Neplatné ID klíče API
201 Nepodařilo se připojit ke službě VIES API
202 Odpověď služby VIES API má neplatný formát
203 Neplatný typ čísla
204 NIP je neplatný
205 DIČ EU je neplatné
206 Funkce vygenerovala výjimku
207 Datum má neplatný formát
208 Neplatný vstupní parametr
209 Překročen limit velikosti dávky [2–99]