Документація VIES API REST

вступ

Наданий нами API використовує стандартний протокол HTTP. Усі функції API використовують метод HTTP GET. Кожен виклик функції вимагає авторизації запиту. Дані для авторизації запиту надсилаються в HTTP-заголовку.

Сервіс виробництва

Потрібна реєстрація суб’єкта, який бажає використовувати функціональні можливості системи viesapi.eu. Для цього перейдіть до Реєстрація сторінку та заповніть відповідну форму. Передумовою використання системи viesapi.eu є прийняття Умови обслуговування. Правильно заповнивши форму та натиснувши кнопку зареєструватися кнопка створить обліковий запис у системі viesapi.eu та його автоматичну активацію.

Під час першого входу автоматично генерується ідентифікатор разом із відповідним ключем. Ідентифікатор є загальнодоступним і не потребує захисту, а ключ є закритим і не повинен надаватися третім особам.

Адреса служби виробництва: https://viesapi.eu/api

Тестовий сервіс

Повну функціональність усіх спільних бібліотек можна перевірити за допомогою спільної бібліотеки Перевірте VIES API. Використовуючи тестовий API, можна перевірити всі функції, які пропонуються в платних планах без необхідності створення облікового запису.

Адреса тестової служби: https://viesapi.eu/api-test

Визначення інтерфейсу API

Детальне визначення API доступне у форматі, сумісному з OpenAPI, і його можна завантажити як файл YAML тут.

API також доступний як клієнтський інтерфейс Swagger UI.

Виконання запиту

Приклад оформлення запиту на тестовий сайт:

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

Де:

api_key_id – Ідентифікатор ключа API (у робочому середовищі значення ідентифікатора, згенерованого під час реєстрації, у тестовому середовищі значення test_id),
unix_timestamp – поточний час у вигляді кількості секунд від т.зв епоха unix,
random_str – випадковий рядок, різний для кожного запиту (мін. 8 символів, макс. 16 символів),
b64_calculated_mac_value – розрахований HMAC (за допомогою an API key, значення test_key на тестовому середовищі),
client_version – версія клієнта (в наших бібліотеках це версія нашої бібліотеки API, наприклад 1.2.3),
platform_name – назва клієнтської платформи API (в наших бібліотеках це назва мови бібліотеки, наприклад, JAVA, PHP, .NET, Python),
platform_version – Версія клієнтської платформи API (в наших бібліотеках це версія бібліотечного середовища, наприклад, 17 для JAVA або 7.4 для PHP),
mime_type – Назва типу MIME, у якому має бути повернута відповідь, підтримуються два типи: text/xml і application/json, якщо запит не містить заголовка Accept, за замовчуванням повертається XML.

Запит на автентифікацію

Авторизаційні дані повинні бути підготовлені відповідно до HTTP-автентифікація: MAC-автентифікація доступу і це рекомендований метод автентифікації. Також можна використовувати Автентифікація HTTP: базова автентифікація однак з міркувань безпеки використовуйте його лише тоді, коли використання першого методу з певних причин неможливе.

Кожен запит до нашого веб-сайту має бути автентифікований за допомогою одного з двох доступних методів.

Спосіб 1 – HMAC (рекомендовано)

Специфікація використовуваного методу авторизації: HTTP-автентифікація: MAC-автентифікація доступу. Авторизація полягає в обчисленні HMAC SHA256 із правильно підготовленого рядка та надсиланні результату в заголовку HTTP.

приклад

Вхідний рядок для функції HMAC:
ts + '\n' + nonce + '\n' + method + '\n' + path + '\n' + host + '\n' + port + '\n\n'

Де:

ts – поточний час у вигляді кількості секунд від т.зв епоха unix, ви завжди повинні надавати поточний час виконання запиту (допуск сервера +/- 10 хв по відношенню до поточного часу),
nonce – випадковий рядок, різний для кожного запиту (мін. 8 символів, макс. 16 символів),
method – Назва методу HTTP (завжди GET),
path – URL-шлях запиту, який буде виконано,
host – Ім’я сервера VIES API (завжди viesapi.eu),
port – Номер порту сервера VIES API (завжди 443),
’\n’ – символ нового рядка (код ASCII 10, 0x0A).

