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

вступ

Наданий нами 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 (за допомогою 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).

Усі відповіді, які повертає веб-сайт, мають формат 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