Надбудова 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 Official Store 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. Налаштуйте надбудову, ввівши ідентифікатор і ключ, завантажені після входу в обліковий запис на нашому веб-сайт – Вкладка «Ключі 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