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

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

Важен отказ от отговорност!

Функцията за синтактичен анализ използва външни AI алгоритми и 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 Неуспешно свързване с услугата VIES API
202 Отговорът на услугата VIES API има невалиден формат
203 Невалиден тип номер
204 NIP е невалиден
205 Идентификационният номер по ДДС в ЕС е невалиден
206 Функцията генерира изключение
207 Датата има невалиден формат
208 Невалиден входен параметър
209 Ограничението за размер на партидата е надвишено [2-99]