Документация за 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 автентификация за достъп и това е препоръчителен метод за удостоверяване. Също така е възможно да се използва 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_id – API ключов идентификатор (в случай на тестова среда, test_id низ),
  • key – API ключ (в случай на тестова среда, низ test_key).

За тестовата среда входният низ за функцията Base64 ще бъде:

str = "test_id:test_key"

След прилагане на функцията Base64 получаваме:

Base64(str) = dGVzdF9pZDp0ZXN0X2tleQ==

Тази стойност трябва да бъде изпратена като основна стойност в заглавката с данни за оторизация. В крайна сметка:

Упълномощаване: Основно 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 документация страница за повече информация относно генерирането на ID и ключ.

Отговор

Ако заявката е обработена правилно, се генерира следният отговор:

Подробно описание на върнатите атрибути:

  • uid – уникален идентификатор на заявка, генериран от viesapi.eu,
  • countryCode – код на държавата, в която е регистрирано дружеството, свързано с ДДС номера в ЕС, предоставен в запитването,
  • vatNumber – ЕС ДДС номер на проверената компания, посочен в запитването,
  • valid – отговор от услугата VIES, информиращ за текущия статут по ДДС в ЕС на проверяваното лице:
    • true – ДДС номерът на ЕС, предоставен в запитването, е валиден,
    • false – ДДС номерът на ЕС, предоставен в запитването, не е валиден,
  • traderName – търговско наименование на фирмата,
  • traderCompanyType – винаги връщаше низ от знаци „-“,
  • traderAddress – адрес на фирмата, където е регистрирана фирмата,
  • id – уникален идентификатор на заявка, генериран от системата VIES
  • date – дата на изпълнение на заявката
  • source – източник на данни, винаги: http://ec.europa.eu

Отговор за грешка

В случай на грешка, свързана с обработката на заявката, се връща следното съобщение за грешка:

Грешка

Подробно описание на върнатите атрибути:

  • code – уникален код за грешка за автоматично обработване на грешки,
  • description – описание на прихваната от човека грешка,
  • details – мподробно описание на грешката (по избор),