REST API Documentation

VIES API REST Documentation

Introduction

The API provided by us uses the standard HTTP protocol. All API functions use the HTTP GET method. Each function call requires query authorization. Data for query authorization is sent in the HTTP header.

Production service

Registration of an entity that wants to use the functionality of the viesapi.eu system is required. To do this, go to the Registration page and fill out the appropriate form. The prerequisite for using the viesapi.eu system is the acceptance of the Terms of Service. Correctly filling in the form and clicking the Register button will create an account in the viesapi.eu system and its automatic activation.

When logging in for the first time, an identifier is automatically generated along with the corresponding key. The identifier is public and does not require protection, while the key is private and should not be made available to third parties.

Production service address: https://viesapi.eu/api

Test service

The full functionality of all shared libraries can be checked using the shared Test VIES API. By using the test API, it is possible to check all the functions offered in paid plans without the need to create an account.

Test service address: https://viesapi.eu/api-test

API interface definition

A detailed definition of the API is available in an OpenAPI compatible format and can be downloaded as a YAML file here.

API is also available as a client interface Swagger UI.

Execution of the query

An example of making a query to the test site:

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

Where:

  • api_key_id – API key identifier (on the production environment, the value of the identifier generated during registration, on the test environment, the value of test_id),
  • unix_timestamp – the current time in the form of a number of seconds from the so-called unix epoch,
  • random_str – random string, different for each query (min. 8 characters, max. 16 characters),
  • b64_calculated_mac_value – calculated HMAC (using an API key, value test_key on the test environment),
  • client_version – client version (in our libraries it is the version of our API library, e.g. 1.2.3),
  • platform_name – the name of the API client platform (in our libraries it is the name of the library language, e.g. JAVA, PHP, .NET, Python),
  • platform_version – API client platform version (in our libraries it is the library environment version, eg 17 for JAVA, or 7.4 for PHP),
  • mime_type – MIME type name in which the response should be returned, two types are supported: text/xml and application/json, if request does not contain Accept header, XML is returned by default.

Authentication request

Authorization data must be prepared in accordance with HTTP Authentication: MAC Access Authentication and this is recommended authentication method. It is also possible to use the HTTP Authentication: Basic Authentication method, however for security reasons, please use it only when using the first method is not possible for some reason.

Each query to our website must be authenticated using one of the two availabe methods.

Method 1 – HMAC (recommended)

Specification of the authorization method used: HTTP Authentication: MAC Access Authentication. Authorization consists in calculating the HMAC SHA256 from a properly prepared string and sending the result in the HTTP header.

Example

The input string to the HMAC function is:
ts + '\n' + nonce + '\n' + method + '\n' + path + '\n' + host + '\n' + port + '\n\n'

Where:

  • ts – the current time in the form of a number of seconds from the so-called unix epoch, you should always provide the current query execution time (server tolerance +/- 10 min in relation to the current time),
  • nonce – random string, different for each query (min. 8 characters, max. 16 characters),
  • method – HTTP method name (always GET),
  • path – URL path of the query to be executed,
  • host – VIES API server name (always viesapi.eu),
  • port – VIES API server port number (always 443),
  • ’\n’ – newline character (ASCII code 10, 0x0A).

For the query for the VAT number PL7171642051 sent to the test service on 2019-11-25 00:00:00 UTC the input string to the HMAC function will look like this:
str = "1574640000\ndt831hs59s\nGET\n/api-test/get/vies/euvat/PL7171642051\nviesapi.eu\n443\n\n"

The input string file for this example can be downloaded here.

From the prepared string, we calculate HMAC SHA256, as the HMAC password we give the API key, i.e. in the case of the test API, the value of test_key:

HMAC_SHA256(str, "test_key") = 7776a12b958233ce60dd0f16b8d141e80472a1ee3b1e1fb136d7abe34cb59306

The HMAC SHA256 function returns 32 binary bytes (shown above as a hex string for readability). Download file with binary value here.

The binary value of the calculated HMAC should be encoded with the Base64 algorithm, we get:

d3ahK5WCM85g3Q8WuNFB6ARyoe47Hh+xNter40y1kwY=

This value should be sent as MAC value in the header with data for authorization. Finally:

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

On Linux machine required MAC value can be calculated in one step using this command:

$ 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

Method 2 – Basic Authentication

Specification of this authorization method used: HTTP Authentication: Basic Authentication.

Example 1

The input string to the Base64 function is:

str = key_id + ':' + key

Where:

  • key_id – API key identifier (in the case of a test environment, test_id string),
  • key – API key (in the case of a test environment, string test_key).

For the test environment, the input string for the Base64 function will be:

str = "test_id:test_key"

After applying the Base64 function, we get:

Base64(str) = dGVzdF9pZDp0ZXN0X2tleQ==

This value should be sent as a Basic value in the header with data for authorization. Ultimately:

Authorization: Basic dGVzdF9pZDp0ZXN0X2tleQ==

Example 2

The following example shows a query that can be invoked in a test environment from a web browser. Just copy and paste it into the browser address bar:

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

Where:

  • test_id – to authenticate in a production environment, parameter should contain a valid key identifier used for authorization,
  • test_key – to authenticate in a production environment, parameter should contain a valid value of the key used for authorization.

The key identifier and the key are generated by the user after logging in to his account on the viesapi.eu portal (API keys tab). See the documentation page for more information on ID and key generation.

Response

If the request is handled correctly, the following response is generated:

Detailed description of returned attributes:

  • uid – unique query identifier generated by viesapi.eu,
  • countryCode – country code in which the company associated with the EU VAT number provided in the inquiry is registered,
  • vatNumber – EU VAT number of the verified company provided in the inquiry,
  • valid – response from the VIES service, informing about the current EU VAT status of the checked entity:
    • true – the EU VAT number provided in the inquiry is valid,
    • false – the EU VAT number provided in the inquiry is not valid,
  • traderName – company’s trade name,
  • traderCompanyType – always returned a string of ‘-‘ characters,
  • traderAddress – company address where the company is registered,
  • id – unique query identifier generated by the VIES system
  • date – query execution date
  • source – data source, always: http://ec.europa.eu

Error response

In case of any error related to the handling of the request, the following error message is returned:

Error

Detailed description of returned attributes:

  • code – unique error code for automatic error handling,
  • description – human-interceptable error description,
  • details – more detailed error description (optional),

Error codes

The table below lists all possible errors returned by REST APIs and programming libraries:

Error code Error message
8 Invalid request format
10 Invalid API path
11 Internal service error
22 EU VAT number is invalid
23 Failed to get data from VIES system
26 This feature is not available on the currently selected plan
27 This function does not support this search mode
33 Querying the given data is not possible in the test mode
35 No access query authorization required
36 The service is temporarily unavailable due to scheduled technical work
43 The number of user queries for the current month could not be retrieved
54 Incorrect date or time on the user\s computer or system
55 Invalid MAC string value in header with query credentials
57 Invalid key value in header with query credentials
58 The maximum number of concurrent queries for this Member State has been reached
59 The application at the Member State is not replying or not available
101 The connection IP number does not match the IP number assigned to the API key
102 API key is blocked
103 Invalid API key
104 The maximum number of queries available for the selected plan has been reached
105 Account blocked or deleted
106 Invalid account type
107 The pre-paid account has not been paid
108 Invalid API key ID
201 Failed to connect to the VIES API service
202 VIES API service response has invalid format
203 Invalid number type
204 NIP is invalid
205 EU VAT ID is invalid
206 Function generated an exception
207 Date has an invalid format
208 Invalid input parameter