26 kwietnia 2017

Dodatek do MS Excel

Niniejszy rozdział zawiera instrukcje jak szybko i prosto zintegrować aplikację Microsoft Excel z systemem nip24.pl. Udostępniony dodatek (Add-In) został pomyślnie przetestowany w następujących wersjach MS Excel: 2007, 2010, 2013 oraz 2016. Dodatek można zainstalować zarówno w wersji Excel 32-bitowej jak i 64-bitowej.

Najnowsza wersja dodatku dostępna jest zawsze do pobrania ze strony Pobierz.

Pełną funkcjonalności dodatku do Excel można sprawdzić – bez konieczności zakładania konta – korzystając z udostępnionego Testowego API. Na stronie jest również opis jak należy skonfigurować dodatek do Excel w celu użycia w API udostępnionym do testów.

Korzystanie z dodatku w produkcyjnym API wymaga założenia konta w serwisie nip24.pl oraz wygenerowania klucza oraz jego identyfikatora. Proces rejestracji i zakładania konta oraz generowania kluczy został opisany na stronie Dokumentacja.

Instalacja

Uruchom aplikację MS Excel i przejdź do Plik > Opcje, a następnie zaznacz z menu Dodatki.

excel-vat-vies-gus-api-dodatek_2

Na dole ustawień należy wybrać Dodatki programu Excel i kliknąć przycisk Przejdź. W oknie Dodatki, należy kliknąć przycisk Przeglądaj, przejść do katalogu w którym został rozpakowany plik nip24-ms-excel-addin-1.2.4.zip i w wskazać:

  • nip24Excel.xll – dla 32-bitowej wersji Excel,
  • nip24Excel64.xll – dla 64-bitowej wersji Excel.

Poprawne załadowanie dodatku ilustruje rysunek poniżej. Wystarczy kliknąć przycisk OK, aby funkcje zaimplementowane w dodatku były dostępne w aplikacji Excel.

excel-vat-vies-gus-api-dodatek_3

Konfiguracja

Aby możliwe było wywoływanie funkcji, konieczne jest jednorazowe skonfigurowanie dostępu do serwisu nip24.pl. W tym celu należy przejść na dowolny arkusz aplikacji Excel i wykonać funkcję:

=NIP24.ZAPISZ.ID.KLUCZ("identyfikator";"klucz")

gdzie parametrami funkcji są:

  • identyfikator” – parametr powinien zawierać wygenerowany na koncie w serwisie nip24.pl identyfikator (ID),
  • klucz” – parametr powinien zawierać wygenerowany na koncie w serwisie nip24.pl klucz (Key).

Szczegóły dotyczące generowania identyfikatora oraz klucza opisane zostały na stronie Dokumentacja.

Po poprawnym wywołaniu funkcji powinien pojawić się komunikat SUKCES: Zapisano ustawienia:

excel-vat-vies-gus-api-dodatek_4

Następnie należy skonfigurować dostęp do produkcyjnego API, po przez wykonanie w dowolnej komórce funkcji:

=NIP24.ZAPISZ("URL";"https://www.nip24.pl/api")

Po poprawnym wywołaniu funkcji również zostanie wyświetlony komunikat SUKCES: Zapisano ustawienia

Domyślnie każdy dokument Excel ma ustawioną opcję automatycznego obliczania skoroszytu. Ustawienie tej opcji implikuje wywołanie wszystkich formuł w przypadku dokonania zmian wpływającej na daną formułę. Przykładem takiego działania jest usunięcie wiersza w arkuszu. Aby uniknąć automatycznego wywołania wszystkich funkcji zdefiniowanych w danym arkuszu, co wiąże się z automatycznym wysłaniem zapytań do API serwisu nip24.pl, należy zmienić opcję obliczania skoroszytu na Ręczny:

  1. z menu PLIK należy wybrać Opcje
  2. zaznaczyć zakładkę Formuły.
  3. w sekcji Opcje obliczania należy wybrać ustawienie: Ręcznie i odznaczyć opcję dodatkową: Oblicz ponownie skoroszyt przed zapisem.
  4. należy zapisać wprowadzone zmiany w arkuszu.

