Dodatek Excel umożliwia szybkie i automatyczne sprawdzenie podmiotów (kontrahentów) za pomocą arkusza kalkulacyjnego Excel pod kątem ich aktualnego statusu w System VIES.

Ten rozdział zawiera instrukcje dotyczące integracji aplikacji Microsoft Excel z systemem API VIES. Dołączony dodatek został pomyślnie przetestowany w następujących wersjach programu MS Excel: 2007, 2010, 2013, 2016, 2019 (w systemach operacyjnych Windows i macOS) i 2021 (w systemach operacyjnych Windows i macOS) oraz w wersji internetowej Excel365.

Najnowsza wersja dodatku do programu Excel 2007, 2010, 2013, 2016 i 2019 jest zawsze dostępna do pobrania ze strony Pobierz stronę. Dodatek można zainstalować zarówno w 32-bitowej, jak i 64-bitowej wersji programu Excel. Uwaga! Wybierz wersję (32- lub 64-bitową), która pasuje do wersji Excela, a nie system operacyjny.

Aby pobrać i zainstalować dodatek dla MacOS i Excel 2021 dla Windows i Excel365, odwiedź oficjalny sklep Microsoft: https://appsource.microsoft.com.

Pełną funkcjonalność dodatku Excel można sprawdzić – bez konieczności zakładania konta – korzystając z udostępnionej Testuj API. Na stronie opisano również, jak skonfigurować dodatek programu Excel do użycia w interfejsie API udostępnionym do testowania.

Korzystanie z dodatku w produkcyjnym API wymaga założenia konta w serwisie viesapi.eu, zakupu minimum Biznesplanu oraz wygenerowania klucza i jego identyfikatora. Proces rejestracji i zakładania konta oraz generowania kluczy został opisany na Dokumentacja stronie internetowej.

Instalacja i konfiguracja dla MS Excel 2021 i Excel 365 z Microsoft Store (Źródło aplikacji)

Instalacja

Po wejściu na stronę Microsoft Official Store https://appsource.microsoft.com, Kliknij Get it now przycisk.

Wyświetli się okno logowania, w którym należy podać adres e-mail, dla którego utworzyłeś konto w Microsoft (prywatne lub firmowe). Jeśli nie posiadasz takiego konta, możesz je założyć i kontynuować proces instalacji lub zatrzymać instalację i skorzystać z opcji instalacji dodatku w jeden z opisanych powyżej sposobów.

Aby pobrać i zainstalować dodatek z programu Excel 2021 lub Excel 365 (internet), przejdź do Insert [1], znajdź sekcję Dodatki i kliknij OfficeAdd-ins [2] przycisk. Następnie w otwartym oknie wpisz słowo 'viesapi ′ [3] w polu wyszukiwania i naciśnij ikonę lupy. Dodatek o nazwie „VIES API - EU VAT Validation” powinien zostać znaleziony, który należy zainstalować, klikając Add przycisk [4]. Wszystkie powyższe kroki są zilustrowane na poniższym zrzucie ekranu:

Po kliknięciu Add powinien pojawić się ekran, na którym można przeczytać warunki licencji i zasady ochrony prywatności.

Aby rozpocząć instalację dodatku, naciśnij Continue przycisk.

Konfiguracja

Po poprawnym zainstalowaniu wtyczki powinien pojawić się ekran podobny do przedstawionego poniżej. w Home menu [1], znajdź ikonę reprezentującą VIES API Panel [2] i kliknij, aby wyświetlić panel boczny. Zaraz po instalacji dodatek jest konfigurowany do pracy w środowisku testowym – szczegóły na Testuj stronę API. Korzystanie z dodatku w trybie testowym nie wymaga zakładania konta w serwisie viesapi.eu stronie internetowej.

Aby przełączyć dodatek do środowiska produkcyjnego, kliknij ID and key [3] zakładkę i wprowadź Key i klucz ID, które można znaleźć po zalogowaniu się do swojego konta na stronie viesapi.eu w zakładce „API Keys” zakładka. Po wprowadzeniu obu wartości, naciśnij Save przycisk.

Jeśli nie masz jeszcze konta na naszej stronie, kliknij link pod adresem viesapi.eu [4] i przejść przez proces rejestracji, który jest szczegółowo opisany na Dokumentacja strona.

Instalacja i konfiguracja dla Excela: 2007, 2010, 2013, 2016 i 2019

Instalacja

