Добавката на Excel ви позволява бързо и автоматично да проверявате обекти (изпълнители), като използвате електронната таблица на Excel по отношение на текущото им състояние в VIES система.

Тази глава съдържа инструкции как да интегрирате приложението Microsoft Excel със системата VIES API. Предоставеното допълнение е успешно тествано в следните версии на MS Excel: 2007, 2010, 2013, 2016, 2019 (на операционните системи Windows и MacOS) и 2021 (на операционните системи Windows и MacOS), както и в уеб версията на Excel365.

Най-новата версия на добавката за Excel 2007, 2010, 2013, 2016 и 2019 е винаги достъпна за изтегляне от Страница за изтегляне. Добавката може да се инсталира както в 32-битова, така и в 64-битова версия на Excel. внимание! Изберете версията (32 или 64 бита), която отговаря на версията на Excel, а не операционната система.

За да изтеглите и инсталирате добавката за MacOS и Excel 2021 за Windows и Excel365, моля, посетете официалния магазин на Microsoft: https://appsource.microsoft.com.

Пълната функционалност на добавката на Excel може да се провери – без да е необходимо да създавате акаунт – използване на предоставените Тествайте API. Страницата също така описва как да конфигурирате добавка на Excel за използване в API, предоставен за тестване.

Използването на добавката в производствения API изисква създаване на акаунт на уебсайта viesapi.eu, закупуване на минимум бизнес план и генериране на ключ и неговия идентификатор. Процесът на регистрация и настройка на акаунт, както и генериране на ключове е описан на Документация уебсайт.

Инсталация и конфигурация за MS Excel 2021 и Excel 365 от Microsoft Store (AppSource)

Инсталация

След като влезете в уебсайта на официалния магазин на Microsoft https://appsource.microsoft.com, щракнете върху Get it now бутон.

Ще се покаже прозорец за влизане, в който трябва да въведете имейл адреса, за който сте създали акаунт в Microsoft (личен или корпоративен). Ако нямате такъв акаунт, можете да създадете такъв и да продължите инсталационния процес или да спрете инсталацията и да използвате опцията за инсталиране на добавката по един от начините, описани по-горе.

За да изтеглите и инсталирате добавката от Excel 2021 или Excel 365 (уеб), отидете на Insert [1], намерете раздела Добавки и щракнете върху OfficeAdd-ins бутон [2]. След това в отворения прозорец въведете думата "viesapi ′ [3] в полето за търсене и натиснете иконата на лупа. Добавка, наречена „VIES API - EU VAT Validation”, който трябва да бъде инсталиран, като щракнете върху Add бутон [4]. Всички стъпки по-горе са илюстрирани на екранната снимка по-долу:

След като щракнете върху Add трябва да се появи екран, където можете да прочетете лицензионните условия и правилата за защита на поверителността.

За да започнете инсталирането на добавката, натиснете Continue бутон.

Конфигурация

След като инсталирате правилно плъгина, трябва да видите екран, подобен на представения по-долу. В Home menu [1], намерете иконата, представляваща VIES API Panel [2] и щракнете върху него, за да се покаже страничният панел. Веднага след инсталирането добавката се конфигурира да работи в тестова среда – подробности за Тестова API страница. Използването на добавката в тестов режим не изисква създаване на акаунт в viesapi.eu уебсайт.

За да превключите добавката към производствената среда, щракнете върху ID and key [3] и въведете Key и ключ ID, които можете да намерите, след като влезете в акаунта си в сайта viesapi.eu в „API Keys" раздел. След като въведете и двете стойности, натиснете Save бутон.

Ако все още нямате акаунт на нашия уебсайт, щракнете върху връзката на viesapi.eu [4] и преминете през процеса на регистрация, който е описан подробно на Документация страница.

Инсталация и конфигурация за Excel: 2007, 2010, 2013, 2016 и 2019

Инсталация

Вземете най-новата версия на добавката за Excel 2007, 2010, 2013, 2016 и 2019 от Страница за изтегляне. Стартирайте MS Excel и отидете на File> Options, след което изберете Add-ins [1] от менюто.

В долната част на настройките изберете Excel Add-ins [2] и щракнете върху Go бутон [3].

Напредналите потребители могат да добавят добавка от Developer раздел [1], след което щракнете Excel Add-ins [2] и щракнете върху Browse [3] бутон:

В Add-ins прозорец, щракнете върху Browse бутон, отидете в директорията, където viesapi-ms-excel-addin-version-number.zip файлът беше разопакован и изберете:

• viesapiExcel.xll – за 32-битовата версия на Excel,
• viesapiExcel64.xll – за 64-битовата версия на Excel.

Правилното зареждане на добавката е показано на фигурата по-долу [1].

