Документация за 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/клиентска_версия име_на_платформа/версия_на_платформа

Където:

  • 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