20 września 2015

Dokumentacja

Wprowadzenie

System nip24.pl udostępnia wybrane dane przedsiębiorców z wykorzystaniem m.in. usług sieciowych oraz bibliotek programistycznych i dedykowanych pluginów dla sklepów e-commerce. Dzięki udostępnionemu oprogramowaniu (biblioteki oraz pluginy i wtyczki) Państwa klienci w najszybszy z możliwych sposobów będą mogli wypełnić formularz z danymi do faktury, pobierać dane szczegółowe firmy, aktualizować dane adresowe i kontaktowe, pobierać informacje o kontrahencie z systemu VIES oraz sprawdzać kontrahenta w rejestrze VAT.

Niniejszy dokument szczegółowo opisuje jakie czynności należy wykonać, aby dokonać poprawnej integracji z systemem nip24.pl.


UWAGA! Pełną funkcjonalności wszystkich udostępnionych bibliotek można sprawdzić korzystając z udostępnionego Testowego API. Dzięki API testowemu możliwe jest sprawdzenie wszystkich funkcji oferowanych w planach płatnych bez konieczności zakładania konta.


Opisane poniżej kroki należy wykonać w celu uzyskania dostępu do produkcyjnego interfejsu API.

Pierwszym etapem jest zarejestrowanie się w systemie i utworzenie konta, dzięki któremu możliwe będzie pobranie oprogramowania i dalsze jego skonfigurowanie do poprawnej komunikacji z udostępnionymi przez system nip24.pl usługami sieciowymi (ang. webservices).

Rejestracja

Wymagana jest rejestracja podmiotu, który chce skorzystać z funkcjonalności systemu nip24.pl. W tym celu należy wejść na stronę Rejestracja i wypełnić odpowiedni formularz. Warunkiem koniecznym do korzystania z systemu nip24.pl jest akceptacja regulaminu. Poprawne wypełnienie formularza i kliknięcie przycisku Zarejestruj powoduje utworzenie konta w systemie nip24.pl oraz automatyczną jego aktywację.

Logowanie

Logowanie do aktywowanego konta jest możliwe wejściu na zakładkę Konto oraz podanie adresu e-mail i hasła zdefiniowanego w czasie rejestracji. Po poprawnym uwierzytelnieniu, możliwe jest zarządzanie kontem. Użytkownik na swoim koncie może wygenerować identyfikatory i klucze dostępowe, które służą do uwierzytelnienia się do systemu.

Podczas pierwszego logowania generowany jest automatycznie identyfikator wraz z odpowiadającym mu kluczem. Identyfikator ma charakter publiczny i nie wymaga ochrony, natomiast klucz ma charakter prywatny i nie powinien być udostępniany osobom trzecim. Dodatkowo w celu zwiększenia bezpieczeństwa użytkownik może wprowadzić adres IP, z którego mogą przychodzić zapytania. Może to być na przykład adres IP sklepu internetowego. W pakiecie darmowym Użytkownik może wygenerować tylko jedną parę klucza i identyfikatora. W pakietach płatnych nie ma ograniczenia na liczbę wygenerowanych par kluczy i identyfikatorów. W przypadku gdy użytkownik nie chce już używać jakiejś pary identyfikator-klucz może ją wyłączyć zmieniając jej status.

 

Interfejs GUI

Interfejs umożliwiający wyszukiwanie danych przedsiębiorców na podstawie wprowadzonego numeru NIP dostępny jest na stronie Wyszukiwanie firm.

Po wprowadzeniu w odpowiednie pole numeru NIP, numeru REGON lub KRS niezbędne jest zaznaczenie pola zabezpieczającego Nie jestem robotem pełniącego rolę CAPTCHA i kliknięcie przycisku Szukaj. W polu NIP można wpisać 10 cyfrowy numer NIP szukanej firmy. W polu REGON można wpisać numer REGON. Przy wyszukiwaniu po numerze KRS, należy wprowadzić pełny numer KRS. Jeśli firma zostanie znaleziona w bazie serwisu, wtedy wyświetlane są jej podstawowe dane:

  • Pełna nazwa firmy
  • Numer NIP
  • Adres prowadzenia działalności:
    • Nazwa ulicy
    • Numer budynku wraz z numerem lokalu
    • Miejscowość
    • Kod pocztowy wraz z pocztą
  • Numer telefonu*
  • Adres e-mail*
  • Adres WWW*

