Ú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í 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).
Všechny odpovědi vrácené webem jsou ve formátu XML.
Žádost o ověření
Specifikace použitého způsobu autorizace: HTTP Authentication: MAC Access Authentication. Každý dotaz na naše webové stránky musí být ověřen pomocí této metody. 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=
This value should be sent as MAC value in the header with data for authorization. Finally:
Authorization: MAC id="test_id", ts="1574640000", nonce="dt831hs59s", mac="d3ahK5WCM85g3Q8WuNFB6ARyoe47Hh+xNter40y1kwY="
On Linux machine required MAC value can be calculated in one step using this command:
$ 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