вступ
Наданий нами 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
Хост: viesapi.eu:443
Авторизація: MAC id="api_key_id", ts="unix_timestamp", nonce="random_str", mac="b64_calculated_mac_value"
Агент користувача: VIESAPIClient/client_version назва_платформи/версія_платформи
Де:
api_key_id
– Ідентифікатор ключа API (у робочому середовищі значення ідентифікатора, згенерованого під час реєстрації, у тестовому середовищі значення test_id),unix_timestamp
– поточний час у вигляді кількості секунд від т.зв епоха unix,random_str
– випадковий рядок, різний для кожного запиту (мін. 8 символів, макс. 16 символів),b64_calculated_mac_value
– розрахований HMAC (за допомогою anAPI key
, значенняtest_key
на тестовому середовищі),client_version
– версія клієнта (в наших бібліотеках це версія нашої бібліотеки API, наприклад 1.2.3),platform_name
– назва клієнтської платформи API (в наших бібліотеках це назва мови бібліотеки, наприклад, JAVA, PHP, .NET, Python),platform_version
– Версія клієнтської платформи API (в наших бібліотеках це версія середовища бібліотеки, наприклад, 17 для JAVA або 7.4 для PHP).
Усі відповіді, які повертає веб-сайт, мають формат XML.
Запит на автентифікацію
Специфікація використовуваного методу авторизації: 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