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
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

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 plateforme client API (dans nos librairies c'est la version de l'environnement de la librairie, par exemple 17 pour JAVA, ou 7.4 pour PHP),
  • mime_type – Nom du type MIME dans lequel la réponse doit être renvoyée, deux types sont pris en charge : text/xml et application/json, si la requête ne contient pas d'en-tête Accept, XML est renvoyé par défaut.

Demande d'authentification

Les données d'autorisation doivent être préparées conformément aux Authentification HTTP : Authentification d'accès MAC et c'est la méthode d'authentification recommandée. Il est également possible d'utiliser le Authentification HTTP : authentification de base méthode, mais pour des raisons de sécurité, veuillez ne l'utiliser que lorsque l'utilisation de la première méthode n'est pas possible pour une raison quelconque.

Chaque requête sur notre site Web doit être authentifiée à l'aide de l'une des deux méthodes disponibles.

Méthode 1 – HMAC (recommandé)

Spécification de la méthode d'autorisation utilisée : Authentification HTTP : Authentification d'accès MAC. 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

Méthode 2 - Authentification de base

Spécification de cette méthode d'autorisation utilisée : Authentification HTTP : authentification de base.

Exemple 1

La chaîne d'entrée de la fonction Base64 est :

str = key_id + ':' + key

Où:

  • key_id – Identifiant de clé API (dans le cas d'un environnement de test, test_id chaîne),
  • key – Clé API (dans le cas d'un environnement de test, chaîne test_key).

Pour l'environnement de test, la chaîne d'entrée pour la fonction Base64 sera :

str = "test_id:test_key"

Après application de la fonction Base64, nous obtenons :

Base64(str) = dGVzdF9pZDp0ZXN0X2tleQ==

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

Authorization: Basic dGVzdF9pZDp0ZXN0X2tleQ==

Exemple 2

L'exemple suivant montre une requête qui peut être appelée dans un environnement de test à partir d'un navigateur Web. Copiez-le et collez-le simplement dans la barre d'adresse du navigateur :

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

Où:

  • test_id – pour s'authentifier dans une production environnement, le paramètre doit contenir un identifiant de clé valide utilisé pour l'autorisation,
  • test_key – pour s'authentifier dans une production environnement, le paramètre doit contenir une valeur valide de la clé utilisée pour l'autorisation.

L'identifiant de la clé et la clé sont générés par l'utilisateur après s'être connecté à son compte sur le viesapi.eu portail (API keys languette). Svoila le Documentation page pour plus d'informations sur la génération d'identifiants et de clés.

Réponse

Si la requête est correctement traitée, la réponse suivante est générée :

Description détaillée des attributs renvoyés :

  • uid – identifiant de requête unique généré par viesapi.eu,
  • countryCode – code pays dans lequel est enregistrée la société associée au numéro de TVA intracommunautaire fourni dans la demande,
  • vatNumber – Numéro de TVA intracommunautaire de l'entreprise vérifiée fourni dans la demande,
  • valid – réponse du service VIES, informant du statut TVA UE actuel de l'entité contrôlée :
    • true – le numéro de TVA intracommunautaire fourni dans la demande est valide,
    • false – le numéro de TVA intracommunautaire fourni dans la demande n'est pas valide,
  • traderName – le nom commercial de la société,
  • traderCompanyType – renvoyait toujours une chaîne de caractères '-',
  • traderAddress – adresse de la société où la société est enregistrée,
  • id – identifiant de requête unique généré par le système VIES
  • date – date d'exécution de la requête
  • source – source de données, toujours : http://ec.europa.eu

Réponse d'erreur

En cas d'erreur liée au traitement de la requête, le message d'erreur suivant est renvoyé :

Erreur

Description détaillée des attributs renvoyés :

  • code – code d'erreur unique pour la gestion automatique des erreurs,
  • description – description de l'erreur interceptable par l'homme,
  • details – mdescription détaillée de l'erreur (facultatif),