excel-sprawdzenie_podmiotu_vat-vies-ceidg-gus-regon-nip

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

CTRL + ALT + SHIFT + F9

Wykorzystanie

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

  • Wszystkie wywołania funkcji realizowane są w trybie asynchronicznym, co nie powoduje efektu zamrożenia (brak odpowiedzi) aplikacji Excel.
  • Dodanie (wstawienie) wiersza lub kolumny nie powoduje odświeżenia wszystkich zdefiniowanych wywołań funkcji.
  • Kopiowanie lub przenoszenie komórek zwierających funkcje nie powoduje odświeżenia zdefiniowanych wywołań funkcji.
  • Usunięcie wiersza lub kolumny powoduje odświeżenie wszystkich zdefiniowanych wywołań funkcji i wysłanie zapytań do serwisu nip24.pl (tylko w przypadku domyślnych ustawień Excel). Opis zmiany ustawień domyślnych został zawarty w rozdziale Konfiguracja.

Przykładowy plik Excel zawierający wszystkie opisane poniżej funkcje dołączony został do pliku ZIP zawierającego dodatek do Excel:

NIP24.CZY.AKTYWNA() – Funkcja weryfikuje i zwraca bieżący status działalności firmy. Jako parametry należy podać:

  • TYP numeru (NIP, KRS lub REGON),
  • numer zgodny ze wskazanym typem.
=NIP24.CZY.AKTYWNA("NIP";"7171642051")

NIP24.CZY.AKTYWNA.NIP() – Funkcja weryfikuje i zwraca bieżący status działalności firmy dla podanego numeru NIP. Jako parametry należy podać:

  • NUMER NIP.
=NIP24.CZY.AKTYWNA.NIP("7171642051")

NIP24.CZY.AKTYWNA.REGON() – Funkcja weryfikuje i zwraca bieżący status działalności firmy dla podanego numeru REGON. Jako parametry należy podać:

  • NUMER REGON.
=NIP24.CZY.AKTYWNA.REGON("141715362")

NIP24.CZY.AKTYWNA.KRS() – Funkcja weryfikuje i zwraca bieżący status działalności firmy dla podanego numeru KRS. Jako parametry należy podać:

  • NUMER KRS.
=NIP24.CZY.AKTYWNA.KRS("0000001280")

NIP24.DANE.FAKTURA() – Funkcja pobiera dane niezbędne do wystawienia faktury. Jako parametry należy podać:

  • TYP numeru (NIP, KRS lub REGON),
  • numer zgodny ze wskazanym typem,
  • (opcjonalnie) FORMAT zwracanych danych (patrz: Tagi możliwe do wykorzystania jako parametr FORMAT).
=NIP24.DANE.FAKTURA("NIP";"7171642051")

NIP24.DANE.FAKTURA.NIP() – Funkcja pobiera dane niezbędne do wystawienia faktury dla podanego numeru NIP. Jako parametry należy podać:

  • NUMER NIP,
  • (opcjonalnie) FORMAT zwracanych danych (patrz: Tagi możliwe do wykorzystania jako parametr FORMAT).
=NIP24.DANE.FAKTURA.NIP("7171645051";"$(Name)")

NIP24.DANE.FAKTURA.REGON() – Funkcja pobiera dane niezbędne do wystawienia faktury dla podanego numeru REGON. Jako parametry należy podać:

  • NUMER REGON,
  • (opcjonalnie) FORMAT zwracanych danych (patrz: Tagi możliwe do wykorzystania jako parametr FORMAT).
=NIP24.DANE.FAKTURA.REGON("141715362";"$(Name) - $(LastName) $(FirstName)")

