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 (използвайки anAPI 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
Следващият пример показва заявка, която може да бъде извикана в тестова среда от уеб браузър. Просто го копирайте и поставете в адресната лента на браузъра:
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– уникален идентификатор на заявка, генериран от системата VIESdate– дата на изпълнение на заявкатаsource– източник на данни, винаги: http://ec.europa.eu
Отговор за грешка
В случай на грешка, свързана с обработката на заявката, се връща следното съобщение за грешка:
Подробно описание на върнатите атрибути:
code– уникален код за грешка за автоматично обработване на грешки,description– описание на прихваната от човека грешка,details– мподробно описание на грешката (по избор),
Кодове за грешки
Таблицата по-долу изброява всички възможни грешки, върнати от REST API и програмни библиотеки:
| Код на грешка | Съобщение за грешка |
| 8 | Невалиден формат на заявката |
| 10 | Невалиден API път |
| 11 | Вътрешна сервизна грешка |
| 22 | Номерът по ДДС в ЕС е невалиден |
| 23 | Неуспешно получаване на данни от системата VIES |
| 26 | Тази функция не е налична за текущо избрания план |
| 27 | Тази функция не поддържа този режим на търсене |
| 33 | Запитването на дадените данни не е възможно в тестов режим |
| 35 | Не се изисква разрешение за заявка за достъп |
| 36 | Услугата временно не е достъпна поради планирани технически дейности |
| 43 | Броят потребителски заявки за текущия месец не можа да бъде извлечен |
| 54 | Неправилна дата или час на компютъра или системата на потребителя |
| 55 | Невалидна стойност на MAC низ в заглавката с идентификационни данни за заявка |
| 57 | Невалидна стойност на ключ в заглавката с идентификационни данни за заявка |
| 58 | Максималният брой едновременни заявки за тази държава членка е достигнат |
| 59 | Приложението в държавата членка не отговаря или не е достъпно |
| 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 | Невалиден входен параметър |