VIES API REST-Dokumentation

Einführung

Die von uns bereitgestellte API verwendet das Standard-HTTP-Protokoll. Alle API-Funktionen verwenden die HTTP-GET-Methode. Jeder Funktionsaufruf erfordert eine Abfrageberechtigung. Daten für die Abfrageautorisierung werden im HTTP-Header gesendet.

Produktionsservice

Die Registrierung einer juristischen Person, die die Funktionalität des viesapi.eu-Systems nutzen möchte, ist erforderlich. Gehen Sie dazu auf die Anmeldung Seite und füllen Sie das entsprechende Formular aus. Voraussetzung für die Nutzung des viesapi.eu-Systems ist die Akzeptanz der Nutzungsbedingungen. Richtiges Ausfüllen des Formulars und Anklicken der Registrieren Schaltfläche wird ein Konto im viesapi.eu-System erstellt und automatisch aktiviert.

Beim erstmaligen Einloggen wird automatisch eine Kennung mit dem dazugehörigen Schlüssel generiert. Der Identifikator ist öffentlich und muss nicht geschützt werden, während der Schlüssel privat ist und nicht an Dritte weitergegeben werden sollte.

Adresse Produktionsservice: https://viesapi.eu/api

Testservice

Die volle Funktionalität aller Shared Libraries kann mit der shared Testen Sie die VIES-API. Durch die Verwendung der Test-API ist es möglich, alle Funktionen zu überprüfen, die in kostenpflichtigen Plänen angeboten werden ohne dass ein Konto erstellt werden muss.

Prüfservice-Adresse: https://viesapi.eu/api-test

API-Schnittstellendefinition

Eine detaillierte Definition der API ist in einem OpenAPI-kompatiblen Format verfügbar und kann als YAML-Datei heruntergeladen werden hier.

API ist auch als Client-Schnittstelle verfügbar Swagger-UI.

Ausführung der Abfrage

Ein Beispiel für eine Abfrage an die 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

Wo:

api_key_id – API-Schlüsselkennung (in der Produktionsumgebung der Wert der bei der Registrierung generierten Kennung, in der Testumgebung der Wert von test_id),
unix_timestamp – die aktuelle Uhrzeit in Form einer Sekundenzahl aus der sog Unix-Epoche,
random_str – zufälliger String, für jede Abfrage anders (min. 8 Zeichen, max. 16 Zeichen),
b64_calculated_mac_value – berechneter HMAC (unter Verwendung einer API key, Wert test_key auf der Testumgebung),
client_version – Client-Version (in unseren Bibliotheken ist es die Version unserer API-Bibliothek, z. B. 1.2.3),
platform_name – der Name der API-Client-Plattform (in unseren Bibliotheken ist es der Name der Bibliothekssprache, z. B. JAVA, PHP, .NET, Python),
platform_version – API-Client-Plattformversion (in unseren Bibliotheken ist es die Version der Bibliotheksumgebung, z. B. 17 für JAVA oder 7.4 für PHP),
mime_type – MIME-Typname, in dem die Antwort zurückgegeben werden soll, zwei Typen werden unterstützt: text/xml und application/jsonWenn die Anfrage keinen Accept-Header enthält, wird standardmäßig XML zurückgegeben.

Authentifizierungsanfrage

Berechtigungsdaten müssen gem HTTP-Authentifizierung: MAC-Zugriffsauthentifizierung und dies ist die empfohlene Authentifizierungsmethode. Es ist auch möglich, die zu verwenden HTTP-Authentifizierung: Basisauthentifizierung Methode, verwenden Sie sie jedoch aus Sicherheitsgründen nur, wenn die Verwendung der ersten Methode aus irgendeinem Grund nicht möglich ist.

Jede Anfrage an unsere Website muss mit einer der beiden verfügbaren Methoden authentifiziert werden.

Methode 1 – HMAC (empfohlen)

Angabe des verwendeten Autorisierungsverfahrens: HTTP-Authentifizierung: MAC-Zugriffsauthentifizierung. Die Autorisierung besteht darin, den HMAC SHA256 aus einem ordnungsgemäß vorbereiteten String zu berechnen und das Ergebnis im HTTP-Header zu senden.

Beispiel

Die Eingabezeichenfolge für die HMAC-Funktion lautet:
ts + '\n' + nonce + '\n' + method + '\n' + path + '\n' + host + '\n' + port + '\n\n'

Wo:

ts – die aktuelle Uhrzeit in Form einer Sekundenzahl aus der sog Unix-Epoche, sollten Sie immer die aktuelle Abfrageausführungszeit angeben (Servertoleranz +/- 10 min bezogen auf die aktuelle Zeit),
nonce – zufälliger String, für jede Abfrage anders (min. 8 Zeichen, max. 16 Zeichen),
method – HTTP-Methodenname (immer GET),
path – URL-Pfad der auszuführenden Abfrage,
host – Name des VIES-API-Servers (immer viesapi.eu),
port – Portnummer des VIES-API-Servers (immer 443),
’\n’ – Zeilenumbruchzeichen (ASCII-Code 10, 0x0A).