NIP24.DANE.FAKTURA.KRS() – Funkcja pobiera dane niezbędne do wystawienia faktury dla podanego numeru KRS. Jako parametry należy podać:

  • NUMER KRS,
  • (opcjonalnie) FORMAT zwracanych danych (patrz: Tagi możliwe do wykorzystania jako parametr FORMAT),
=NIP24.DANE.FAKTURA.KRS("0000001280";"$(Name)")

Tagi dostępne w funkcjach pobierających dane niezbędne do wystawienia faktury,  możliwe do wykorzystania jako parametr FORMAT:

  • $(NIP) – Numer Identyfikacji Podatkowej podmiotu
  • $(Name) – Nazwa firmy
  • $(FirstName) – Imię właściciela
  • $(LastName) – Nazwisko właściciela
  • $(Street) – Ulica
  • $(StreetNumber) – Numer nieruchomości
  • $(HouseNumber) – Numer lokalu
  • $(PostCode) – Kod pocztowy
  • $(PostCity) – Poczta
  • $(City) – Miejscowość

Domyślny FORMAT: „$(Name), $(PostCode) $(City), $(Street) $(StreetNumber)/$(HouseNumber), NIP: $(NIP)”

NIP24.DANE.PEŁNE() – Funkcja pobiera wszystkie dostępne dane podmiotu. Jako parametry należy podać:

  • TYP numeru (NIP, KRS lub REGON),
  • numer zgodny ze wskazanym typem,
  • (opcjonalnie) FORMAT zwracanych danych (patrz: Tagi możliwe do wykorzystania jako parametr FORMAT).
=NIP24.DANE.PEŁNE("NIP";"7171642051")

NIP24.DANE.PEŁNE.NIP() – Funkcja pobiera wszystkie dostępne dane podmiotu dla podanego numeru NIP. Jako parametry należy podać:

  • NUMER NIP,
  • (opcjonalnie) FORMAT zwracanych danych (patrz: Tagi możliwe do wykorzystania jako parametr FORMAT).
=NIP24.DANE.PELNE.NIP("7171642051";"$(Name)")

NIP24.DANE.PEŁNE.REGON() – Funkcja pobiera wszystkie dostępne dane podmiotu dla podanego numeru REGON. Jako parametry należy podać:

  • NUMER REGON,
  • (opcjonalnie) FORMAT zwracanych danych (patrz: Tagi możliwe do wykorzystania jako parametr FORMAT).
=NIP24.DANE.PELNE.REGON("141715362";"$(Name) - $(LastName) $(FirstName)")

NIP24.DANE.PEŁNE.KRS() – Funkcja pobiera wszystkie dostępne dane podmiotu dla podanego numeru KRS. Jako parametry należy podać:

  • NUMER KRS,
  • (opcjonalnie) FORMAT zwracanych danych (patrz: Tagi możliwe do wykorzystania jako parametr FORMAT).
=NIP24.DANE.PELNE.KRS("0000001280";"$(Name)")

