REST API dokumentation

Introduktion

API'en, der leveres af os, bruger standard HTTP-protokollen. Alle API-funktioner bruger HTTP GET-metoden. Hvert funktionskald kræver forespørgselsautorisation. Data til forespørgselsautorisation sendes i HTTP-headeren.

Produktionsservice

Registrering af en enhed, der ønsker at bruge viesapi.eu-systemets funktionalitet, er påkrævet. For at gøre dette skal du gå til Registrering side og udfyld den relevante formular. Forudsætningen for at bruge viesapi.eu-systemet er accept af Servicevilkår. Korrekt udfyldelse af formularen og klik på Tilmeld knappen vil oprette en konto i viesapi.eu-systemet og dens automatiske aktivering.

Når du logger på første gang, genereres der automatisk en identifikator sammen med den tilhørende nøgle. Identifikationen er offentlig og kræver ikke beskyttelse, mens nøglen er privat og ikke bør stilles til rådighed for tredjeparter.

Produktionsserviceadresse: https://viesapi.eu/api

Test service

Den fulde funktionalitet af alle delte biblioteker kan kontrolleres ved hjælp af den delte Test VIES API. Ved at bruge test-API'en er det muligt at kontrollere alle de funktioner, der tilbydes i betalte planer uden behov for at oprette en konto.

Testserviceadresse: https://viesapi.eu/api-test

API interface definition

En detaljeret definition af API'en er tilgængelig i et OpenAPI-kompatibelt format og kan downloades som en YAML-fil her.

API er også tilgængelig som en klientgrænseflade Swagger UI.

Udførelse af forespørgslen

Et eksempel på at lave en forespørgsel til teststedet:

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

Hvor:

  • api_key_id – API-nøgleidentifikator (på produktionsmiljøet, værdien af identifikatoren genereret under registreringen, på testmiljøet, værdien af test_id)
  • unix_timestamp – den aktuelle tid i form af et antal sekunder fra den såkaldte unix epoke,
  • random_str – tilfældig streng, forskellig for hver forespørgsel (min. 8 tegn, maks. 16 tegn),
  • b64_calculated_mac_value – beregnet HMAC (ved hjælp af en API key, værdi test_key på testmiljøet),
  • client_version – klientversion (i vores biblioteker er det versionen af vores API-bibliotek, f.eks. 1.2.3),
  • platform_name – navnet på API-klientplatformen (i vores biblioteker er det navnet på bibliotekssproget, f.eks. JAVA, PHP, .NET, Python),
  • platform_version – API-klientplatformversion (i vores biblioteker er det biblioteksmiljøversionen, f.eks. 17 til JAVA eller 7.4 til PHP),
  • mime_type – MIME-typenavn, som svaret skal returneres i, to typer understøttes: text/xml og application/json, hvis anmodningen ikke indeholder Accept header, returneres XML som standard.

Godkendelsesanmodning

Autorisationsdata skal udarbejdes iht HTTP-godkendelse: MAC-adgangsgodkendelse og dette er anbefalet godkendelsesmetode. Det er også muligt at bruge HTTP-godkendelse: Grundlæggende godkendelse metode, men af sikkerhedsmæssige årsager skal du kun bruge den, når den første metode af en eller anden grund ikke er mulig.

Hver forespørgsel til vores hjemmeside skal autentificeres ved hjælp af en af de to tilgængelige metoder.

Metode 1 – HMAC (anbefalet)

Specifikation af den anvendte godkendelsesmetode: HTTP-godkendelse: MAC-adgangsgodkendelse. Autorisation består i at beregne HMAC SHA256 fra en korrekt forberedt streng og sende resultatet i HTTP-headeren.

Eksempel

Inputstrengen til HMAC-funktionen er:
ts + '\n' + nonce + '\n' + method + '\n' + path + '\n' + host + '\n' + port + '\n\n'

Hvor:

  • ts – den aktuelle tid i form af et antal sekunder fra den såkaldte unix epoke, skal du altid angive den aktuelle forespørgsels eksekveringstid (servertolerance +/- 10 min i forhold til det aktuelle tidspunkt),
  • nonce – tilfældig streng, forskellig for hver forespørgsel (min. 8 tegn, maks. 16 tegn),
  • method – HTTP-metodenavn (altid GET),
  • path – URL-sti til den forespørgsel, der skal udføres,
  • host – VIES API-servernavn (altid viesapi.eu),
  • port – VIES API-serverportnummer (altid 443),
  • ’\n’ – nylinjetegn (ASCII-kode 10, 0x0A).

