VIES API REST 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 enAPI key
, værditest_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
ogapplication/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 (altidviesapi.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ø, strengtest_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-systemetdate
– forespørgsels udførelsesdatosource
– datakilde, altid: http://ec.europa.eu
Fejlsvar
I tilfælde af fejl i forbindelse med håndteringen af anmodningen, returneres følgende fejlmeddelelse:
Detaljeret beskrivelse af returnerede attributter:
code
– unik fejlkode til automatisk fejlhåndtering,description
– beskrivelse af menneskelig aflytning,details
– meller detaljeret fejlbeskrivelse (valgfrit),
Fejlkoder
Tabellen nedenfor viser alle mulige fejl returneret af REST API'er og programmeringsbiblioteker:
Fejlkode | Fejlmeddelelse |
8 | Ugyldigt anmodningsformat |
10 | Ugyldig API-sti |
11 | Intern servicefejl |
22 | EU-momsnummeret er ugyldigt |
23 | Kunne ikke hente data fra VIES-systemet |
26 | Denne funktion er ikke tilgængelig på det aktuelt valgte abonnement |
27 | Denne funktion understøtter ikke denne søgetilstand |
33 | Det er ikke muligt at forespørge på de givne data i testtilstand |
35 | Der kræves ingen adgangsforespørgselsautorisation |
36 | Tjenesten er midlertidigt utilgængelig på grund af planlagt teknisk arbejde |
43 | Antallet af brugerforespørgsler for den aktuelle måned kunne ikke hentes |
54 | Forkert dato eller klokkeslæt på brugerens computer eller system |
55 | Ugyldig MAC-strengværdi i header med forespørgselslegitimationsoplysninger |
57 | Ugyldig nøgleværdi i header med forespørgselslegitimationsoplysninger |
58 | Det maksimale antal samtidige forespørgsler for denne medlemsstat er nået |
59 | Ansøgningen i medlemsstaten besvarer ikke eller er ikke tilgængelig |
101 | Forbindelsens IP-nummer svarer ikke til det IP-nummer, der er tildelt API-nøglen |
102 | API-nøgle er blokeret |
103 | Ugyldig API-nøgle |
104 | Det maksimale antal tilgængelige forespørgsler for den valgte plan er nået |
105 | Konto blokeret eller slettet |
106 | Ugyldig kontotype |
107 | Den forudbetalte konto er ikke blevet betalt |
108 | Ugyldigt API-nøgle-id |
201 | Kunne ikke oprette forbindelse til VIES API-tjenesten |
202 | VIES API-tjenestesvaret har et ugyldigt format |
203 | Ugyldig nummertype |
204 | NIP er ugyldig |
205 | EU-moms-id er ugyldigt |
206 | Funktionen genererede en undtagelse |
207 | Datoen har et ugyldigt format |
208 | Ugyldig inputparameter |