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

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

All responses returned by the website are in XML format.

Authentication request

Specification of the authorization method used: HTTP Authentication: MAC Access Authentication. Each query to our website must be authenticated using this method. 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") = 6ECF32FAAB8A3BBFAF33019B356CD82425E98351DCDFBCFEC2263E9DBE2DC1C8

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:

bs8y+quKO7+vMwGbNWzYJCXpg1Hc37z+wiY+nb4twcg=

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

Authorization: MAC id="test_id", ts="1574640000", nonce="dt831hs59s", mac="bs8y+quKO7+vMwGbNWzYJCXpg1Hc37z+wiY+nb4twcg="