Documentation API REST

Documentation de l'API REST de VIES

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 invoquée dans un Environnement de test depuis 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.

getVIESData réponse

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

API Vies - getVIESDataParsed

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 l’entreprise où la société est enregistrée (format original),
  • traderAddressComponent – détails de l'adresse du groupement de composants – attribut facultatif, ne sera jamais renvoyé dans cette fonction.
  • id – identifiant unique de requête généré par le système VIES (Numéro de consultation),
  • date – date d'exécution de la requête
  • source – source de données, toujours : http://ec.europa.eu

obtenirVIESDataParsed réponse

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

données de l'API REST de Vies analysées et réponse

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 – nom d'enregistrement de l'entreprise (format original),
  • traderNameComponents – forme juridique de la société de groupement de composants :
    • name – nom de l’entreprise de traderName (sans forme juridique),
    • legalForm – nom de la forme juridique extrait de traderName (sans raison sociale),
    • legalFormCanonicalId – identifiant du dictionnaire de la forme juridique,
    • legalFromCanonicalName – nom du dictionnaire de la forme juridique,
  • traderCompanyType – renvoyait toujours une chaîne de caractères '-',
  • traderAddress – adresse de l’entreprise où la société est enregistrée (format original),
  • traderAddressComponent – détails de l'adresse du groupe de composants :
    • country – nom du pays commerçant dans sa langue nationale,
    • postalCode – code postal de l’adresse du commerçant,
    • city – ville de l’adresse du commerçant,
    • street -rue de l'adresse du commerçant,
    • streetNumber – numéro de rue de l’adresse du commerçant,
    • houseNumber – numéro de maison de l’adresse du commerçant,
  • id – identifiant unique de requête généré par le système VIES (Numéro de consultation),
  • date – date d’exécution de la requête,
  • source – source de données, toujours : http://ec.europa.eu
legalFormCanonicalId legalFormCanonicalName 
0 INCONNU
1 ENTREPRISE INDIVIDUELLE
2 SOCIÉTÉ À RESPONSABILITÉ LIMITÉE
3 PARTENARIAT_GÉNÉRAL
4 SOCIÉTÉ PAR ACTIONS
5 SOCIÉTÉ EN COMMANDITE
6 SOCIÉTÉ À RESPONSABILITÉ LIMITÉE
7 SOCIÉTÉ PAR ACTIONS À MEMBRE UNIQUE
8 SOCIÉTÉ À RESPONSABILITÉ LIMITÉE SIMPLE
9 SOCIÉTÉ À RESPONSABILITÉ LIMITÉE À MEMBRE UNIQUE
10 SOCIÉTÉ PAR ACTIONS SIMPLIFIÉE
11 PETITE_ENTREPRISE
12 SOCIÉTÉ EN COMMANDITE PAR ACTIONS
13 PARTENARIAT_PROFESSIONNEL
14 SOCIÉTÉ EN RESPONSABILITÉ LIMITÉE
15 PARTENARIAT PRIVÉ
16 SOCIÉTÉ À RESPONSABILITÉ LIMITÉE
17 SOCIÉTÉ À RESPONSABILITÉ LIMITÉE
18 INSTITUTION PUBLIQUE

Avis de non-responsabilité important!

La fonction d'analyse utilise des algorithmes d'IA externes et des API pour extraire automatiquement des attributs tels que : la ville, le code postal, la rue avec le numéro de rue (numéro de bâtiment) et le numéro de maison, nous ne pouvons donc pas garantir son bon fonctionnement 100%.

obtenirVIESDataAsync réponse

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

Réponse getVIESDataAsync de l'API VIES

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

  • token – le jeton de lot (guid) généré par viesapi.eu, doit être utilisé pour appeler la fonction getVIESDataAsync (après 2-3 minutes) pour obtenir des résultats.

obtenirVIESDataAsyncResult réponse

Si la demande est traitée correctement, la réponse suivante devrait être générée, contenant une liste d'objets avec des données renvoyées par VIES:

API Vies getVIESDataAsyncResults

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

  • numbers – un tableau d'objets avec des résultats renvoyés par VIES correspondant aux numéros de TVA de l'UE envoyés dans la demande d'appel de fonction getVIESDataAsync
    • 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 l’entreprise où la société est enregistrée (format original),
    • id – identifiant unique de requête généré par le système VIES (Numéro de consultation),
    • date – date d'exécution de la requête
    • source – source de données, toujours : http://ec.europa.eu
  • errors – tableau d'objets avec des erreurs renvoyées par VIES pour les données de numéro de TVA de l'UE envoyées dans la demande d'appel de fonction getVIESDataAsync
    • 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,
    • error – détails de l'erreur renvoyée pour ce numéro de TVA UE spécifique
    • 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é :

réponse d'erreur de l'API REST de Vies

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

Codes d'erreur

Le tableau ci-dessous répertorie toutes les erreurs possibles renvoyées par les API REST et les bibliothèques de programmation :

Code d'erreur Message d'erreur
8 Format de demande non valide
10 Chemin d'API non valide
11 Erreur de service interne
22 Le numéro de TVA de l'UE n'est pas valide
23 Impossible d'obtenir les données du système VIES
26 Cette fonctionnalité n'est pas disponible sur le plan actuellement sélectionné
27 Cette fonction ne prend pas en charge ce mode de recherche
33 L'interrogation des données fournies n'est pas possible en mode test
35 Aucune autorisation de requête d'accès requise
36 Le service est temporairement indisponible en raison de travaux techniques programmés
43 Le nombre de requêtes des utilisateurs pour le mois en cours n'a pas pu être récupéré
54 Date ou heure incorrecte sur l'ordinateur ou le système de l'utilisateur
55 Valeur de chaîne MAC non valide dans l'en-tête avec les informations d'identification de la requête
57 Valeur de clé non valide dans l'en-tête avec les informations d'identification de la requête
58 Le nombre maximal de requêtes simultanées pour cet État membre a été atteint
59 La demande de l'État membre ne répond pas ou n'est pas disponible
62 Le lot est toujours en cours de traitement, réessayez plus tard
63 Le nombre maximum de demandes par lots a été atteint, veuillez soumettre à nouveau votre demande ultérieurement
101 Le numéro IP de connexion ne correspond pas au numéro IP attribué à la clé API
102 La clé API est bloquée
103 Clé API non valide
104 Le nombre maximum de requêtes disponibles pour le plan sélectionné a été atteint
105 Compte bloqué ou supprimé
106 Type de compte invalide
107 Le compte prépayé n'a pas été payé
108 ID de clé API non valide
201 Échec de la connexion au service API VIES
202 La réponse du service API VIES a un format non valide
203 Type de numéro non valide
204 Le NIP n'est pas valide
205 Le numéro de TVA de l'UE n'est pas valide
206 La fonction a généré une exception
207 La date a un format non valide
208 Paramètre d'entrée non valide
209 Limite de taille de lot dépassée [2-99]