Tagi dostępne w funkcjach NIP24.DANE.PEŁNE możliwe do wykorzystania jako parametr FORMAT:

  • $(Type) – Typ podmiotu
  • $(NIP) – Numer Identyfikacji Podatkowej podmiotu
  • $(REGON) – Numer REGON
  • $(Name) – Nazwa firmy
  • $(ShortName) – Skrócona nazwa
  • $(FirstName) – Imię właściciela
  • $(LastName) – Nazwisko właściciela
  • $(SecondName) – Drugie imię właściciela
  • $(Street) – Ulica
  • $(StreetCode) – Kod TERYT ulicy
  • $(StreetNumber) – Numer nieruchomości
  • $(HouseNumber) – Numer lokalu
  • $(PostCode) – Kod pocztowy
  • $(PostCity) – Poczta
  • $(City) – Miejscowość
  • $(CityCode) – Kod TERYT miejscowości
  • $(Community) – Gmina
  • $(CommunityCode) – Kod TERYT gminy
  • $(County) – Powiat
  • $(CountyCode) – Kod TERYT powiatu
  • $(State) – Województwo
  • $(StateCode) – Kod TERYT województwa
  • $(CreationDate) – Data utworzenia firmy
  • $(StartDate) – Data rozpoczęcia działalności
  • $(RegistrationDate) – Data wpisu do rejestru
  • $(HoldDate) – Data wstrzymania działalności
  • $(RenevalDate) – Data wznowienia działalności
  • $(LastUpdateDate) – Data ostatniej aktualizacji danych
  • $(EndDate) – Data zakończenia działalności
  • $(RegistryEntityCode) – Kod organu rejestrującego
  • $(RegistryEntityName) – Nazwa organu rejestrującego
  • $(RegistryCode) – Kod rejestru lub ewidencji
  • $(RegistryName) – Nazwa rejestru lub ewidencji
  • $(RecordCreationDate) – Data utworzenia rekordu danych
  • $(RecordNumber)- Numer rejestrowy lub ewidencji
  • $(BasicLegalFormCode) – Kod podstawowej formy prawnej
  • $(BasicLegalFormName) – Nazwa podstawowej formy prawnej
  • $(SpecificLegalFormCode) – Kod szczególnej formy prawnej
  • $(SpecificLegalFormName) – Nazwa szczególnej formy prawnej
  • $(OwnershipFormCode) – Kod własności
  • $(OwnershipFormName) – Nazwa własności
  • $(PKD) – Lista PKD. Jako pierwsza zawsze jest wyświetlana działalność przeważająca
  • $(Phone) – Firmowy numer telefonu
  • $(Email) – Firmowy adres e-mail
  • $(WWW) – Firmowa strona WWW

Domyślny FORMAT: „$(Name), $(PostCode) $(City), $(Street) $(StreetNumber)/$(HouseNumber), NIP: $(NIP)”

NIP24.STATUS.VIES() – Funkcja pobiera wszystkie dostępne dane podmiotu bezpośrednio z systemu VIES. Jako parametry należy podać:

  • europejski numer NIP (VAT EU),
  • (opcjonalnie) FORMAT zwracanych danych (patrz: Tagi możliwe do wykorzystania jako parametr FORMAT).
=NIP24.STATUS.VIES(ZŁĄCZ.TEKSTY("PL";"7171642051"))

Tagi dostępne w funkcji NIP24.STATUS.VIES możliwe do wykorzystania jako parametr FORMAT:

  • $(UID) – Unikalny identyfikator wygenerowany przez Źródło danych
  • $(CountryCode) – Kod kraju
  • $(VATNumber) – Europejski numer NIP
  • $(Valid) – Status
  • $(TraderName) – Nazwa kontrahenta
  • $(TraderCompanyType) – Rodzaj działalności
  • $(TraderAddress) – Adres kontrahenta
  • $(ID) – Unikalny identyfikator wygenerowany przez system VIES
  • $(Date) – Data wygenerowania odpowiedzi
  • $(Source) – Źródło danych

Domyślny FORMAT: „$(Valid)”

NIP24.STATUS.VAT() – Funkcja zwraca status podmiotu w rejestrze VAT. Jako parametry należy podać:

  • TYP numeru (NIP, KRS lub REGON),
  • numer zgodny ze wskazanym typem,
  • (opcjonalnie) FORMAT zwracanych danych (patrz: Tagi możliwe do wykorzystania jako parametr FORMAT).
=NIP24.STATUS.VAT("NIP";"7171642051";"$(Status)")

NIP24.STATUS.VAT.NIP() – Funkcja zwraca status podmiotu w rejestrze VAT dla podanego numeru NIP. Jako parametry należy podać:

  • NUMER NIP,
  • (opcjonalnie) FORMAT zwracanych danych (patrz: Tagi możliwe do wykorzystania jako parametr FORMAT).
