Documentation API REST

Introduction

L'API que nous fournissons utilise le protocole HTTP standard. Toutes les fonctions de l'API utilisent la méthode HTTP GET. Chaque appel de fonction nécessite une autorisation de requête. Les données d'autorisation de requête sont envoyées dans l'en-tête HTTP.

Service de fabrication

L'enregistrement d'une entité qui souhaite utiliser les fonctionnalités du système viesapi.eu est requis. Pour ce faire, rendez-vous sur Inscription page et remplissez le formulaire approprié. La condition préalable à l'utilisation du système viesapi.eu est l'acceptation du Conditions d'utilisation. Remplissez correctement le formulaire et cliquez sur le S'inscrire créera un compte dans le système viesapi.eu et son activation automatique.

Lors de la première connexion, un identifiant est automatiquement généré avec la clé correspondante. L'identifiant est public et ne nécessite pas de protection, tandis que la clé est privée et ne doit pas être mise à la disposition de tiers.

Adresse du service de fabrication : https://viesapi.eu/api

Prestation d'essai

La fonctionnalité complète de toutes les bibliothèques partagées peut être vérifiée à l'aide de la Tester l'API VIES. En utilisant l'API de test, il est possible de vérifier toutes les fonctions proposées dans les plans payants sans avoir besoin de créer un compte.

Adresse du service d'essai : https://viesapi.eu/api-test

Définition de l'interface API

Une définition détaillée de l'API est disponible dans un format compatible OpenAPI et peut être téléchargée sous forme de fichier YAML ici.

L'API est également disponible en tant qu'interface client Interface utilisateur Swagger.

Exécution de la requête

Un exemple de requête sur le site de test :

GET /api-test/get/vies/euvat/PL7171642051 HTTP/1.1
Hébergeur : viesapi.eu:443
Autorisation : MAC id="api_key_id", ts="unix_timestamp", nonce="random_str", mac="b64_calculated_mac_value"
Agent utilisateur : VIESAPIClient/version_client nom_plateforme/version_plateforme

Où:

  • api_key_id – Identifiant de la clé API (sur l'environnement de production, la valeur de l'identifiant généré lors de l'inscription, sur l'environnement de test, la valeur de test_id),
  • unix_timestamp – l'heure actuelle sous la forme d'un nombre de secondes à partir de la soi-disant époque unix,
  • random_str – chaîne aléatoire, différente pour chaque requête (min. 8 caractères, max. 16 caractères),
  • b64_calculated_mac_value – HMAC calculé (à l'aide d'un API key, évaluer test_key sur l'environnement de test),
  • client_version – version client (dans nos librairies c'est la version de notre librairie API, par exemple 1.2.3),
  • platform_name – le nom de la plateforme cliente de l'API (dans nos bibliothèques c'est le nom du langage de la bibliothèque, par exemple JAVA, PHP, .NET, Python),
  • platform_version – Version de la plate-forme du client API (dans nos bibliothèques, il s'agit de la version de l'environnement de la bibliothèque, par exemple 17 pour JAVA ou 7.4 pour PHP).

Toutes les réponses renvoyées par le site Web sont au format XML.

Demande d'authentification

Spécification de la méthode d'autorisation utilisée : Authentification HTTP : Authentification d'accès MAC. Chaque requête sur notre site Web doit être authentifiée à l'aide de cette méthode. L'autorisation consiste à calculer le HMAC SHA256 à partir d'une chaîne correctement préparée et à envoyer le résultat dans l'en-tête HTTP.

Exemple

La chaîne d'entrée de la fonction HMAC est :
ts + '\n' + nonce + '\n' + method + '\n' + path + '\n' + host + '\n' + port + '\n\n'

Où:

  • ts – l'heure actuelle sous la forme d'un nombre de secondes à partir de la soi-disant époque unix, vous devez toujours fournir l'heure d'exécution de la requête actuelle (tolérance du serveur +/- 10 min par rapport à l'heure actuelle),
  • nonce – chaîne aléatoire, différente pour chaque requête (min. 8 caractères, max. 16 caractères),
  • method – Nom de la méthode HTTP (toujours GET),
  • path – chemin URL de la requête à exécuter,
  • host – Nom du serveur API VIES (toujours viesapi.eu),
  • port – Numéro de port du serveur API VIES (toujours 443),
  • ’\n’ – caractère de saut de ligne (code ASCII 10, 0x0A).

Pour la requête du numéro de TVA PL7171642051 envoyée au service de test le 2019-11-25 00:00:00 UTC, la chaîne d'entrée de la fonction HMAC ressemblera à ceci :
str = "1574640000\ndt831hs59s\nGET\n/api-test/get/vies/euvat/PL7171642051\nviesapi.eu\n443\n\n"

Le fichier de chaîne d'entrée pour cet exemple peut être téléchargé ici.

À partir de la chaîne préparée, nous calculons HMAC SHA256, comme mot de passe HMAC nous donnons le API key, c'est-à-dire dans le cas de l'API de test, la valeur de test_key:

HMAC_SHA256(str, "test_key") = 7776a12b958233ce60dd0f16b8d141e80472a1ee3b1e1fb136d7abe34cb59306

La fonction HMAC SHA256 renvoie 32 octets binaires (illustrés ci-dessus sous la forme d'un hex chaîne de caractères pour la lisibilité). Télécharger le fichier avec une valeur binaire ici.

La valeur binaire du HMAC calculé doit être encodée avec l'algorithme Base64, on obtient :

d3ahK5WCM85g3Q8WuNFB6ARyoe47Hh+xNter40y1kwY=

Cette valeur doit être envoyée en tant que valeur MAC dans l'en-tête avec les données d'autorisation. Enfin:

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

Sur la machine Linux, la valeur MAC requise peut être calculée en une seule étape à l'aide de cette commande :

$ 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