Добавка на Excel VIES Валидатор

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

Тази глава съдържа инструкции как да интегрирате приложението Microsoft Excel със системата nip24.pl. Предоставената добавка е успешно тествана в следните версии на 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 бутон.

vies excel групово валидиране

Ще се покаже прозорец за влизане, в който трябва да въведете имейл адреса, за който сте създали акаунт в 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] бутон:

vies excel

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

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

vies excel insatllation

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

конфигурация на vies excel

Достатъчно е да щракнете върху 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) – Валиден статут номер по ДДС в ЕС (Yes/No)
  • $(TraderName) – Име на изпълнителя/доставчика
  • $(TraderCompanyType) - Бизнес тип
  • $(TraderAddress) – Адрес на контрагента
  • $(ID) – Уникален идентификатор, генериран от системата VIES
  • $(Date) – Датата на генериране на отговора
  • $(Source) – Източникът на данните

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

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

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

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

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

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

=VIESAPI.STATUS.ACCOUNT()

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

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

  • $(BillingPlanName) – Име на текущия тарифен план
  • $(SubscriptionPrice) – Нетна цена на месечния абонамент
  • $(ItemPrice) – Единично запитване нетни разходи извън плана в стандартния план
  • $(ItemPriceStatus) – Нетна цена на едно запитване – VIES / Бизнес статус на субекта в индивидуален план
  • $(Limit) – Максималният брой заявки в плана
  • $(RequestDelay) – Минималният интервал от време между заявките
  • $(DomainLimit) – Максимален брой домейни (API ключове)
  • $(OverPlanAllowed) – Възможност за надвишаване на максималния брой заявки в плана
  • $(ExcelAddIn) – Достъп чрез добавката MS Excel
  • $(Stats) – Достъп до статистика на извършените заявки
  • $(NIPMonitor) – Достъп до наблюдение на състоянието на VIES
  • $(SearchByNIP) – Търсене по данъчен идентификационен номер по ДДС в ЕС
  • $(FuncGetVIESData) – Достъп до функции, които проверяват състоянието на обекта в системата VIES
  • $(VIESStatusCount) – Брой направени запитвания относно статуса на обекта в системата 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 низ, който може свободно да се анализира и обработва допълнително.

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

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