=NIP24.STATUS.VAT.NIP("7171642051")

NIP24.STATUS.VAT.REGON() – Funkcja zwraca status podmiotu w rejestrze VAT dla podanego numeru REGON. Jako parametry należy podać:

  • NUMER REGON,
  • (opcjonalnie) FORMAT zwracanych danych (patrz: Tagi możliwe do wykorzystania jako parametr FORMAT).
=NIP24.STATUS.VAT.REGON("141715362")

NIP24.STATUS.VAT.KRS() – Funkcja zwraca status podmiotu w rejestrze VAT dla podanego numeru KRS. Jako parametry należy podać:

  • NUMER KRS,
  • (opcjonalnie) FORMAT zwracanych danych (patrz: Tagi możliwe do wykorzystania jako parametr FORMAT).
=NIP24.STATUS.VAT.KRS("0000001280")

Tagi dostępne w funkcjach NIP24.STATUS.VAT możliwe do wykorzystania jako parametr FORMAT:

  • $(UID) – Unikalny identyfikator wygenerowany przez Źródło danych
  • $(Name) – Nazwa weryfikowanej firmy
  • $(NIP) – Numer NIP weryfikowanej firmy
  • $(REGON) – Numer REGON weryfikowanej firmy
  • $(Result) – Opisowy status podmiotu w VAT
  • $(Status) – Liczbowy status podmiotu w VAT
  • $(Date) – Data wygenerowania odpowiedzi
  • $(Source) – Źródło danych

Domyślny FORMAT: „$(Result)”

NIP24.KRS.NORMA() – Funkcja przekształca numer KRS do postaci znormalizowanej. Jako parametry należy podać: NUMER KRS

=NIP24.KRS.NORMA("1280")

NIP24.NIP.NORMA() – Funkcja przekształca numer NIP do postaci znormalizowanej. Jako parametry należy podać: NUMER NIP

=NIP24.NIP.NORMA("717-164-20-51")

NIP24.REGON.NORMA() – Funkcja przekształca numer REGON do postaci znormalizowanej. Jako parametry należy podać: NUMER REGON

=NIP24.REGON.NORMA("141715362")

NIP24.KRS.POPRAWNY() – Funkcja weryfikuje poprawność podanego numeru KRS. Jako parametry należy podać: NUMER KRS. Zwraca PRAWDA jeśli numer jest poprawny oraz FAŁSZ jeśli numer jest niepoprawny

=NIP24.KRS.POPRAWNY("0000001280")

NIP24.NIP.POPRAWNY() – Funkcja weryfikuje poprawność podanego numeru NIP. Jako parametry należy podać: NUMER NIP. Zwraca PRAWDA jeśli numer jest poprawny oraz FAŁSZ jeśli numer jest niepoprawny

=NIP24.NIP.POPRAWNY("717-164-20-52")

NIP24.REGON.POPRAWNY() – Funkcja weryfikuje poprawność podanego numeru REGON. Jako parametry należy podać: NUMER REGON. Zwraca PRAWDA jeśli numer jest poprawny oraz FAŁSZ jeśli numer jest niepoprawny

=NIP24.REGON.POPRAWNY("14171536200000")

Sprawdzenie statusu konta użytkownika w NIP24

NIP24.STATUS.KONTA() – Funkcja zwraca podstawowe informacje o aktualnie wykorzystywanym przez użytkownika planie. Jako parametry należy podać:

  • (opcjonalnie) FORMAT zwracanych danych (patrz: Tagi możliwe do wykorzystania jako parametr FORMAT),
=NIP24.STATUS.KONTA()

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

