REST API-dokumentation

VIES API REST 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
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

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),
  • mime_type – MIME-typnamn där svaret ska returneras, två typer stöds: text/xml och application/json, om begäran inte innehåller Accept header, returneras XML som standard.

Begäran om autentisering

Behörighetsuppgifter ska upprättas enl HTTP-autentisering: MAC Access-autentisering och detta rekommenderas autentiseringsmetod. Det är också möjligt att använda HTTP-autentisering: Grundläggande autentisering metod, men av säkerhetsskäl, använd den endast när det inte är möjligt att använda den första metoden av någon anledning.

Varje fråga till vår webbplats måste autentiseras med en av de två tillgängliga metoderna.

Metod 1 – HMAC (rekommenderas)

Specifikation av den auktoriseringsmetod som används: HTTP-autentisering: MAC Access-autentisering. 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=

Detta värde ska skickas som MAC-värde i rubriken med data för auktorisering. Till sist:

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

På Linux-maskin kan det erforderliga MAC-värdet beräknas i ett steg med detta kommando:

$ 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

Metod 2 – Grundläggande autentisering

Specifikation av denna auktoriseringsmetod som används: HTTP-autentisering: Grundläggande autentisering.

Exempel 1

Inmatningssträngen till Base64-funktionen är:

str = key_id + ':' + key

Var:

  • key_id – API-nyckelidentifierare (i fallet med en testmiljö, test_id sträng),
  • key – API-nyckel (i fallet med en testmiljö, sträng test_key).

För testmiljön kommer indatasträngen för Base64-funktionen att vara:

str = "test_id:test_key"

Efter att ha tillämpat Base64-funktionen får vi:

Base64(str) = dGVzdF9pZDp0ZXN0X2tleQ==

Detta värde ska skickas som ett basvärde i rubriken med data för auktorisering. I sista hand:

Authorization: Basic dGVzdF9pZDp0ZXN0X2tleQ==

Exempel 2

Följande exempel visar en fråga som kan anropas i en testmiljö från en webbläsare. Bara kopiera och klistra in den i webbläsarens adressfält:

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

Var:

  • test_id – att autentisera i en produktion miljö, bör parametern innehålla en giltig nyckelidentifierare som används för auktorisering,
  • test_key – att autentisera i en produktion miljö, bör parametern innehålla ett giltigt värde för nyckeln som används för auktorisering.

Nyckelidentifieraren och nyckeln genereras av användaren efter att ha loggat in på sitt konto på viesapi.eu portal (API keys flik). See den dokumentation sida för mer information om ID och nyckelgenerering.

Svar

Om begäran hanteras korrekt genereras följande svar:

Detaljerad beskrivning av returnerade attribut:

  • uid – unik frågeidentifierare genererad av viesapi.eu,
  • countryCode – landskod där det företag som är kopplat till det EU-momsnummer som anges i förfrågan är registrerat,
  • vatNumber – EU-momsnummer för det verifierade företaget som anges i förfrågan,
  • valid – svar från VIES-tjänsten, som informerar om den kontrollerade enhetens aktuella EU-momsstatus:
    • true – EU-momsnummer som anges i förfrågan är giltigt,
    • false – EU-momsnumret som anges i förfrågan är inte giltigt,
  • traderName – företagets handelsnamn,
  • traderCompanyType – returnerade alltid en sträng med "-"-tecken,
  • traderAddress – företagsadress där företaget är registrerat,
  • id – unik frågeidentifierare genererad av VIES-systemet
  • date – datum för utförande av frågan
  • source – datakälla, alltid: http://ec.europa.eu

Felsvar

I händelse av något fel relaterat till hanteringen av begäran returneras följande felmeddelande:

Fel

Detaljerad beskrivning av returnerade attribut:

  • code – unik felkod för automatisk felhantering,
  • description – mänskligt avlyssningsbar felbeskrivning,
  • details – meller detaljerad felbeskrivning (valfritt),

Felkoder

Tabellen nedan listar alla möjliga fel som returneras av REST API:er och programmeringsbibliotek:

Felkod Felmeddelande
8 Ogiltigt format för begäran
10 Ogiltig API-sökväg
11 Internt servicefel
22 EU-momsnummer är ogiltigt
23 Det gick inte att hämta data från VIES-systemet
26 Den här funktionen är inte tillgänglig på den för närvarande valda planen
27 Denna funktion stöder inte detta sökläge
33 Det är inte möjligt att fråga efter givna data i testläget
35 Ingen behörighet för åtkomstfråga krävs
36 Tjänsten är tillfälligt otillgänglig på grund av planerat tekniskt arbete
43 Antalet användarfrågor för den aktuella månaden kunde inte hämtas
54 Felaktigt datum eller tid på användarens dator eller system
55 Ogiltigt MAC-strängvärde i rubriken med frågeuppgifter
57 Ogiltigt nyckelvärde i rubriken med frågeuppgifter
58 Det maximala antalet samtidiga förfrågningar för denna medlemsstat har uppnåtts
59 Ansökan i medlemsstaten svarar inte eller är inte tillgänglig
101 Anslutningens IP-nummer matchar inte IP-numret som tilldelats API-nyckeln
102 API-nyckeln är blockerad
103 Ogiltig API-nyckel
104 Det maximala antalet tillgängliga frågor för den valda planen har uppnåtts
105 Kontot blockerat eller raderat
106 Ogiltig kontotyp
107 Det förbetalda kontot har inte betalats
108 Ogiltigt API-nyckel-ID
201 Det gick inte att ansluta till VIES API-tjänsten
202 VIES API-tjänstsvaret har ogiltigt format
203 Ogiltig nummertyp
204 NIP är ogiltigt
205 EU VAT ID är ogiltigt
206 Funktionen genererade ett undantag
207 Datum har ett ogiltigt format
208 Ogiltig indataparameter