Dodatek Google Sheets™ Walidator VIES

Dodatek Google Sheets™ Walidator VIES

interfejs API arkuszy GoogleDodatek Google Sheets™ umożliwia szybkie i automatyczne sprawdzanie jednostek (kontrahentów) korzystających z arkusza kalkulacyjnego Google Sheets™ pod kątem ich bieżącego statusu w System VIES.

Niniejsza dokumentacja zawiera instrukcje dotyczące integracji aplikacji Arkusze Google™ z systemem API VIES.

 

 

Instalacja i konfiguracja

Instalacja

Po wejściu na stronę internetową Google Workspace Marketplace https://workspace.google.com/marketplace/app/vies_api_eu_vat_validation/1043052728267, Kliknij Install przycisk.

instalacja dodatku Vies API Arkuszy Google

Wybór konta Google, dla którego ma zostać zainstalowany i udostępniony dodatek VIES Validator Google Sheets:

vies api dodatek google sheet zainstaluj konto

Na następnym ekranie możesz przeczytać Polityka prywatności i obowiązujące Warunki usługi, a także zakres Twoich danych, które będziemy przetwarzać. Aby przejść do kolejnego kroku instalacji, naciśnij przycisk Continue przycisk.

uprawnienia instalacji dodatku Vies API Arkuszy Google

Potwierdź, że udzieliłeś niezbędnych uprawnień, aby dodatek działał prawidłowo i naciśnij przycisk Allow przycisk:

instalacja dodatku Vies API Arkusze Google uprawnienia zezwalają

Dodatek VIES Validation został pomyślnie zainstalowany na Twoim koncie i będzie dostępny po uruchomieniu Arkuszy Google na karcie Rozszerzenia. Aby kontynuować, kliknij Next:

Vies API Arkusze Google dodatek instalacyjny rozszerzenie

Na ostatnim ekranie instalatora pojawi się monit o skonfigurowanie dodatku. Kliknięcie „Complete additional setup nowLink „ otworzy nowe okno przeglądarki z aktualną stroną dokumentacji. Kliknij Done Kliknij przycisk i rozpocznij konfigurację dodatku zgodnie z opisem w sekcji Konfiguracja.

dodatek Vies API do Arkuszy Google zainstalowany

Konfiguracja