Tagi dostępne w funkcji NIP24.STATUS.KONTA możliwe do wykorzystania jako parametr FORMAT:

  • $(BillingPlanName)    –    Nazwa bieżącego planu taryfowego
  • $(SubscriptionPrice)    –    Cena netto abonamentu miesięcznego
  • $(ItemPrice)    –    Koszt netto pojedynczego zapytania poza planem w planie standardowym
  • $(ItemPriceStatus)    –    Koszt netto pojedynczego zapytania – VAT/VIES/Status działalności podmiotu w planie indywidualnym
  • $(ItemPriceInvoice)    –    Koszt netto pojedynczego zapytania – dane do faktury w planie indywidualnym
  • $(ItemPriceAll)    –    Koszt netto pojedynczego zapytania – pełne dane podmiotu w planie indywidualnym
  • $(Limit)    –     Maksymalna liczba zapytań w planie
  • $(RequestDelay)    –    Minimalny odstęp czasu między zapytaniami
  • $(DomainLimit)    –    Maksymalna ilość domen (kluczy API)
  • $(OverPlanAllowed)    –    Możliwość przekroczenia maksymalnej liczby zapytań w planie
  • $(TerytCodes)    –    Dostęp do kodów TERYT
  • $(ExcelAddIn)    –    Dostęp z wykorzystaniem dodatku MS Excel
  • $(Stats)    –    Dostęp do statystyk wykonanych zapytań
  • $(NIPMonitor)    –    Dostęp do monitorowania statusów podmiotów: VAT/VIES/Status działalności
  • $(SearchByNIP)    –    Wyszukiwanie po numerze NIP
  • $(SearchByREGON)    –    Wyszukiwanie po numerze REGON
  • $(SearchByKRS)    –    Wyszukiwanie po numerze KRS
  • $(FuncIsActive)    –    Dostęp do funkcji sprawdzających status działalności podmiotu
  • $(FuncGetInvoiceData)    –    Dostęp do funkcji pobierających dane podmiotu do faktury
  • $(FuncGetAllData)    –    Dostęp do funkcji pobierających pełne dane podmiotu
  • $(FuncGetVIESData)    –    Dostęp do funkcji sprawdzających status podmiotu w systemie VIES
  • $(FuncGetVATStatus)    –    Dostęp do funkcji sprawdzających status podmiotu w rejestrze VAT
  • $(InvoiceDataCount)    –    Ilość wykonanych zapytań o dane podmiotu do faktury
  • $(AllDataCount)    –    Ilość wykonanych zapytań o pełne dane podmiotu
  • $(FirmStatusCount)    –    Ilość wykonanych zapytań o status działalności podmiotu
  • $(VATStatusCount)    –    Ilość wykonanych zapytań o status podmiotu w rejestrze VAT
  • $(VIESStatusCount)    –    Ilość wykonanych zapytań o status podmiotu w systemie VIES
  • $(TotalCount)    –    Całkowita ilość wykonanych zapytań w bieżącym miesiącu

Domyślny FORMAT: „Nazwa bieżącego planu taryfowego: $(BillingPlanName), Cena netto abonamentu miesięcznego: $(SubscriptionPrice), Maksymalna liczba zapytań w planie: $(Limit), Całkowita ilość wykonanych zapytań w bieżącym miesiącu: $(TotalCount)”

Maksymalna liczba zapytań w planie

NIP24.STATUS.KONTA.LIMIT() – Funkcja zwraca informację o maksymalnej liczbie zapytań dostępnej w wybranym przez użytkownika planie. Zwraca dokładnie taką samą liczbę, jak tag $(Limit) w funkcji NIP24.STATUS.KONTA().

=NIP24.STATUS.KONTA.LIMIT()

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

Pobranie liczby wszystkich wykonanych w bieżącym miesiącu zapytań

NIP24.STATUS.KONTA.LICZBA.ZAPYTAŃ() – Funkcja zwraca informację o maksymalnej liczbie zapytań dostępnej w wybranym przez użytkownika planie. Zwraca dokładnie taką samą liczbę, jak tag $(TotalCount) w funkcji NIP24.STATUS.KONTA().

=NIP24.STATUS.KONTA.LICZBA.ZAPYTAŃ()

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