Достатъчно е да щракнете върху OK бутон [2], за да направите функциите, внедрени в добавката, достъпни в Excel.

Конфигурация

След инсталирането плъгинът е настроен на тестова среда по подразбиране (повече подробности на Тествайте API страница). За да можете да извиквате функции в производствената среда, е необходимо да конфигурирате достъпа до уебсайта viesapi.eu веднъж. За да направите това, отидете на която и да е електронна таблица на Excel и изпълнете функцията:

=VIESAPI.CONNECT.PRODUCTION("identifier";"key")

където функционалните параметри са:

• identifier – параметърът трябва да съдържа идентификатора (ID), генериран в акаунта на уебсайта viesapi.eu,
• key – параметърът трябва да съдържа ключа, генериран в акаунта на уебсайта viesapi.eu.

Подробности за генериране на идентификатор и ключ са описани на Документация уебсайт.

За да се провери коректността на връзката с даден API (тест или производство), трябва да се изпълни следната функция:

=VIESAPI.CONNECT.STATUS()

Което може да върне стойности:

• SUCCESS: Production – ако добавката е правилно конфигурирана да работи с производствената среда,
• SUCCESS: Test – ако добавката е правилно конфигурирана да работи с тестова среда,

• ERROR: Connection requires configuration – в случай на грешна конфигурация.

По подразбиране всеки документ на Excel е настроен да изчислява автоматично електронната таблица. Задаването на тази опция предполага, че всички формули се извикват, когато се правят промени, които засягат формулата. Пример за това е да изтриете ред в работен лист.

За да избегнете автоматичното извикване на всички функции, дефинирани в даден лист, което е свързано с автоматичното изпращане на заявки към API на уебсайта veisapi.eu, променете опцията за изчисляване на работната книга на Ръчно:

1. От File меню, изберете Options
2. Маркирайте Formulas раздел
3. В секцията Опции за изчисление изберете настройката: Manual и премахнете отметката допълнителна опция: Recalculate the workbook before saving.
4. Необходимо е да запазите направените промени в листа.

С електронната таблица на Excel, конфигурирана по такъв начин, за да принудите опресняването на всички дефинирани формули, натиснете клавишната комбинация:

CTRL + ALT + SHIFT + F9

Актуализирайте приставката до най-новата версия

внимание!Следната процедура за актуализиране на добавката на Excel работи правилно за версии на MS Excel 2019, 2021 и Excel 365, където добавката може да бъде инсталирана от Microsoft Store.

внимание! След като инсталирате най-новата версия, трябва да преконфигурирате добавката, т.е. да въведете и запазите ID и ключа.

За да инсталирате най-новата версия на добавката на Excel, изпълнете следните стъпки:

1. Проверете версията на инсталираната добавка, като извикате формулата =VIESAPI.VERSION(). Последната версия на добавката е 1.2.8

2. Изчистване на кеша на MS Excel, съгласно процедурата, описана на официалната страница с документация: https://learn.microsoft.com/en-us/office/dev/add-ins/testing/clear-cache

3. След като изпълните всички стъпки от точка 2, рестартирайте приложението MS Excel.

4. По време на рестартиране приложението MS Excel ще изтегли най-новата версия на добавката от Microsoft Store.

5. Конфигурирайте добавката, като въведете ID и ключа, изтеглени след влизане в акаунта ви в нашия уебсайт – Раздел „API ключове“.

Използване

Гледайте как автоматично и масово да проверявате статута по ДДС в ЕС на компании в системата VIES с помощта на нашата добавка за Excel:

Преди да използвате добавката, трябва да се запознаете със спецификата на нейната работа:

• Всички извиквания на функции се изпълняват в асинхронен режим, който не причинява ефекта на замразяване (без отговор) на приложението на Excel.
• Добавянето (вмъкването) на ред или колона не опреснява всички дефинирани извиквания на функции.
• Копирането или преместването на клетки, които съдържат функции, не опреснява дефинирани извиквания на функции.
• Изтриването на ред или колона ще обнови всички дефинирани извиквания на функции и ще изпрати заявки до viesApi.eu (само в случай на настройки по подразбиране на Excel). Описанието на промяната на настройките по подразбиране е включено в главата за конфигурация.
• внимание! Не се препоръчва да изпълнявате повече от 500 паралелни заявки, защото Excel има проблеми с обработката на голям брой асинхронни повиквания.

Вземете фирмени данни от VIES

VIESAPI.VIES.DATA() – Функцията извлича всички налични фирмени данни директно от VIES системата. Параметрите трябва да бъдат:

• Европейски данъчен идентификационен номер (ДДС ЕС),
• (по избор) FORMAT на върнатите данни (вижте: Етикети, които могат да се използват като FORMAT параметър).

=VIESAPI.VIES.DATA("PL7171642051")

