Добавка за 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 Sheets трябва да бъде инсталирана и достъпна:

инсталиране на добавка за Google Sheets на VIE API

На следващия екран можете да прочетете Политика за поверителност и приложимите Условия за ползване, както и обхвата на вашите данни, които ще обработваме. За да продължите към следващата стъпка от инсталацията, натиснете бутона Continue бутон.

Разрешения за инсталиране на добавката vies api google sheets

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

Разрешения за инсталиране на добавка vies api google sheets

Добавката VIES Validation е инсталирана успешно във вашия акаунт и ще бъде достъпна след стартиране на Google Sheets в раздела „Разширения“. За да продължите, моля, кликнете Next:

Разширение за инсталиране на добавка VIE API за Google Sheets

Последният екран на инсталатора ще ви подкани да конфигурирате добавката. Щракването върху „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 Sheets™ и 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 Sheets™ е търговска марка на Google LLC.