Für die Abfrage der Umsatzsteuer-Identifikationsnummer PL7171642051, die am 25.11.2019 00:00:00 UTC an den Testdienst gesendet wurde, sieht die Eingabezeichenfolge für die HMAC-Funktion folgendermaßen aus:
str = "1574640000\ndt831hs59s\nGET\n/api-test/get/vies/euvat/PL7171642051\nviesapi.eu\n443\n\n"

Die Eingabezeichenfolgendatei für dieses Beispiel kann heruntergeladen werden hier.

Aus dem vorbereiteten String berechnen wir HMAC SHA256, als HMAC-Passwort geben wir das an API key, dh im Fall der Test-API, der Wert von test_key:

HMAC_SHA256(str, "test_key") = 7776a12b958233ce60dd0f16b8d141e80472a1ee3b1e1fb136d7abe34cb59306

Die HMAC SHA256-Funktion gibt 32 binäre Bytes zurück (oben als a hex Zeichenfolge für die Lesbarkeit). Datei mit Binärwert herunterladen hier.

Der Binärwert des berechneten HMAC sollte mit dem Base64-Algorithmus codiert werden, wir erhalten:

d3ahK5WCM85g3Q8WuNFB6ARyoe47Hh+xNter40y1kwY=

Dieser Wert sollte als MAC-Wert im Header mit Daten zur Autorisierung gesendet werden. Endlich:

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

Auf einem Linux-Rechner kann der erforderliche MAC-Wert mit diesem Befehl in einem Schritt berechnet werden:

$ 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 – Basisauthentifizierung

Spezifikation dieser verwendeten Autorisierungsmethode: HTTP-Authentifizierung: Basisauthentifizierung .

Beispiel 1

Die Eingabezeichenfolge für die Base64-Funktion lautet:

str = key_id + ':' + key

Wo:

key_id – API-Schlüsselkennung (im Falle einer Testumgebung, test_id Schnur),
key – API-Schlüssel (im Falle einer Testumgebung string test_key).

Für die Testumgebung lautet die Eingabezeichenfolge für die Base64-Funktion:

str = "test_id:test_key"

Nach Anwendung der Base64-Funktion erhalten wir:

Base64(str) = dGVzdF9pZDp0ZXN0X2tleQ==

Dieser Wert sollte als Basiswert im Header mit Daten zur Autorisierung gesendet werden. Letzten Endes:

Authorization: Basic dGVzdF9pZDp0ZXN0X2tleQ==

Beispiel 2

Das folgende Beispiel zeigt eine Abfrage, die in einer Testumgebung von einem Webbrowser aus aufgerufen werden kann. Einfach kopieren und in die Adressleiste des Browsers einfügen:

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

Wo:

test_id – sich in einer Produktion zu authentifizieren Umfeld, Parameter sollte eine gültige Schlüsselkennung enthalten, die für die Autorisierung verwendet wird,
test_key – sich in einer Produktion zu authentifizieren Umgebung muss der Parameter einen gültigen Wert des für die Autorisierung verwendeten Schlüssels enthalten.

Die Schlüsselkennung und der Schlüssel werden vom Benutzer nach dem Einloggen in sein Konto auf der generiert viesapi.eu Portal (API keys Tab). Säh die Dokumentation Seite für weitere Informationen zur ID- und Schlüsselgenerierung.

Antwort

Bei korrekter Bearbeitung der Anfrage wird folgende Antwort generiert:

Detaillierte Beschreibung der zurückgegebenen Attribute:

uid – eindeutige Abfrage-ID, generiert von viesapi.eu,
countryCode – Ländercode, in dem das Unternehmen registriert ist, das mit der in der Anfrage angegebenen EU-Umsatzsteuernummer verknüpft ist,
vatNumber – EU-Umsatzsteuernummer des in der Anfrage angegebenen verifizierten Unternehmens,
valid – Antwort des MIAS-Dienstes, die über den aktuellen EU-Mehrwertsteuerstatus des überprüften Unternehmens informiert:
- true – die in der Anfrage angegebene EU-Umsatzsteuernummer ist gültig,
- false – die in der Anfrage angegebene EU-Umsatzsteuer-Identifikationsnummer ist ungültig,
traderName – Handelsname des Unternehmens,
traderCompanyType – gab immer eine Zeichenfolge mit „-“-Zeichen zurück,
traderAddress – Firmenadresse, an der das Unternehmen eingetragen ist,
id – eindeutige Abfrage-ID, die vom VIES-System generiert wird
date – Ausführungsdatum abfragen
source – Datenquelle, immer: http://ec.europa.eu

Fehlerreaktion

Im Falle eines Fehlers im Zusammenhang mit der Bearbeitung der Anfrage wird die folgende Fehlermeldung zurückgegeben:

Fehler