Надбудова VIES Validator для Excel

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