REST API-dokumentation

Introduktion

API:et som tillhandahålls av oss använder standard HTTP-protokollet. Alla API-funktioner använder HTTP GET-metoden. Varje funktionsanrop kräver frågeauktorisering. Data för frågeauktorisering skickas i HTTP-huvudet.

Produktionstjänst

Registrering av en enhet som vill använda funktionaliteten i systemet viesapi.eu krävs. För att göra detta, gå till Registrering sida och fyll i lämpligt formulär. Förutsättningen för att använda viesapi.eu-systemet är godkännandet av Användarvillkor. Fyll i formuläret korrekt och klicka på Registrera knappen kommer att skapa ett konto i viesapi.eu-systemet och dess automatiska aktivering.

När du loggar in för första gången genereras en identifierare automatiskt tillsammans med motsvarande nyckel. Identifieraren är offentlig och kräver inget skydd, medan nyckeln är privat och inte bör göras tillgänglig för tredje part.

Produktionstjänstens adress: https://viesapi.eu/api

Testtjänst

Den fulla funktionaliteten för alla delade bibliotek kan kontrolleras med hjälp av delade Testa VIES API. Genom att använda test-API:et är det möjligt att kontrollera alla funktioner som erbjuds i betalplaner utan att behöva skapa ett konto.

Testtjänstadress: https://viesapi.eu/api-test

API-gränssnittsdefinition

En detaljerad definition av API:t finns i ett OpenAPI-kompatibelt format och kan laddas ner som en YAML-fil här.

API är också tillgängligt som ett klientgränssnitt Swagger UI.

Utförande av frågan

Ett exempel på att göra en fråga till testplatsen:

GET /api-test/get/vies/euvat/PL7171642051 HTTP/1.1
Värd: viesapi.eu:443
Auktorisering: MAC id="api_key_id", ts="unix_timestamp", nonce="random_str", mac="b64_calculated_mac_value"
User-Agent: VIESAPIClient/client_version plattformsnamn/plattformsversion

Var:

  • api_key_id – API-nyckelidentifierare (på produktionsmiljön, värdet på identifieraren som genererades under registreringen, på testmiljön, värdet av test_id),
  • unix_timestamp – den aktuella tiden i form av ett antal sekunder från den sk unix epok,
  • random_str – slumpmässig sträng, olika för varje fråga (min. 8 tecken, max. 16 tecken),
  • b64_calculated_mac_value – beräknad HMAC (med an API key, värde test_key på testmiljön),
  • client_version – klientversion (i våra bibliotek är det versionen av vårt API-bibliotek, t.ex. 1.2.3),
  • platform_name – namnet på API-klientplattformen (i våra bibliotek är det namnet på biblioteksspråket, t.ex. JAVA, PHP, .NET, Python),
  • platform_version – API-klientplattformsversion (i våra bibliotek är det biblioteksmiljöversionen, t.ex. 17 för JAVA eller 7.4 för PHP).

Alla svar som returneras av webbplatsen är i XML-format.

Begäran om autentisering

Specifikation av den auktoriseringsmetod som används: HTTP-autentisering: MAC Access-autentisering. Varje fråga till vår webbplats måste autentiseras med denna metod. Auktoriseringen består i att beräkna HMAC SHA256 från en korrekt förberedd sträng och skicka resultatet i HTTP-huvudet.

Exempel

Inmatningssträngen till HMAC-funktionen är:
ts + '\n' + nonce + '\n' + method + '\n' + path + '\n' + host + '\n' + port + '\n\n'

Var:

  • ts – den aktuella tiden i form av ett antal sekunder från den sk unix epok, bör du alltid ange den aktuella frågekörningstiden (servertolerans +/- 10 min i förhållande till aktuell tid),
  • nonce – slumpmässig sträng, olika för varje fråga (min. 8 tecken, max. 16 tecken),
  • method – HTTP-metodnamn (alltid GET),
  • path – URL-sökväg för frågan som ska köras,
  • host – VIES API-servernamn (alltid viesapi.eu),
  • port – VIES API-serverportnummer (alltid 443),
  • ’\n’ – nyradstecken (ASCII-kod 10, 0x0A).

För frågan om momsnumret PL7171642051 som skickades till testtjänsten 2019-11-25 00:00:00 UTC kommer inmatningssträngen till HMAC-funktionen att se ut så här:
str = "1574640000\ndt831hs59s\nGET\n/api-test/get/vies/euvat/PL7171642051\nviesapi.eu\n443\n\n"

Indatasträngsfilen för detta exempel kan laddas ner här.

Från den förberedda strängen beräknar vi HMAC SHA256, som HMAC-lösenordet ger vi API key, dvs i fallet med test-API:t, värdet på test_key:

HMAC_SHA256(str, "test_key") = 7776a12b958233ce60dd0f16b8d141e80472a1ee3b1e1fb136d7abe34cb59306

Funktionen HMAC SHA256 returnerar 32 binära byte (visas ovan som en hex sträng för läsbarhet). Ladda ner fil med binärt värde här.

Det binära värdet för den beräknade HMAC bör kodas med Base64-algoritmen, vi får:

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