For forespørgslen om momsnummeret PL7171642051 sendt til testtjenesten 2019-11-25 00:00:00 UTC vil inputstrengen til HMAC-funktionen se sådan ud:
str = "1574640000\ndt831hs59s\nGET\n/api-test/get/vies/euvat/PL7171642051\nviesapi.eu\n443\n\n"

Input-strengfilen til dette eksempel kan downloades her.

Ud fra den forberedte streng beregner vi HMAC SHA256, som HMAC-adgangskoden giver vi API key, dvs. i tilfælde af test-API'en, værdien af test_key:

HMAC_SHA256(str, "test_key") = 7776a12b958233ce60dd0f16b8d141e80472a1ee3b1e1fb136d7abe34cb59306

HMAC SHA256-funktionen returnerer 32 binære bytes (vist ovenfor som en hex streng for læsbarhed). Download fil med binær værdi her.

Den binære værdi af den beregnede HMAC skal kodes med Base64-algoritmen, vi får:

d3ahK5WCM85g3Q8WuNFB6ARyoe47Hh+xNter40y1kwY=

Denne værdi skal sendes som MAC-værdi i headeren med data til godkendelse. Endelig:

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

På Linux-maskine kan den nødvendige MAC-værdi beregnes i ét trin ved hjælp af denne 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

Metode 2 – Grundlæggende godkendelse

Specifikation af denne anvendte godkendelsesmetode: HTTP-godkendelse: Grundlæggende godkendelse.

Eksempel 1

Inputstrengen til Base64-funktionen er:

str = key_id + ':' + key

Hvor:

  • key_id – API-nøgle-id (i tilfælde af et testmiljø, test_id snor),
  • key – API-nøgle (i tilfælde af et testmiljø, streng test_key).

For testmiljøet vil inputstrengen for Base64-funktionen være:

str = "test_id:test_key"

Efter at have anvendt Base64-funktionen får vi:

Base64(str) = dGVzdF9pZDp0ZXN0X2tleQ==

Denne værdi skal sendes som en basisværdi i headeren med data til godkendelse. Ultimativt:

Authorization: Basic dGVzdF9pZDp0ZXN0X2tleQ==

Eksempel 2

Følgende eksempel viser en forespørgsel, der kan startes i et testmiljø fra en webbrowser. Bare kopier og indsæt det i browserens adresselinje:

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

Hvor:

  • test_id – at autentificere i en produktion miljø, skal parameteren indeholde en gyldig nøgle-id, der bruges til godkendelse,
  • test_key – at autentificere i en produktion miljø, skal parameteren indeholde en gyldig værdi af den nøgle, der bruges til godkendelse.

Nøgleidentifikationen og nøglen genereres af brugeren efter at have logget ind på sin konto på viesapi.eu portal (API keys fanen). See den dokumentation side for mere information om ID og nøglegenerering.

Respons

Hvis anmodningen håndteres korrekt, genereres følgende svar:

Detaljeret beskrivelse af returnerede attributter:

  • uid – unik forespørgsels-id genereret af viesapi.eu,
  • countryCode – landekode, hvor den virksomhed, der er tilknyttet det EU-momsnummer, der er angivet i forespørgslen, er registreret,
  • vatNumber – EU-momsnummer for den verificerede virksomhed, der er angivet i forespørgslen,
  • valid – svar fra VIES-tjenesten, der informerer om den aktuelle EU-momsstatus for den kontrollerede enhed:
    • true – det EU-momsnummer, der er angivet i forespørgslen, er gyldigt,
    • false – EU-momsnummeret, der er angivet i forespørgslen, er ikke gyldigt,
  • traderName – virksomhedens firmanavn,
  • traderCompanyType – returnerede altid en streng af '-'-tegn,
  • traderAddress – virksomhedsadresse, hvor virksomheden er registreret,
  • id – unik forespørgselsidentifikation genereret af VIES-systemet
  • date – forespørgsels udførelsesdato
  • source – datakilde, altid: http://ec.europa.eu

Fejlsvar

I tilfælde af fejl i forbindelse med håndteringen af anmodningen, returneres følgende fejlmeddelelse:

Fejl

Detaljeret beskrivelse af returnerede attributter:

  • code – unik fejlkode til automatisk fejlhåndtering,
  • description – beskrivelse af menneskelig aflytning,
  • details – meller detaljeret fejlbeskrivelse (valgfrit),