Ако имате нужда само от статус на фирма във VIES, моля, използвайте следната заявка:

=VIESAPI.VIES.DATA("PL7171642051";"$(Valid)")

Ако върнатият статус е Да, това означава, че компанията има валиден ДДС номер в ЕС.

Етикети, налични в VIESAPI.VIES.DATA функция, която може да се използва като FORMAT параметър:

• $(UID) – уникален идентификатор, генериран от услугата viesApi.eu
• $(CountryCode) – код на държавата
• $(VATNumber) – европейски ДДС номер
• $(Valid) – отговор от услугата VIES, информиращ за текущия статус по ДДС в ЕС на проверяваната компания (Yes/No)
• $(TraderName) – регистрационно име на фирмата
• $(TraderCompanyType) – вид бизнес
• $(TraderAddress) – адрес на търговеца, където е регистрирана фирмата
• $(ID) – уникален идентификатор, генериран от системата VIES (номер за консултация)
• $(Date) – датата на генериране на отговора
• $(Source) – източникът на данните

Формат по подразбиране: "$(TraderName), $(TraderAddress)"

Ако низът "JSON" се дава като FORMAT параметър, функцията ще върне пълния резултат под формата на JSON низ, който може свободно да се анализира и обработва допълнително:

=VIESAPI.VIES.DATA("PL7171642051";"JSON")

Получаване на анализирани фирмени данни от VIES

VIESAPI.VIES.DATA.PARSED() – Функцията извлича всички налични данни за компанията директно от системата VIES. Освен това, името и адресът на компанията се връщат като анализирани данни, разделени на отделни атрибути. Параметрите трябва да бъдат:

• Европейски данъчен идентификационен номер (ДДС ЕС),
• (по избор) FORMAT на върнатите данни (вижте: Етикети, които могат да се използват като FORMAT параметър).

=VIESAPI.VIES.DATA.PARSED("PL7171642051")

Ако имате нужда само от статус на фирма във VIES, моля, използвайте следната заявка:

=VIESAPI.VIES.DATA.PARSED("PL7171642051";"$(Valid)")

Ако върнатият статус е Да, това означава, че компанията има валиден ДДС номер в ЕС.

Етикети, налични в VIESAPI.VIES.DATA.PARSED функция, която може да се използва като FORMAT параметър:

• $(UID) – уникален идентификатор, генериран от услугата viesApi.eu
• $(CountryCode) – код на държавата
• $(VATNumber) – европейски ДДС номер
• $(Valid) – отговор от услугата VIES, информиращ за текущия статус по ДДС в ЕС на проверяваната компания (Yes/No)
• $(TraderName) – регистрационно име на фирмата
• $(TraderNameComponents.Name) – име на фирмата от traderName (без правна форма)
• $(TraderNameComponents.LegalForm) – наименование на правната форма, извлечено от traderName (без името на фирмата)
• $(TraderNameComponents.LegalFormCanonicalId) – речников идентификатор на правната форма
• $(TraderNameComponents.LegalFormCanonicalName) – речниково наименование на правната форма
• $(TraderCompanyType) – вид бизнес
• $(TraderAddress) – адрес на търговеца, където е регистрирана фирмата
• $(TraderAddressComponents.Country) – име на държавата търговец на нейния национален език
• $(TraderAddressComponents.PostalCode) – пощенски код на адреса на търговеца
• $(TraderAddressComponents.City) – град на адреса на търговеца
• $(TraderAddressComponents.Street) – улица, на която се намира адресът на търговеца
• $(TraderAddressComponents.StreetNumber) – номер на сградата с адреса на търговеца
• $(TraderAddressComponents.HouseNumber) – номер на апартамент/офис по адрес на търговеца
• $(TraderAddressComponents.Other) – други данни за адреса (име на района, име на сградата, номер на етажа и др.)
• $(ID) – уникален идентификатор, генериран от системата VIES (номер за консултация)
• $(Date) – датата на генериране на отговора
• $(Source) – източникът на данните

Формат по подразбиране: "$(TraderName), $(TraderAddress)"

Ако низът "JSON" се дава като FORMAT параметър, функцията ще върне пълния резултат под формата на JSON низ, който може свободно да се анализира и обработва допълнително:

=VIESAPI.VIES.DATA.PARSED("PL7171642051";"JSON")

Проверка на състоянието на потребителския акаунт (безплатно)

VIESAPI.ACCOUNT.STATUS() – Функцията връща основна информация за плана, използван в момента от потребителя. Параметрите трябва да бъдат:

• (по избор) FORMAT на върнатите данни (вижте: Етикети, които могат да се използват като FORMAT параметър)

=VIESAPI.ACCOUNT.STATUS()

внимание! Извикването на функцията не увеличава броя на направените заявки.

