Доповнення Google Sheets™, валідатор VIES

Доповнення Google Sheets™, валідатор VIES

API VIE у Google ТаблицяхДоповнення Google Sheets™ дозволяє швидко та автоматично перевіряти поточний статус суб'єктів господарювання (підрядників) за допомогою електронної таблиці Google Sheets™. Система VIES.

Ця документація містить інструкції щодо інтеграції програми Google Sheets™ із системою VIES API.

 

 

Встановлення та налаштування

монтаж

Після входу на веб-сайт Google Workspace Marketplace https://workspace.google.com/marketplace/app/vies_api_eu_vat_validation/1043052728267, натисніть Install кнопку.

Встановлення доповнення vies api google sheets

Вибір облікового запису Google, для якого має бути встановлено та доступне доповнення VIES Validator для Google Таблиць:

встановлення облікового запису доповнення vies api google sheets

На наступному екрані ви можете прочитати Політика конфіденційності та застосовні Умови обслуговування, а також обсяг ваших даних, які ми оброблятимемо. Щоб перейти до наступного кроку встановлення, натисніть Continue кнопку.

дозволи на встановлення доповнення vies api google sheets

Переконайтеся, що ви надали необхідні дозволи для належної роботи доповнення, і натисніть Allow кнопка:

дозволи на встановлення доповнення vies api google sheets

Доповнення VIES Validation успішно встановлено у вашому обліковому записі та буде доступне після запуску Google Таблиць на вкладці Розширення. Щоб продовжити, натисніть Next:

розширення для встановлення доповнення VIE API Google Таблиць

На останньому екрані інсталятора вам буде запропоновано налаштувати доповнення. Натискання кнопки «Complete additional setup now«посилання» відкриє нове вікно браузера з поточною сторінкою документації. Натисніть Done кнопку та почніть налаштування доповнення, як описано в розділі «Налаштування».

Встановлено доповнення vies api google sheets

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

Після інсталяції плагін за замовчуванням налаштований на тестове середовище (докладніше див Тестовий API сторінка). Щоб мати змогу викликати функції у робочому середовищі, необхідно один раз налаштувати доступ до веб-сайту viesapi.eu. Для цього перейдіть до будь-якої електронної таблиці Google Sheets™ та виконайте функцію:

=VIESAPI_CONNECT_PRODUCTION("identifier";"key")

де параметри функції:

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

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

Щоб перевірити правильність з’єднання з заданим API (тестовим чи робочим), слід виконати наступну функцію:

=VIESAPI_CONNECT_STATUS()

Який може повертати значення:

  • SUCCESS: Production – якщо надбудову правильно налаштовано для роботи з робочим середовищем,
  • SUCCESS: Test – якщо надбудову правильно налаштовано для роботи з тестове середовище,
  • ERROR: Connection requires configuration – у разі неправильної конфігурації.

Якщо ви надаєте перевагу конфігурації бічної панелі, натисніть кнопку Extensions вкладку, а потім виберіть VIES API - EU VAT Validation і нарешті натисніть Show sidebar щоб увімкнути бічну панель:

Бічна панель налаштувань доповнення vies api google sheets

Тоді перейдіть до ID and Key вкладка для входу ID і Key у відповідних текстових полях, які доступні після входу до вашого облікового запису VIES API: https://viesapi.eu/sign-in/

Ідентифікатор та ключ конфігурації доповнення vies api google sheets

Використання

Перед використанням доповнення необхідно ознайомитися з особливостями його роботи:

  • Усі виклики функцій виконуються в асинхронному режимі, що не викликає ефекту зависання (відсутності відповіді) програми Google Sheets™.
  • Додавання (вставлення) рядка чи стовпця не оновлює всі визначені виклики функцій.
  • Копіювання або переміщення клітинок, які містять функції, не оновлює визначені виклики функцій.
  • Видалення рядка або стовпця призведе до оновлення всіх визначених викликів функцій та надсилання запитів до viesApi.eu (лише у випадку налаштувань Google Sheets™ за замовчуванням). Опис зміни налаштувань за замовчуванням міститься в розділі «Конфігурація».
  • Увага! Не рекомендується виконувати більше 500 паралельних запитів, оскільки Google Sheets™ має проблеми з обробкою великої кількості асинхронних викликів.

Отримайте дані компанії з 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) – доступ до надбудови Google Таблиць™ та Microsoft 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

Google Таблиці™ є торговою маркою Google LLC.