Для запиту щодо номера платника ПДВ PL7171642051, надісланого тестовій службі 2019-11-25 00:00:00 UTC, вхідний рядок у функцію HMAC виглядатиме так:
str = "1574640000\ndt831hs59s\nGET\n/api-test/get/vies/euvat/PL7171642051\nviesapi.eu\n443\n\n"

Файл вхідного рядка для цього прикладу можна завантажити тут.

З підготовленого рядка ми обчислюємо HMAC SHA256 як пароль HMAC, який ми надаємо API key, тобто у випадку тестового API, значення test_key:

HMAC_SHA256(str, "test_key") = 7776a12b958233ce60dd0f16b8d141e80472a1ee3b1e1fb136d7abe34cb59306

Функція HMAC SHA256 повертає 32 двійкові байти (показано вище як a hex рядок для читабельності). Завантажте файл із двійковим значенням тут.

Двійкове значення розрахованого HMAC потрібно закодувати за допомогою алгоритму Base64, отримуємо:

d3ahK5WCM85g3Q8WuNFB6ARyoe47Hh+xNter40y1kwY=

Це значення має надсилатися як значення MAC у заголовку з даними для авторизації. Нарешті:

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

На машині Linux необхідне значення MAC можна обчислити за один крок за допомогою цієї команди:

$ 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

Спосіб 2 – базова автентифікація

Специфікація цього використаного методу авторизації: Автентифікація HTTP: базова автентифікація .

Приклад 1

Вхідний рядок для функції Base64:

str = key_id + ':' + key

Де:

key_id – ідентифікатор ключа API (у випадку тестового середовища, test_id рядок),
key – ключ API (у випадку тестового середовища – рядок test_key).

Для тестового середовища вхідний рядок для функції Base64 буде таким:

str = "test_id:test_key"

Після застосування функції Base64 ми отримуємо:

Base64(str) = dGVzdF9pZDp0ZXN0X2tleQ==

Це значення слід надіслати як базове значення в заголовку з даними для авторизації. Зрештою:

Authorization: Basic dGVzdF9pZDp0ZXN0X2tleQ==

Приклад 2

У наступному прикладі показано запит, який можна викликати в тестовому середовищі з веб-браузера. Просто скопіюйте та вставте його в адресний рядок браузера:

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

Де:

test_id – для аутентифікації у виробництві навколишнє середовище, параметр повинен містити дійсний ідентифікатор ключа, який використовується для авторизації,
test_key – для аутентифікації у виробництві середовища, параметр повинен містити дійсне значення ключа, який використовується для авторизації.

Ідентифікатор ключа та ключ генеруються користувачем після входу в обліковий запис на viesapi.eu портал (API keys вкладка). Сee the документація сторінку для отримання додаткової інформації про створення ідентифікатора та ключа.

Відповідь

Якщо запит оброблено правильно, буде згенеровано таку відповідь:

Детальний опис повернутих атрибутів:

uid – унікальний ідентифікатор запиту, згенерований viesapi.eu,
countryCode – код країни, у якій зареєстрована компанія, пов’язана з номером ПДВ ЄС, наданим у запиті,
vatNumber – Номер платника ПДВ ЄС перевіреної компанії, наданий у запиті,
valid – відповідь від сервісу VIES з інформацією про поточний ПДВ-статус ЄС перевіряється:
- true – номер ПДВ ЄС, наданий у запиті, дійсний,
- false – номер ПДВ ЄС, наданий у запиті, недійсний,
traderName - фірмове найменування підприємства,
traderCompanyType – завжди повертав рядок із символів «-»,
traderAddress – адреса компанії, за якою зареєстрована компанія,
id – унікальний ідентифікатор запиту, згенерований системою VIES
date – дата виконання запиту
source – джерело даних, завжди: http://ec.europa.eu

Відповідь на помилку

У разі будь-якої помилки, пов’язаної з обробкою запиту, повертається таке повідомлення про помилку:

Помилка