REST API-documentatie

VIES API REST-documentatie

Invoering

De door ons geleverde API maakt gebruik van het standaard HTTP-protocol. Alle API-functies gebruiken de HTTP GET-methode. Elke functieaanroep vereist query-autorisatie. Gegevens voor query-autorisatie worden verzonden in de HTTP-header.

Productie dienst

Registratie van een entiteit die de functionaliteit van het systeem van viesapi.eu wil gebruiken, is vereist. Ga hiervoor naar de Registratie pagina en vul het juiste formulier in. Voorwaarde voor het gebruik van het systeem viesapi.eu is de acceptatie van de Servicevoorwaarden. Correct invullen van het formulier en klikken op de Register knop maakt een account aan in het systeem van viesapi.eu en wordt automatisch geactiveerd.

Bij de eerste keer inloggen wordt automatisch een identifier gegenereerd samen met de bijbehorende sleutel. De identifier is openbaar en behoeft geen bescherming, terwijl de sleutel privé is en niet aan derden ter beschikking mag worden gesteld.

Adres productieservice: https://viesapi.eu/api

Test dienst

De volledige functionaliteit van alle gedeelde bibliotheken kan worden gecontroleerd met behulp van de gedeelde VIES-API testen. Door de test-API te gebruiken, is het mogelijk om alle functies te controleren die worden aangeboden in betaalde abonnementen zonder dat je een account hoeft aan te maken.

Adres testservice: https://viesapi.eu/api-test

API-interfacedefinitie

Een gedetailleerde definitie van de API is beschikbaar in een OpenAPI-compatibel formaat en kan worden gedownload als een YAML-bestand hier.

API is ook beschikbaar als clientinterface Swagger-gebruikersinterface.

Uitvoering van de vraag

Een voorbeeld van het maken van een query naar de testsite:

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

Waar:

  • api_key_id – API key identifier (op de productieomgeving, de waarde van de identifier gegenereerd tijdens registratie, op de testomgeving, de waarde van test_id),
  • unix_timestamp – de actuele tijd in de vorm van een aantal seconden uit de zgn unix-tijdperk,
  • random_str – willekeurige string, verschillend voor elke zoekopdracht (min. 8 karakters, max. 16 karakters),
  • b64_calculated_mac_value – berekende HMAC (met behulp van een API key, waarde test_key op de testomgeving),
  • client_version – clientversie (in onze bibliotheken is dit de versie van onze API-bibliotheek, bijv. 1.2.3),
  • platform_name – de naam van het API-clientplatform (in onze bibliotheken is dit de naam van de bibliotheektaal, bijv. JAVA, PHP, .NET, Python),
  • platform_version – API-clientplatformversie (in onze bibliotheken is dit de versie van de bibliotheekomgeving, bijvoorbeeld 17 voor JAVA of 7.4 voor PHP),
  • mime_type – MIME-typenaam waarin het antwoord moet worden geretourneerd, er worden twee typen ondersteund: text/xml en application/jsonAls de aanvraag geen Accept-header bevat, wordt XML standaard geretourneerd.

Verificatieverzoek

Autorisatiegegevens moeten worden opgesteld in overeenstemming met HTTP-authenticatie: MAC-toegangsauthenticatie en dit is de aanbevolen authenticatiemethode. Het is ook mogelijk om gebruik te maken van de HTTP-authenticatie: basisauthenticatie methode, maar gebruik deze om veiligheidsredenen alleen als de eerste methode om de een of andere reden niet mogelijk is.

Elke zoekopdracht op onze website moet worden geverifieerd met behulp van een van de twee beschikbare methoden.

Methode 1 – HMAC (aanbevolen)

Specificatie van de gebruikte autorisatiemethode: HTTP-authenticatie: MAC-toegangsauthenticatie. Autorisatie bestaat uit het berekenen van de HMAC SHA256 uit een correct voorbereide string en het verzenden van het resultaat in de HTTP-header.

Voorbeeld

De invoertekenreeks voor de HMAC-functie is:
ts + '\n' + nonce + '\n' + method + '\n' + path + '\n' + host + '\n' + port + '\n\n'

Waar:

  • ts – de actuele tijd in de vorm van een aantal seconden uit de zgn unix-tijdperk, moet u altijd de huidige uitvoeringstijd van de query opgeven (servertolerantie +/- 10 min ten opzichte van de huidige tijd),
  • nonce – willekeurige string, verschillend voor elke zoekopdracht (min. 8 karakters, max. 16 karakters),
  • method - HTTP-methodenaam (altijd GET),
  • path – URL-pad van de uit te voeren query,
  • host – VIES API servernaam (altijd viesapi.eu),
  • port – VIES API server poortnummer (altijd 443),
  • ’\n’ – teken voor een nieuwe regel (ASCII-code 10, 0x0A).

Voor de query voor het btw-nummer PL7171642051 verzonden naar de testservice op 2019-11-25 00:00:00 UTC ziet de invoerreeks voor de HMAC-functie er als volgt uit:
str = "1574640000\ndt831hs59s\nGET\n/api-test/get/vies/euvat/PL7171642051\nviesapi.eu\n443\n\n"

Het invoertekenreeksbestand voor dit voorbeeld kan worden gedownload hier.

Uit de voorbereide string berekenen we HMAC SHA256, als het HMAC-wachtwoord dat we geven API key, dwz in het geval van de test-API, de waarde van test_key:

HMAC_SHA256(str, "test_key") = 7776a12b958233ce60dd0f16b8d141e80472a1ee3b1e1fb136d7abe34cb59306

De HMAC SHA256-functie retourneert 32 binaire bytes (hierboven weergegeven als een hex tekenreeks voor leesbaarheid). Download bestand met binaire waarde hier.

