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í anAPI key
, hodnotatest_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
aapplication/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ždyviesapi.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ězectest_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 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 VIESdate
– datum provedení dotazusource
– 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:
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á |
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 |