Po instalacji wtyczka jest domyślnie ustawiona na środowisko testowe (więcej szczegółów na Testuj API Aby móc wywoływać funkcje w środowisku produkcyjnym, należy jednorazowo skonfigurować dostęp do witryny viesapi.eu. W tym celu należy przejść do dowolnego arkusza kalkulacyjnego Google Sheets™ i wykonać następującą funkcję:

=VIESAPI_CONNECT_PRODUCTION("identifier";"key")

gdzie parametry funkcji to:

  • identifier – parametr powinien zawierać identyfikator (ID) wygenerowany na koncie w serwisie viesapi.eu,
  • key – parametr powinien zawierać Klucz wygenerowany na koncie w serwisie viesapi.eu.

Szczegóły dotyczące generowania identyfikatora i klucza opisane są na Dokumentacja stronie internetowej.

W celu weryfikacji poprawności połączenia z danym API (testowym lub produkcyjnym) należy wykonać następującą funkcję:

=VIESAPI_CONNECT_STATUS()

Które mogą zwracać wartości:

  • SUCCESS: Production – czy dodatek jest poprawnie skonfigurowany do pracy ze środowiskiem produkcyjnym,
  • SUCCESS: Test – czy dodatek jest poprawnie skonfigurowany do pracy z Środowisko testowe,
  • ERROR: Connection requires configuration – w przypadku złej konfiguracji.

Jeśli wolisz konfigurację paska bocznego, kliknij Extensions kartę, a następnie wybierz VIES API - EU VAT Validation i na koniec kliknij Show sidebar aby włączyć pasek boczny:

pasek boczny konfiguracji dodatku Vies API Arkuszy Google

Następnie przejdź do ID and Key zakładkę, aby wejść ID oraz Key w odpowiednich polach tekstowych, które są dostępne po zalogowaniu się na konto API VIES: https://viesapi.eu/sign-in/

Identyfikator i klucz konfiguracji dodatku Vies API Arkuszy Google

Stosowanie

Przed skorzystaniem z dodatku należy zapoznać się ze specyfiką jego działania:

  • Wszystkie wywołania funkcji są wykonywane w trybie asynchronicznym, co nie powoduje efektu zawieszania się (braku odpowiedzi) aplikacji Arkusze Google™.
  • Dodanie (wstawienie) wiersza lub kolumny nie odświeża wszystkich zdefiniowanych wywołań funkcji.
  • Kopiowanie lub przenoszenie komórek zawierających funkcje nie odświeża zdefiniowanych wywołań funkcji.
  • Usunięcie wiersza lub kolumny spowoduje odświeżenie wszystkich zdefiniowanych wywołań funkcji i wysłanie zapytań do viesApi.eu (tylko w przypadku domyślnych ustawień Arkuszy Google™). Opis zmiany ustawień domyślnych znajduje się w rozdziale „Konfiguracja”.
  • Uwaga! Nie zaleca się uruchamiania więcej niż 500 równoległych zapytań, ponieważ Arkusze Google™ mają problemy z obsługą dużej liczby wywołań asynchronicznych.

Uzyskaj dane firmy z VIES

VIESAPI_VIES_DATA() – Funkcja pobiera wszystkie dostępne dane firmy bezpośrednio z systemu VIES. Parametry powinny być:

  • europejski numer identyfikacji podatkowej (VAT EU),
  • (opcjonalny) FORMAT zwróconych danych (patrz: Tagi, które mogą być użyte jako FORMAT parametr).

=VIESAPI_VIES_DATA("PL7171642051")

Jeśli potrzebujesz tylko statusu firmy w VIES, użyj następującego zapytania:

=VIESAPI_VIES_DATA("PL7171642051";"$(Valid)")

Jeśli zwrócony status to Tak, oznacza to, że firma posiada ważny numer VAT UE.

Tagi dostępne w VIESAPI_VIES_DATA funkcja, która może być używana jako FORMAT parametr:

  • $(UID) – unikalny identyfikator wygenerowany przez usługę viesApi.eu
  • $(CountryCode) – kod kraju
  • $(VATNumber) – europejski numer VAT
  • $(Valid) – odpowiedź z serwisu VIES informująca o aktualnym statusie VAT UE sprawdzanej firmy (Yes/No)
  • $(TraderName) – nazwa rejestracyjna firmy
  • $(TraderCompanyType) – rodzaj działalności gospodarczej
  • $(TraderAddress) – adres przedsiębiorcy, pod którym zarejestrowana jest firma
  • $(ID) – unikalny identyfikator generowany przez system VIES (numer konsultacji)
  • $(Date) – data wygenerowania odpowiedzi
  • $(Source) – źródło danych

Format domyślny: "$(TraderName), $(TraderAddress)"

Jeśli ciąg "JSON" jest podany jako FORMAT funkcja zwróci pełny wynik w postaci ciągu JSON, który można dowolnie parsować i przetwarzać dalej:

=VIESAPI_VIES_DATA("PL7171642051";"JSON")

Pobierz przeanalizowane dane firmy z VIES

VIESAPI_VIES_DATA_PARSED() – Funkcja pobiera wszystkie dostępne dane firmy bezpośrednio z systemu VIES. Dodatkowo nazwa i adres firmy są zwracane jako dane parsowane, podzielone na osobne atrybuty. Parametry powinny być następujące:

  • europejski numer identyfikacji podatkowej (VAT EU),
  • (opcjonalny) FORMAT zwróconych danych (patrz: Tagi, które mogą być użyte jako FORMAT parametr).

=VIESAPI_VIES_DATA_PARSED("PL7171642051")

Jeśli potrzebujesz tylko statusu firmy w VIES, użyj następującego zapytania:

=VIESAPI_VIES_DATA_PARSED("PL7171642051";"$(Valid)")

Jeśli zwrócony status to Tak, oznacza to, że firma posiada ważny numer VAT UE.

Tagi dostępne w VIESAPI_VIES_DATA_PARSED funkcja, która może być używana jako FORMAT parametr:

  • $(UID) – unikalny identyfikator wygenerowany przez usługę viesApi.eu
  • $(CountryCode) – kod kraju
  • $(VATNumber) – europejski numer VAT
  • $(Valid) – odpowiedź z serwisu VIES informująca o aktualnym statusie VAT UE sprawdzanej firmy (Yes/No)
  • $(TraderName) – nazwa rejestracyjna firmy
  • $(TraderNameComponents.Name) – nazwa firmy od traderName (bez formy prawnej)
  • $(TraderNameComponents.LegalForm) – nazwa formy prawnej wyodrębniona z tradeName (bez nazwy firmy)
  • $(TraderNameComponents.LegalFormCanonicalId) – identyfikator słownikowy formy prawnej
  • $(TraderNameComponents.LegalFormCanonicalName) – słownikowa nazwa formy prawnej
  • $(TraderCompanyType) – rodzaj działalności gospodarczej
  • $(TraderAddress) – adres przedsiębiorcy, pod którym zarejestrowana jest firma
  • $(TraderAddressComponents.Country) – nazwa kraju przedsiębiorcy w jego języku ojczystym
  • $(TraderAddressComponents.PostalCode) – kod pocztowy adresu przedsiębiorcy
  • $(TraderAddressComponents.City) – miasto adresu przedsiębiorcy
  • $(TraderAddressComponents.Street) – ulica adresu sprzedawcy
  • $(TraderAddressComponents.StreetNumber) – numer budynku przy ulicy, na której znajduje się adres przedsiębiorcy
  • $(TraderAddressComponents.HouseNumber) – numer mieszkania/biura pod adresem przedsiębiorcy
  • $(TraderAddressComponents.Other) – inne dane adresowe (nazwa obszaru, nazwa budynku, numer piętra itp.)
  • $(ID) – unikalny identyfikator generowany przez system VIES (numer konsultacji)
  • $(Date) – data wygenerowania odpowiedzi
  • $(Source) – źródło danych

Format domyślny: "$(TraderName), $(TraderAddress)"

Jeśli ciąg "JSON" jest podany jako FORMAT funkcja zwróci pełny wynik w postaci ciągu JSON, który można dowolnie parsować i przetwarzać dalej:

=VIESAPI_VIES_DATA_PARSED("PL7171642051";"JSON")

Sprawdzanie statusu konta użytkownika (bezpłatnie)

VIESAPI_ACCOUNT_STATUS() – Funkcja zwraca podstawowe informacje o aktualnie używanym przez użytkownika planie. Parametry powinny być:

  • (opcjonalny) FORMAT zwróconych danych (patrz: Tagi, które mogą być użyte jako FORMAT parametr)

=VIESAPI_ACCOUNT_STATUS()

Uwaga! Wywołanie funkcji nie zwiększa liczby wykonywanych zapytań.

Tagi dostępne w VIESAPI_ACCOUNT_STATUS funkcja może być używana jako FORMAT parametr:

  • $(UID) – unikalny identyfikator wygenerowany przez usługę viesApi.eu
  • $(BillingPlanName) – nazwa aktualnego planu
  • $(SubscriptionPrice) – miesięczna opłata abonamentowa
  • $(ItemPrice) – koszt pojedynczego zapytania poza planem
  • $(ItemPriceStatus) – koszt zapytania – VAT/VIES/status aktywności firmy
  • $(ItemPriceParsed) – koszt zapytania – VAT/VIES/status aktywności firmy z przeanalizowanymi danymi
  • $(Limit) – maksymalna liczba zapytań w planie
  • $(RequestDelay) – minimalny odstęp czasu między zapytaniami
  • $(DomainLimit) – maksymalna liczba domen (kluczy API)
  • $(OverPlanAllowed) – możliwość przekroczenia maksymalnej liczby zapytań w planie
  • $(ExcelAddIn) – dostęp do dodatku Google Sheets™ i Microsoft Excel™
  • $(Stats) – dostęp do statystyk zapytań
  • $(NIPMonitor) – dostęp do monitoringu statusu firm: VAT/VIES/Status działalności
  • $(FuncGetVIESData) – dostęp do funkcji weryfikujących status firmy w systemie VIES
  • $(FuncGetVIESDataParsed) – dostęp do funkcji weryfikujących status firmy w systemie VIES oraz analizujących nazwę i adres przedsiębiorcy
  • $(VIESDataCount) – liczba zapytań VIES wykonanych w tym miesiącu
  • $(VIESDataParsedCount) – liczba zapytań VIES z przeanalizowanymi danymi wykonanych w tym miesiącu
  • $(TotalCount) – całkowita liczba zapytań wykonanych w tym miesiącu

Domyślny FORMAT: "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)"

Jeśli ciąg "JSON" jest podany jako FORMAT funkcja zwróci pełny wynik w postaci ciągu JSON, który można dowolnie parsować i dalej przetwarzać.

Sprawdzenie statusu systemu VIES (bezpłatne)

VIESAPI_VIES_STATUS() – Ta funkcja umożliwia sprawdzenie aktualnego statusu systemu VIES. Zwraca ona ogólny status wskazujący dostępność, a także listę poszczególnych krajów członkowskich wraz z aktualnym statusem dostępności ich systemów krajowych. Parametry powinny być następujące:

  • (opcjonalny) FORMAT zwróconych danych (patrz: Tagi, które mogą być użyte jako FORMAT parametr)

=VIESAPI_VIES_STATUS()

Uwaga! Wywołanie funkcji nie zwiększa liczby wykonywanych zapytań.

Tagi dostępne w VIESAPI_VIES_STATUS funkcja może być używana jako FORMAT parametr:

  • $(UID) – unikalny identyfikator wygenerowany przez usługę viesApi.eu
  • $(Available) – aktualna dostępność systemu VIES (Dostępny, Częściowo dostępny, Niedostępny)
  • $(Countries) – lista poszczególnych państw członkowskich (Dostępne, Niedostępne)
  • $(AT), $(FR), $(PL), etc. – status dostępności konkretnego kraju członkowskiego (jako wartość tagu użyj 2-literowego kodu kraju złożonego z wielkich liter)

Domyślny FORMAT: "$(Available)"

Jeśli ciąg "JSON" jest podany jako FORMAT funkcja zwróci pełny wynik w postaci ciągu JSON, który można dowolnie parsować i dalej przetwarzać.

Inne przydatne funkcje (bezpłatnie)

VIESAPI_ACCOUNT_STATUS_TOTAL() – Funkcja zwraca informacje o łącznej liczbie zapytań wykonanych w bieżącym miesiącu rozliczeniowym dla danego rachunku (wszystkie klucze API). Zwraca dokładnie taką samą liczbę jak $(TotalCount) tag w VIESAPI_STATUS_ACCOUNT() funkcjonować.

VIESAPI_ACCOUNT_STATUS_LIMIT() – Funkcja zwraca informację o maksymalnej liczbie zapytań dostępnych w wybranym przez użytkownika planie. Zwraca dokładnie taką samą liczbę jak $(Limit) tag w VIES.STATUS.ACCOUNT() funkcjonować

VIESAPI_EUVAT_NORM() – Ta funkcja koryguje i formatuje numer VAT UE (usuwa spacje, łączniki itp.) w trybie offline i nie pobiera żadnych danych z VIES:

=VIESAPI_EUVAT_NORM("PL 717-164-20-51")

VIESAPI_EUVAT_VALID() – Funkcja sprawdza tylko poprawność (składnia, suma kontrolna) numeru VAT UE w trybie offline i nie pobiera żadnych danych z systemu VIES. Zwroty TRUE jeśli numer jest ważny lub FALSE jeśli nie jest ważny:

=VIESAPI_EUVAT_VALID("PL7171642051")

VIESAPI_CONNECTION_STATE() – Funkcja zwraca aktualny stan konfiguracji dodatku.

Jeżeli funkcja zwraca następującą wartość, oznacza to m.in., że ID oraz API key nie zostały zapisane:

ERROR: Connection requires configuration

Po zapisaniu API ID oraz key, funkcja powinna zwrócić następujący komunikat:

SUCCESS: Production

Arkusze Google™ są znakiem towarowym firmy Google LLC.