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

Документація 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

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

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

Де:

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

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

getVIESData відповідь

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

vies api - getVIESDataParsed

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

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

getVIESDataParsed відповідь

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

vies api - getVIESDataParsed

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

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

Важливе застереження!

Функція синтаксичного аналізу використовує зовнішні алгоритми штучного інтелекту та API для автоматичного вилучення таких атрибутів, як: місто, поштовий індекс, вулиця з номером вулиці (номер будинку) і номер будинку, тому ми не можемо гарантувати правильну роботу 100%.

getVIESDataAsync відповідь

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

Відповідь VIES API getVIESDataAsync

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

  • token – пакетний маркер (guid), згенерований viesapi.eu, слід використовувати для виклику функції getVIESDataAsync (через 2-3 хвилини), щоб отримати результати.

getVIESDataAsyncResult відповідь

Якщо запит оброблено правильно, повинна бути згенерована така відповідь, яка містить список об’єктів із даними, які повертає VIES:

vies api getVIESDataAsyncResults

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

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

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

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

відповідь на помилку vies rest api

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

  • code – унікальний код помилки для автоматичної обробки помилок,
  • description – опис помилок, які перехоплює людина,
  • details – мдокладний опис помилки (необов'язково),

Коди помилок

У таблиці нижче перераховано всі можливі помилки, які повертаються REST API та бібліотеками програмування:

Код помилки Повідомлення про помилку
8 Недійсний формат запиту
10 Недійсний шлях API
11 Внутрішня помилка служби
22 Номер ПДВ ЄС недійсний
23 Не вдалося отримати дані з системи VIES
26 Ця функція недоступна в поточному вибраному плані
27 Ця функція не підтримує цей режим пошуку
33 Запит даних даних неможливий у тестовому режимі
35 Авторизація запиту доступу не потрібна
36 Послуга тимчасово недоступна через планові технічні роботи
43 Не вдалося отримати кількість запитів користувачів за поточний місяць
54 Неправильна дата або час на комп’ютері або системі користувача
55 Недійсне значення рядка MAC у заголовку з обліковими даними запиту
57 Недійсне значення ключа в заголовку з обліковими даними запиту
58 Досягнуто максимальної кількості одночасних запитів для цієї держави-члена
59 Програма в державі-члені не відповідає або недоступна
62 Пакет ще обробляється, повторіть спробу пізніше
63 Досягнуто максимальної кількості пакетних запитів. Надішліть запит пізніше
101 IP-номер підключення не збігається з IP-номером, призначеним ключу API
102 Ключ API заблоковано
103 Недійсний ключ API
104 Досягнуто максимальної кількості запитів, доступних для вибраного плану
105 Обліковий запис заблоковано або видалено
106 Недійсний тип облікового запису
107 Рахунок передоплати не сплачено
108 Недійсний ідентифікатор ключа API
201 Не вдалося підключитися до служби API VIES
202 Відповідь служби VIES API має недійсний формат
203 Недійсний тип номера
204 NIP недійсний
205 Ідентифікаційний номер ПДВ ЄС недійсний
206 Функція створила виняток
207 Дата має недійсний формат
208 Недійсний вхідний параметр
209 Перевищено ліміт розміру партії [2-99]