* Dane nie są dostępne dla wszystkich firm

Dodatkowo została utworzona strona umożliwiająca sprawdzenie podmiotu w VAT. Po wpisaniu numeru NIP, REGON lub KRS serwis odpytuje bezpośrednio system Ministerstwa Finansów i zwraca informacje pozwalające określić, czy:

  • Podmiot o podanym identyfikatorze podatkowym NIP nie jest zarejestrowany jako podatnik VAT.
  • Podmiot o podanym identyfikatorze podatkowym NIP jest zarejestrowany jako podatnik VAT czynny.
  • Podmiot o podanym identyfikatorze podatkowym NIP jest zarejestrowany jako podatnik VAT zwolniony.

Korzystając ze strony można porównać identyczność odpowiedzi udzielanych przez Portal Podatkowy MF oraz nasze API.

Interfejs API

Interfejs API umożliwia wyszukiwanie danych przedsiębiorców na podstawie wprowadzonego numeru NIP, REGON, KRS lub VAT EU. Obecnie dostępne są biblioteki API dla następujących języków programowania:

  • .NET (C#, Visual Basic)
  • C/C++
  • Java
  • PHP
  • Python

Interfejs API udostępnia następujące funkcje:

  • isActive – funkcja do sprawdzania bieżącego statusu działalności firmy,
  • getInvoiceData – funkcja do pobierania podstawowych danych firmy umożliwiających prawidłowe wystawienie faktury,
  • getAllData – funkcja do pobierania szczegółowych danych firmy,
  • getVIESData – funkcja do potwierdzania aktywności numeru VAT EU nadanego przez dowolne z państw członkowskich Unii Europejskiej,
  • getVATStatus – funkcja do sprawdzania statusu podmiotu w rejestrze VAT udostępnianym w Portalu Podatkowym Ministerstwa Finansów,
  • getAccountStatus – funkcja do pobierania aktualnych informacji dotyczących konta użytkownika.

Bibliotekę Java można dodać do projektu korzystając z repozytorium Maven:

<repository>
    <id>nip24</id>
    <url>https://www.nip24.pl/public/maven</url>
</repository>

<dependency>
    <groupId>pl.nip24</groupId>
    <artifactId>nip24-client</artifactId>
    <version>1.3.1</version>
</dependency>

Bibliotekę .NET można dodać do projektu poprzez NuGet Gallery.

Uwierzytelnienie

W celu wykonania poprawnego uwierzytelnienia należy podczas konstrukcji obiektu klienta podać prawidłowe wartości parametrów id oraz key. Parametr id powinien zawierać prawidłowy identyfikator klucza służącego do autoryzacji. Parametr key powinien zawierać prawidłową wartość klucza służącego do autoryzacji. Identyfikator klucza oraz klucz generowane są przez użytkownika po zalogowaniu się na swoje konto w portalu nip24.pl. Proces generowania kluczy i identyfikatorów został szczegółowo opisany powyżej.

Poniższy przykład obrazuje sposób użycia funkcji biblioteki.

using nip24Library.dll;

// Utworzenie obiektu klienta usługi serwisu produkcyjnego
// id – ciąg znaków reprezentujący identyfikator klucza API
// key – ciąg znaków reprezentujący klucz API
NIP24Client nip24 = new NIP24Client("id", "key");
#include "nip24.h"

// Utworzenie obiektu klienta usługi serwisu produkcyjnego
// id – ciąg znaków reprezentujący identyfikator klucza API
// key – ciąg znaków reprezentujący klucz API
NIP24Client* nip24 = NULL;
nip24_new_prod(&nip24, "id", "key");
import pl.nip24.client.*;

// Utworzenie obiektu klienta usługi serwisu produkcyjnego
// id – ciąg znaków reprezentujący identyfikator klucza API
// key – ciąg znaków reprezentujący klucz API
NIP24Client nip24 = new NIP24Client("id", "key");
require_once 'NIP24/NIP24Client.php';

\NIP24\NIP24Client::registerAutoloader();

// Utworzenie obiektu klienta usługi serwisu produkcyjnego
// id – ciąg znaków reprezentujący identyfikator klucza API
// key – ciąg znaków reprezentujący klucz API
$nip24 = new \NIP24\NIP24Client('id', 'key');
from nip24 import *
from pprint import pprint

# Utworzenie obiektu klienta usługi serwisu produkcyjnego
# id – ciąg znaków reprezentujący identyfikator klucza API
# key – ciąg znaków reprezentujący klucz API
nip24 = NIP24Client('id', 'key')
' Utworzenie obiektu klienta usługi serwisu produkcyjnego
' id – ciąg znaków reprezentujący identyfikator klucza API
' key – ciąg znaków reprezentujący klucz API
Dim nip24 As New NIP24Client
nip24.URL = "https://www.nip24.pl/api"
nip24.Id = "id"
nip24.Key = "key"

Uwaga! Podczas procesu uwierzytelnienia wykorzystywany jest czas bieżący komputera klienta, dlatego w przypadku problemów z uwierzytelnieniem przy próbie połączenia z systemem nip24.pl, należy w pierwszej kolejności upewnić się czy komputer lub serwer, z którego jest nawiązywane połączenie ma prawidłowo ustawiony czas bieżący i strefę czasową. Więcej informacji na temat używanej przez system nip24.pl metody uwierzytelnienia zapytań można znaleźć tutaj.

Pobranie bieżącego statusu firmy realizowane jest poprzez wywołanie funkcji isActive(), której parametrem jest szukany numer NIP. Funkcja zwraca wartość true, jeżeli firma prowadzi aktywą działalność, zarejestrowaną w odpowiednim rejestrze, która nie została zawieszona lub zakończona. W przeciwnym wypadku zwracana jest wartość false.

Poniższy przykład obrazuje sposób użycia funkcji biblioteki.

// Sprawdzenie statusu firmy
bool active = nip24.IsActive(Number.NIP, "123-456-78-90");

if (active) {
	Console.WriteLine("Firma prowadzi aktywną działalność");
}
else {
	if (String.IsNullOrEmpty(nip24.LastError)) {
		Console.WriteLine("Firma zawiesiła lub zakończyła działalność");
	}
	else {
		Console.WriteLine("Błąd: " + nip24.LastError);
	}
}
// Sprawdzenie statusu firmy
BOOL active = nip24_is_active(nip24, NIP, "123-456-78-90");

if (active) {
	printf("Firma prowadzi aktywną działalność\n");
}
else {
	if (nip24_get_last_err(nip24) == NULL) {
		printf("Firma zawiesiła lub zakończyła działalność\n");
	}
	else {
		printf("Błąd: %s\n", nip24_get_last_err(nip24));
	}
}
// Sprawdzenie statusu firmy
boolean active = nip24.isActive(Number.NIP, "123-456-78-90");

if (active) {
	System.out.println("Firma prowadzi aktywną działalność");
}
else {
	if (nip24.getLastError() == null) {
		System.out.println("Firma zawiesiła lub zakończyła działalność");
	}
	else {
		System.err.println("Błąd: " + nip24.getLastError());
	}
}
// Sprawdzenie statusu firmy
$active = $nip24->isActiveExt(\NIP24\Number::NIP, '123-456-78-90');

if ($active) {
	echo '<p>Firma prowadzi aktywną działalność</p>';
}
else {
	if (!$nip24->getLastError()) {
		echo ''<p>Firma zawiesiła lub zakończyła działalność</p>';
	}
	else {
		echo ''<p>Błąd: ' . $nip24->getLastError() . '</p>';
	}
}
# Sprawdzenie statusu firmy
active = nip24.isActiveExt(Number.NIP, '123-456-78-90')

if active:
	print u'Firma prowadzi aktywną działalność'
else:
    if not nip24.getLastError():
        print u'Firma zawiesiła lub zakończyła działalność'
    else:
        print u'Błąd: ' + nip24.getLastError()
' Sprawdzenie statusu firmy
Dim active As Boolean
Set active = nip24.IsActive(Number_NIP, "123-456-78-90")

If active Then
	Console.WriteLine("Firma prowadzi aktywną działalność")
Else
	If (String.IsNullOrEmpty(nip24.LastError)) Then
		Console.WriteLine("Firma zawiesiła lub zakończyła działalność")
	Else
		Console.WriteLine("Błąd: {0}", nip24.LastError)
	End If
End If

Pobranie danych niezbędnych do wystawienia faktury realizowane jest poprzez wywołanie funkcji getInvoiceData() lub getInvoiceDataExt(), której parametrami są: typ szukanego numeru (NIP, REGON lub KRS), wartość szukanego numeru oraz flaga logiczna wskazująca czy dane są tylko pobierane (false), czy aktualizowane (true). Wywołanie funkcji z parametrem true powoduje, że system odpytuje bezpośrednio referencyjną bazę danych, co gwarantuje pobranie aktualnych danych, ale jest nieco wolniejsze niż wywołanie funkcji z parametrem false. Wyszukiwanie po numerach REGON i KRS dostępne jest wyłącznie po wybraniu jednego z płatnych planów.

Poniższy przykład obrazuje sposób użycia funkcji biblioteki.

// Wywołanie metody zwracającej dane do faktury
InvoiceData invoice = nip24.GetInvoiceData(Number.NIP, "123-456-78-90", false);

if (invoice != null) {
	Console.WriteLine("Nazwa: " + invoice.Name);
	Console.WriteLine("Adres : " + invoice.PostCode + " " + invoice.PostCity + " " + invoice.Street
		+ " " + invoice.StreetNumber);
	Console.WriteLine("Telefon: " + invoice.Phone);
	Console.WriteLine("E-mail: " + invoice.Email);
	Console.WriteLine("WWW: " + invoice.WWW);
}
else {
	Console.WriteLine("Błąd: " + nip24.LastError);
}
// Wywołanie metody zwracającej dane do faktury
InvoiceData* invoice = nip24_get_invoice_data(nip24, NIP, "123-456-78-90", FALSE);

if (invoice != NULL) {
	printf("Nazwa: %s\n", invoice->Name);
	printf("Imię i nazwisko: %s %s\n", invoice->FirstName, invoice->LastName);
	printf("Adres: %s %s %s %s\n", invoice->PostCode, invoice->PostCity, invoice->Street, invoice->StreetNumber);
	printf("NIP: %s\n", invoice->NIP);
}
else {
	printf("Błąd: %s\n", nip24_get_last_err(nip24));
}
// Wywołanie metody zwracającej dane do faktury
InvoiceData invoice = nip24.getInvoiceData(Number.NIP, "123-456-78-90", false);

if (invoice != null) {
	System.out.println("NIP: " + invoice.getNIP());
	System.out.println("Nazwa: " + invoice.getName());
	System.out.println("Imię i nazwisko: " + invoice.getFirstName() + " " + invoice.getLastName());
	System.out.println("Adres: " + invoice.getPostCode() + " " + invoice.getPostCity() + " "
		+ invoice.getStreet() + " " + invoice.getStreetNumber());
	System.out.println("Telefon: " + invoice.getPhone());
	System.out.println("E-mail: " + invoice.getEmail()); 
	System.out.println("WWW: " + invoice.getWWW());
}
else {
	System.out.println("Błąd: " + nip24.getLastError());
}
// Wywołanie metody zwracającej dane do faktury
$invoice = $nip24->getInvoiceDataExt(\NIP24\Number::NIP, '123-456-78-90', false);

if ($invoice) {
	echo '<p>NIP: ' . $invoice->nip . '</p>';
	echo '<p>Nazwa: ' . $invoice->name . '</p>';
	echo '<p>Imię i nazwisko: ' . $invoice->firstname . ' ' . $invoice->lastname . '</p>';
	echo '<p>Adres: ' . $invoice->postCode . ' ' . $invoice->postCity . ' ' . $invoice->street
		. ' ' . $invoice->streetNumber . '</p>';
	echo '<p>Telefon: ' . $invoice->phone . '</p>';
	echo '<p>E-mail: ' . $invoice->email . '</p>';
	echo '<p>WWW: ' . $invoice->www . '</p>';
}
else {
	echo '<p>Błąd: ' . $nip24->getLastError() . '</p>';
}
# Wywołanie metody zwracającej dane do faktury
invoice = nip24.getInvoiceDataExt(Number.NIP, '123-456-78-90', False)

if invoice:
    print u'NIP: ' + invoice.nip
    print u'Nazwa: ' + invoice.name
    print u'Imię i nazwisko: ' + invoice.firstname + ' ' + invoice.lastname
    print u'Adres: ' + invoice.postCode + ' ' + invoice.postCity + ' ' + invoice.street \
		+ ' ' + invoice.streetNumber
    print u'Telefon: ' + invoice.phone
    print u'E-mail: ' + invoice.email
    print u'WWW: ' + invoice.www
else:
	print u'Błąd: ' . nip24.getLastError()
' Wywołanie metody zwracającej dane do faktury
Dim invoice As InvoiceData
Set invoice = nip24.GetInvoiceData(Number_NIP, "123-456-78-90", False)

If invoice Is Nothing Then
	Console.WriteLine("Błąd: {0}", nip24.LastError)
Else
	Console.WriteLine(invoice.ToString())
End If

Funkcja ta jest dostępna wyłącznie po wybraniu jednego z płatnych planów. Pobranie szczegółowych danych firmy realizowane jest poprzez wywołanie funkcji getAllData() lub getAllDataExt(), której parametrami są: typ szukanego numeru (NIP, REGON lub KRS), wartość szukanego numeru oraz oraz flaga logiczna wskazująca czy dane są tylko pobierane (false), czy aktualizowane (true). Wywołanie funkcji z parametrem true powoduje, że system odpytuje bezpośrednio referencyjną bazę danych, co gwarantuje pobranie aktualnych danych, ale jest nieco wolniejsze niż wywołanie funkcji z parametrem false.

Poniższy przykład obrazuje sposób użycia funkcji biblioteki.

// Wywołanie metody zwracającej szczegółowe dane firmy
AllData all = nip24.GetAllData(Number.NIP, "123-456-78-90", false);

if (all != null) {
	Console.WriteLine(all);
}
else {
	Console.WriteLine("Błąd: " + nip24.LastError);
}
// Wywołanie metody zwracającej szczegółowe dane firmy
AllData* all = nip24_get_all_data(nip24, NIP, "123-456-78-90", FALSE);

if (all != NULL) {
	printf("Nazwa: %s\n", all->Name);
	printf("Imię i nazwisko: %s %s\n", all->FirstName, all->LastName);
	printf("Adres: %s %s %s %s\n", all->PostCode, all->PostCity, all->Street, all->StreetNumber);
	printf("NIP: %s\n", all->NIP);
}
else {
	printf("Błąd: %s\n", nip24_get_last_err(nip24));
}
// Wywołanie metody zwracającej szczegółowe dane firmy
AllData all = nip24.getAllData(Number.NIP, "123-456-78-90", false);

if (all != null) {
	System.out.println(all);
}
else {
	System.out.println("Błąd: " + nip24.getLastError());
}
// Wywołanie metody zwracającej szczegółowe dane firmy
$all = $nip24->getAllDataExt(\NIP24\Number::NIP, '123-456-78-90', false);

if ($all) {
	print_r($all);
}
else {
	echo '<p>Błąd: ' . $nip24->getLastError() . '</p>';
}
# Wywołanie metody zwracającej szczegółowe dane firmy
all = nip24.getAllDataExt(Number.NIP, '123-456-78-90', False)

if all:
	pprint(vars(all))
else:
	print u'Błąd: ' + nip24.getLastError()
' Wywołanie metody zwracającej szczegółowe dane firmy
Dim all As AllData
Set all = nip24.GetAllData(Number_NIP, "123-456-78-90", False)

If all Is Nothing Then
	Console.WriteLine("Błąd: {0}", nip24.LastError)
Else
	Console.WriteLine(all.ToString())
End If

Funkcja zwraca następujące dane:

  • dane do faktury (NIP, nazwa firmy, adres siedziby firmy),
  • nazwę skróconą firmy,
  • numer REGON,
  • dane kontaktowe (telefon, e-mail, WWW),
  • nazwę województwa, powiatu i gminy siedziby firmy,
  • kody TERYT dla województwa, powiatu, gminy, miejscowości i nazwy ulicy siedziby firmy,
  • daty: wpisu do ewidencji, rozpoczęcia, zawieszenia, wznowienia i zakończenia działalności,
  • symbol i nazwę organu rejestrowego,
  • symbol i nazwę rejestru lub ewidencji (m.in. CEIDG, KRS),
  • datę wpisu i numer w rejestrze lub ewidencji (m.in. numer KRS),
  • symbol i nazwę podstawowej formy prawnej,
  • symbol i nazwę szczególnej formy prawnej,
  • symbol i nazwę formy własności,
  • listę kodów PKD (Polska Klasyfikacja Działalności).

Funkcja ta jest dostępna wyłącznie po wybraniu jednego z płatnych planów. Potwierdzenie aktywności numeru VAT EU realizowane jest poprzez wywołanie funkcji getVIESData(), której parametem jest numer VAT EU, który chcemy zweryfikować. Funkcja umożliwia weryfikację numerów VAT EU nadawanych przez wszystkie kraje członkowskie Unii Europejskiej.

Poniższy przykład obrazuje sposób użycia funkcji biblioteki.

// Wywołanie metody zwracającej dane z systemu VIES
VIESData vies = nip24.GetVIESData("PL1234567890");

if (vies != null) {
	Console.WriteLine(vies);
}
else {
	Console.WriteLine("Błąd: " + nip24.LastError);
}
// Wywołanie metody zwracającej dane z systemu VIES
VIESData* vies = nip24_get_vies_data(nip24, "PL1234567890");

if (vies != NULL) {
	printf("Kraj: %s\n", vies->CountryCode);
	printf("VAT ID: %s\n", vies->VATNumber);
	printf("Aktywny: %d\n", vies->Valid);
}
else {
	printf("Błąd: %s\n", nip24_get_last_err(nip24));
}
// Wywołanie metody zwracającej dane z systemu VIES
VIESData vies = nip24.getVIESData("PL1234567890");

if (vies != null) {
	System.out.println(vies);
}
else {
	System.out.println("Błąd: " + nip24.getLastError());
}
// Wywołanie metody zwracającej dane z systemu VIES
$vies = $nip24->getVIESData('PL1234567890');

if ($vies) {
	print_r($vies);
}
else {
	echo '<p>Błąd: ' . $nip24->getLastError() . '</p>';
}
# Wywołanie metody zwracającej dane z systemu VIES
vies = nip24.getVIESData('PL1234567890')

if vies:
    pprint(vars(vies))
else:
    print u'Błąd: ' + nip24.getLastError()
' Wywołanie metody zwracającej dane z systemu VIES
Dim vies As VIESData
Set vies = nip24.GetVIESData("PL1234567890")

If vies Is Nothing Then
	Console.WriteLine("Błąd: {0}", nip24.LastError)
Else
	Console.WriteLine(vies.ToString())
End If

Funkcja ta jest dostępna wyłącznie w wybranych planach. Sprawdzenie statusu podmiotu realizowane jest poprzez wywołanie funkcji getVATStatus(), której parametrami są: typ szukanego numeru (NIP, REGON lub KRS), wartość szukanego numeru oraz oraz flaga logiczna wskazująca czy dane mają być pobierane bezpośrednio z Portalu Podatkowego Ministerstwa Finansów (true), czy też pośrednio poprzez Portal NIP24 (false). Wywołanie funkcji z parametrem true powoduje, że system odpytuje bezpośrednio Portal Podatkowy Ministerstwa Finansów, co gwarantuje najszybsze sprawdzenie statusu, ale w tym trybie możliwe jest wyłącznie sprawdzanie podmiotu po numerze NIP. Wywołanie funkcji z parametrem false umożliwia sprawdzanie podmiotów po numerach NIP, REGON i KRS ale wymaga wcześniejszego pobrania danych podmiotu z bazy NIP24 i może być nieco wolniejsze. W obu trybach wywołania funkcji wykonywane jest sprawdzenie bieżącego statusu podmiotu bezpośrednio w Portalu Podatkowym Ministerstwa Finansów.

Interpretacja zwracanych wartości:

  • nip – numer NIP firmy dla którego realizowane było zapytanie,
  • regon – numer REGON firmy (wartość zwracana tylko dla flagi = false),
  • name – nazwa firmy skojarzona z podanym numerem NIP (wartość zwracana tylko dla flagi = false),
  • status – bieżący status sprawdzanego podmiotu:
    • status = 1, result = „Podmiot o podanym identyfikatorze podatkowym NIP nie jest zarejestrowany jako podatnik VAT.”,
    • status = 2, result = „Podmiot o podanym identyfikatorze podatkowym NIP jest zarejestrowany jako podatnik VAT czynny.”,
    • status = 3, result = „Podmiot o podanym identyfikatorze podatkowym NIP jest zarejestrowany jako podatnik VAT zwolniony.”,
  • date – data wykonania zapytania,
  • source – źródło odpowiedzi (zawsze jest to: https://ppuslugi.mf.gov.pl).

Poniższy przykład obrazuje sposób użycia funkcji biblioteki.

// Sprawdzenie statusu firmy w rejestrze VAT
VATStatus vat = nip24.GetVATStatus(Number.NIP, "123-456-78-90", true);

if (vat != null) {
	Console.WriteLine("NIP: " + vat.NIP);
	Console.WriteLine("REGON: " + vat.REGON);
	Console.WriteLine("Nazwa firmy: " + vat.Name);
	Console.WriteLine("Status: " + vat.Status);
	Console.WriteLine("Wynik: " + vat.Result);
	Console.WriteLine("Data sprawdzenia: " + vat.Date);
	Console.WriteLine("Źródło: " + vat.Source);
}
else {
	Console.WriteLine("Błąd: " + nip24.LastError);
}
// Sprawdzenie statusu firmy w rejestrze VAT
VATStatus* vat = nip24_get_vat_status(nip24, NIP, "123-456-78-90", TRUE);

if (vat != NULL) {
	printf("NIP: %s\n", vat->NIP);
	printf("REGON: %s\n", vat->REGON);
	printf("Nazwa firmy: %s\n", vat->Name);
	printf("Status: %d\n", vat->Status);
	printf("Wynik: %s\n", vat->Result);
}
else {
	printf("Błąd: %s\n", nip24_get_last_err(nip24));
}
// Sprawdzenie statusu firmy w rejestrze VAT
VATStatus vat = nip24.getVATStatus(Number.NIP, "123-456-78-90", true);

if (vat != null) {
	System.out.println("NIP: " + vat.getNIP());
	System.out.println("REGON: " + vat.getREGON());
	System.out.println("Nazwa firmy: " + vat.getName());
	System.out.println("Status: " + vat.getStatus());
	System.out.println("Wynik: " + vat.getResult());
	System.out.println("Data sprawdzenia: " + vat.getDate());
	System.out.println("Źródło: " + vat.getSource());
}			
else {
	System.out.println("Błąd: " + nip24.getLastError());
}
// Sprawdzenie statusu firmy w rejestrze VAT
$vat = $nip24->getVATStatusExt(\NIP24\Number::NIP, '123-456-78-90', true);

if ($vat) {
	echo '<p>NIP: ' . $vat->nip . '</p>';
	echo '<p>REGON: ' . $vat->regon . '</p>';
	echo '<p>Nazwa firmy: ' . $vat->name . '</p>';
	echo '<p>Status: ' . $vat->status . '</p>';
	echo '<p>Wynik: ' . $vat->result . '</p>';
	echo '<p>Data sprawdzenia: ' . $vat->date . '</p>';
	echo '<p>Źródło: ' . $vat->source . '</p>';
}
else {
	echo '<p>Błąd: ' . $nip24->getLastError() . '</p>';
}
# Sprawdzenie statusu firmy w rejestrze VAT
vat = nip24.getVATStatusExt(Number.NIP, '123-456-78-90', True)

if vat:
    print u'NIP: ' + vat.nip
    print u'REGON: ' + vat.regon
    print u'Nazwa firmy: ' + vat.name
    print u'Status: ' + vat.status
    print u'Wynik: ' + vat.result
    print u'Data sprawdzenia: ' + vat.date
    print u'Źródło: ' + vat.source
else:
    print u'Błąd: ' . nip24.getLastError()
' Sprawdzenie statusu firmy w rejestrze VAT
Dim vat As VATStatus
Set vat = nip24.GetVATStatus(Number_NIP, "123-456-78-90", True)

If vat Is Nothing Then
	Console.WriteLine("Błąd: {0}", nip24.LastError)
Else
	Console.WriteLine(vat.Result)
End If

Funkcja umożliwia pobranie wszystkich podstawowych informacji dotyczących konta użytkownika, które wyświetlane są po zalogowaniu na konto w portalu nip24.pl. Funkcja zwraca również informację o maksymalnej liczbie zapytań dostępnych w ramach wybranego plan (np. 5 tys. dla planu Biznes) oraz zsumowaną liczbę wszystkich wykonanych w bieżącym miesiącu zapytań na koncie użytkownika.

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

Poniższy przykład obrazuje sposób użycia funkcji biblioteki.

// Sprawdzenie stanu konta
AccountStatus account = nip24.GetAccountStatus();

if (account != null) {
     Console.WriteLine(account);
}
else {
     Console.WriteLine("Błąd: " + nip24.LastError);
}
// Sprawdzenie stanu konta
AccountStatus* account = nip24_get_account_status(nip24);

if (account != NULL) {
	printf("Nazwa planu: %s\n", account->BillingPlanName);
	printf("Cena: %.2f\n", account->SubscriptionPrice);
	printf("Ilość zapytań: %d\n", account->TotalCount);
}
else {
	printf("Błąd: %s\n", nip24_get_last_err(nip24));
}
// Sprawdzenie stanu konta
AccountStatus account = nip24.getAccountStatus();

if (account != null) {
     System.out.println(account);
}
else {
     System.err.println("Błąd: " + nip24.getLastError());
}
// Sprawdzenie stanu konta
$account = $nip24->getAccountStatus();

if ($account) {
     echo '<p>' . print_r($account, true) . '</p>';
}
else {
     echo '<p>Błąd: ' . $nip24->getLastError() . '</p>';
}
# Sprawdzenie stanu konta
account = nip24.getAccountStatus()

if account:
    pprint(vars(account))
else:
    print u'Błąd: ' + nip24.getLastError()
'Sprawdzenie stanu konta
Dim account As AccountStatus
Set account = nip24.GetAccountStatus()

If account Is Nothing Then
	Console.WriteLine("Błąd: {0}", nip24.LastError)
Else
	Console.WriteLine(account.ToString())
End If

Bibliotekę nip24Library.dll można zarejestrować w systemie Windows jako tzw. obiekt COM. Wówczas do funkcji biblioteki można się odwoływać z wielu różnych języków programowania oraz gotowych aplikacji, m.in. Microsoft Excel, Access, SQL Server, Dynamics czy Visual FoxPro.

Aby zarejestrować bibliotekę jako obiekt COM należy wykonać następujące czynności:

  1. Pobrać archiwum biblioteki .NET i rozpakować na dysku lokalnym do dowolnej lokalizacji.
  2. Wejść do katalogu z rozpakowanymi plikami biblioteki i odszukać plik com-register.bat.
  3. Zaznaczyć plik com-register.bat myszą i z menu kontekstowego wybrać polecenie Uruchom jako administrator.

Funkcje biblioteki nip24Library.dll można wykorzystać w aplikacji MS Excel do napisania własnych funkcji i procedur w języku Visual Basic. Aby to było możliwe należy:

  1. Zarejestrować bibliotekę nip24Library.dll jako obiekt COM w systemie Windows.
  2. Uruchomić aplikację Excel. Na wstążce wybrać zakładkę DEVELOPER, a następnie kliknąć przycisk Visual Basic.
  3. W oknie Visual Basic for Application wybrać z menu Tools, a następnie References. Na liście Available References odszukać i zaznaczyć NIP24 Service Client for .NET Framework (C#). Wybór zatwierdzić przyciskiem OK.
  4. Z menu Insert wybrać Module i w nowym oknie wkleić kod funkcji zaprezentowany w przykładach dla Visual Basic.
  5. Na koniec należy ustawić odpowiednie wartości w dla nip24.ID oraz nip24.Key. Sposób uzyskania klucza oraz identyfikatora został opisany w rozdziale Generowanie identyfikatora oraz klucza dostępowego