De binaire waarde van de berekende HMAC moet worden gecodeerd met het Base64-algoritme, we krijgen:

d3ahK5WCM85g3Q8WuNFB6ARyoe47Hh+xNter40y1kwY=

Deze waarde moet als MAC-waarde in de header met gegevens voor autorisatie worden verzonden. Eindelijk:

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

Op een Linux-machine kan de vereiste MAC-waarde in één stap worden berekend met behulp van deze opdracht:

$ 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

Methode 2 - Basisauthenticatie

Specificatie van deze gebruikte autorisatiemethode: HTTP-authenticatie: basisauthenticatie.

voorbeeld 1

De invoertekenreeks voor de Base64-functie is:

str = key_id + ':' + key

Waar:

  • key_id – API key identifier (in het geval van een testomgeving, test_id snaar),
  • key – API key (in het geval van een testomgeving, string test_key).

Voor de testomgeving is de invoertekenreeks voor de Base64-functie:

str = "test_id:test_key"

Na het toepassen van de Base64-functie krijgen we:

Base64(str) = dGVzdF9pZDp0ZXN0X2tleQ==

Deze waarde moet als basiswaarde in de header met gegevens voor autorisatie worden verzonden. uiteindelijk:

Authorization: Basic dGVzdF9pZDp0ZXN0X2tleQ==

Voorbeeld 2

Het volgende voorbeeld toont een query die kan worden aangeroepen in een testomgeving vanuit een webbrowser. Kopieer en plak het in de adresbalk van de browser:

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

Waar:

  • test_id – om te authenticeren in een productie omgeving, parameter moet een geldige sleutel-ID bevatten die wordt gebruikt voor autorisatie,
  • test_key – om te authenticeren in een productie omgeving, moet de parameter een geldige waarde bevatten van de sleutel die wordt gebruikt voor autorisatie.

De sleutel-ID en de sleutel worden gegenereerd door de gebruiker na het inloggen op zijn account op de viesapi.eu portaal (API keys tabblad). Se de documentatie pagina voor meer informatie over het genereren van ID's en sleutels.

Antwoord

Als het verzoek correct wordt afgehandeld, wordt het volgende antwoord gegenereerd:

Gedetailleerde beschrijving van geretourneerde attributen:

  • uid – unieke zoekopdracht-ID gegenereerd door viesapi.eu,
  • countryCode – landcode waarin het bedrijf is geregistreerd dat is aangesloten bij het EU-btw-nummer dat in de aanvraag is opgegeven,
  • vatNumber – EU-btw-nummer van het geverifieerde bedrijf dat in de aanvraag is opgegeven,
  • valid – reactie van de VIES-dienst, met informatie over de huidige EU-btw-status van de gecontroleerde entiteit:
    • true – het in de aanvraag opgegeven EU-btw-nummer geldig is,
    • false – het in de aanvraag opgegeven EU-btw-nummer is niet geldig,
  • traderName – handelsnaam van het bedrijf,
  • traderCompanyType – retourneerde altijd een reeks '-'-tekens,
  • traderAddress – bedrijfsadres waar het bedrijf is geregistreerd,
  • id – unieke identificatiecode gegenereerd door het VIES-systeem
  • date – uitvoeringsdatum query
  • source – gegevensbron, altijd: http://ec.europa.eu

Fout antwoord

In het geval van een fout met betrekking tot de afhandeling van het verzoek, wordt het volgende foutbericht geretourneerd:

Fout

Gedetailleerde beschrijving van geretourneerde attributen:

  • code – unieke foutcode voor automatische foutafhandeling,
  • description – door mensen te onderscheppen foutbeschrijving,
  • details - Mof gedetailleerde foutbeschrijving (optioneel),

Foutcodes

In de onderstaande tabel staan alle mogelijke fouten die door REST API's en programmeerbibliotheken worden geretourneerd:

Foutcode Foutmelding
8 Ongeldig verzoekformaat
10 Ongeldig API-pad
11 Interne servicefout
22 EU BTW-nummer is ongeldig
23 Het is niet gelukt om gegevens uit het VIES-systeem te halen
26 Deze functie is niet beschikbaar op het momenteel geselecteerde abonnement
27 Deze functie ondersteunt deze zoekmodus niet
33 Het is niet mogelijk om de opgegeven gegevens op te vragen in de testmodus
35 Geen toegangsqueryautorisatie vereist
36 De service is tijdelijk niet beschikbaar vanwege geplande technische werkzaamheden
43 Het aantal gebruikersquery's voor de huidige maand kon niet worden opgehaald
54 Onjuiste datum of tijd op de computer of het systeem van de gebruiker
55 Ongeldige MAC-tekenreekswaarde in header met queryreferenties
57 Ongeldige sleutelwaarde in header met queryreferenties
58 Het maximale aantal gelijktijdige zoekopdrachten voor deze lidstaat is bereikt
59 De aanvraag bij de lidstaat reageert niet of is niet beschikbaar
101 Het IP-nummer van de verbinding komt niet overeen met het IP-nummer dat is toegewezen aan de API-sleutel
102 API-sleutel is geblokkeerd
103 Ongeldige API-sleutel
104 Het maximale aantal beschikbare query's voor het geselecteerde plan is bereikt
105 Account geblokkeerd of verwijderd
106 Ongeldig accounttype
107 Het prepaid-account is niet betaald
108 Ongeldige API-sleutel-ID
201 Er kan geen verbinding worden gemaakt met de VIES API-service
202 VIES API-servicerespons heeft ongeldige indeling
203 Ongeldig nummertype
204 NIP is ongeldig
205 EU BTW-ID is ongeldig
206 Functie genereerde een uitzondering
207 Datum heeft een ongeldige notatie
208 Ongeldige invoerparameter