REST-API-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
Autorisierung: MAC id="api_key_id", ts="unix_timestamp", nonce="random_str", mac="b64_calculated_mac_value"
User-Agent: VIESAPIClient/Client_Version Plattformname/Plattformversion

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 – Version der API-Client-Plattform (in unseren Bibliotheken ist dies die Version der Bibliotheksumgebung, z. B. 17 für JAVA oder 7.4 für PHP).

Alle von der Website zurückgegebenen Antworten sind im XML-Format.

Authentifizierungsanfrage

Angabe des verwendeten Autorisierungsverfahrens: HTTP-Authentifizierung: MAC-Zugriffsauthentifizierung. Jede Anfrage an unsere Website muss mit diesem Verfahren authentifiziert werden. 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