Етикетите, налични в VIESAPI.ACCOUNT.STATUS функция може да се използва като FORMAT параметър:

• $(UID) – уникален идентификатор, генериран от услугата viesApi.eu
• $(BillingPlanName) – име на текущия план
• $(SubscriptionPrice) – месечна абонаментна такса
• $(ItemPrice) – цена на едно запитване извън плана
• $(ItemPriceStatus) – цена на запитване – ДДС/VIES/Статут на дейност на фирмата
• $(ItemPriceParsed) – цена на заявка – ДДС/VIES/Статут на дейност на компанията с анализирани данни
• $(Limit) – максимален брой заявки в плана
• $(RequestDelay) – минимален интервал от време между заявките
• $(DomainLimit) – максимален брой домейни (API ключове)
• $(OverPlanAllowed) – възможност за превишаване на максималния брой заявки в плана
• $(ExcelAddIn) – достъп до добавката за MS Excel
• $(Stats) – достъп до статистика на заявките
• $(NIPMonitor) – достъп до наблюдение на статуса на фирмите: ДДС/VIES/статус на дейност
• $(FuncGetVIESData) – достъп до функции, които проверяват статуса на компанията в системата VIES
• $(FuncGetVIESDataParsed) – достъп до функции, които проверяват статуса на компанията в системата VIES и анализират името и адреса на търговеца
• $(VIESDataCount) – брой VIES запитвания, извършени този месец
• $(VIESDataParsedCount) – брой VIES заявки с анализирани данни, извършени този месец
• $(TotalCount) – общ брой заявки, извършени този месец

ФОРМАТ по подразбиране: "Name of the current tariff plan: $(BillingPlanName), Monthly subscription net price: $(SubscriptionPrice), Maximum number of inquiries in the plan: $(Limit), Total number of queries made in the current month: $(TotalCount)"

Ако низът "JSON" се дава като FORMAT параметър, функцията ще върне пълния резултат под формата на JSON низ, който може свободно да се анализира и обработва допълнително.

Проверка на състоянието на VIES системата (безплатно)

VIESAPI.VIES.STATUS() – Тази функция ви позволява да проверите текущото състояние на системата VIES. Тя връща общо състояние, показващо наличността, както и списък с отделните държави членки, заедно с текущото състояние на наличност на техните национални системи. Параметрите трябва да бъдат:

• (по избор) FORMAT на върнатите данни (вижте: Етикети, които могат да се използват като FORMAT параметър)

=VIESAPI.VIES.STATUS()

внимание! Извикването на функцията не увеличава броя на направените заявки.

Етикетите, налични в VIESAPI.VIES.STATUS функция може да се използва като FORMAT параметър:

• $(UID) – уникален идентификатор, генериран от услугата viesApi.eu
• $(Available) – текуща наличност на VIES системата (Налична, Частично налична, Неналична)
• $(Countries) – списък на отделните държави-членки (Налични, Неналични)
• $(AT), $(FR), $(PL), etc. – статус на наличност на конкретна държава членка (използвайте двубуквен код на държавата като стойност на етикета)

ФОРМАТ по подразбиране: "$(Available)"

Ако низът "JSON" се дава като FORMAT параметър, функцията ще върне пълния резултат под формата на JSON низ, който може свободно да се анализира и обработва допълнително.

Други полезни функции (безплатно)

VIESAPI.ACCOUNT.STATUS.TOTAL() – Функцията връща информация за общия брой направени запитвания през текущия месец на фактуриране за даден акаунт (всички API ключове). Връща точно същото число като $(TotalCount) етикет в VIESAPI.STATUS.ACCOUNT() функция.

VIESAPI.ACCOUNT.STATUS.LIMIT() – Функцията връща информация за максималния брой налични заявки в избрания от потребителя план. Връща точно същото число като $(Limit) таг в VIES.STATUS.ACCOUNT() функция

VIESAPI.EUVAT.NORM() – Тази функция коригира и форматира ДДС номера в ЕС (премахва интервали и тирета и т.н.) офлайн и не извлича никакви данни от VIES:

=VIESAPI.EUVAT.NORM("PL 717-164-20-51")

VIESAPI.EUVAT.VALID() – Функцията проверява само коректността (синтаксис, контролна сума) на ДДС номера в ЕС офлайн и не извлича никакви данни от системата VIES. Се завръща TRUE ако номерът е валиден или FALSE ако не е валиден:

=VIESAPI.EUVAT.VALID("PL7171642051")

VIESAPI.CONNECTION.STATE() – Функцията връща текущия статус на конфигурацията на добавката.

Ако функцията върне следната стойност, това означава, наред с другото, че ID и API key не са запазени:

ERROR: Connection requires configuration

След като запазите API ID и key, функцията трябва да върне следното съобщение:

SUCCESS: Production