Pobierz najnowszą wersję dodatku do programu Excel 2007, 2010, 2013, 2016 i 2019 z witryny Pobierz stronę. Uruchom MS Excel i przejdź do File> Options, a następnie wybierz Add-ins [1] z menu.

U dołu ustawień wybierz Excel Add-ins [2] i kliknij Go [3] przycisk.

Zaawansowani użytkownicy mogą dodać dodatek z Developer tab [1], a następnie kliknij Excel Add-ins [2] i kliknij Browse [3] przycisk:

w Add-ins w oknie, kliknij Browse przycisk, przejdź do katalogu, w którym viesapi-ms-excel-addin-version-number.zip plik został rozpakowany i wybierz:

• viesapiExcel.xll – dla 32-bitowej wersji Excela,
• viesapiExcel64.xll – dla 64-bitowej wersji programu Excel.

Prawidłowe ładowanie dodatku pokazano na poniższym rysunku [1].

Wystarczy kliknąć OK przycisk [2], aby udostępnić w Excelu funkcje zaimplementowane w dodatku.

Konfiguracja

Po instalacji wtyczka jest domyślnie ustawiona na środowisko testowe (więcej szczegółów na Testuj API strona). Aby móc wywoływać funkcje w środowisku produkcyjnym, konieczne jest jednorazowe skonfigurowanie dostępu do serwisu viesapi.eu. Aby to zrobić, przejdź do dowolnego arkusza kalkulacyjnego Excel i wykonaj 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.

Domyślnie każdy dokument programu Excel jest ustawiony na automatyczne obliczanie arkusza kalkulacyjnego. Ustawienie tej opcji oznacza, że wszystkie formuły są wywoływane po wprowadzeniu zmian mających wpływ na formułę. Przykładem tego jest usunięcie wiersza w arkuszu.

Aby uniknąć automatycznego wywoływania wszystkich funkcji zdefiniowanych w danym arkuszu, co wiąże się z automatycznym wysyłaniem zapytań do API serwisu veisapi.eu, zmień opcję kalkulacji skoroszytu na Ręcznie:

1. Od File menu, Wybierz Options
2. Podkreśl Formulas patka
3. W sekcji Opcje obliczeń wybierz ustawienie: Manual oraz odznacz dodatkowa opcja: Recalculate the workbook before saving.
4. Konieczne jest zapisanie zmian dokonanych w arkuszu.

Przy tak skonfigurowanym arkuszu Excel, aby wymusić odświeżenie wszystkich zdefiniowanych formuł należy nacisnąć kombinację klawiszy:

CTRL + ALT + SHIFT + F9

Zaktualizuj wtyczkę do najnowszej wersji

Uwaga!Poniższa procedura aktualizacji dodatku do programu Excel działa prawidłowo w wersjach programu MS Excel 2019, 2021 i Excel 365, w których dodatek można zainstalować ze sklepu Microsoft Store.

Uwaga! Po zainstalowaniu najnowszej wersji należy ponownie skonfigurować dodatek, tj. wprowadzić i zapisać identyfikator i klucz.

Aby zainstalować najnowszą wersję dodatku do programu Excel, wykonaj następujące czynności:

1. Sprawdź wersję zainstalowanego dodatku, wywołując formułę =VIESAPI.VERSION()Najnowsza wersja dodatku to 1.2.8

2. Wyczyść pamięć podręczną programu MS Excel zgodnie z procedurą opisaną na oficjalnej stronie dokumentacji: https://learn.microsoft.com/en-us/office/dev/add-ins/testing/clear-cache

3. Po wykonaniu wszystkich czynności z punktu 2 uruchom ponownie aplikację MS Excel.

4. Podczas ponownego uruchamiania aplikacja MS Excel pobierze najnowszą wersję dodatku ze sklepu Microsoft Store.

5. Skonfiguruj dodatek, wpisując identyfikator i klucz pobrany po zalogowaniu się na nasze konto strona internetowa – Karta „Klucze API”.

Stosowanie

Zobacz, jak automatycznie i masowo weryfikować status VAT UE firm w systemie VIES za pomocą naszego dodatku do Excela:

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 zamrożenia (braku odpowiedzi) aplikacji Excel.
• 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ń Excela). Opis zmiany ustawień domyślnych znajduje się w rozdziale Konfiguracja.
• Uwaga! Nie zaleca się uruchamiania więcej niż 500 zapytań równoległych, ponieważ program Excel ma 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 MS 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