20 marca 2017

strona_testowa_dokumentacji

Wprowadzenie

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 przypadku gdy użytkownik nie chce już używać jakiejś pary identyfikator-klucz może ją wyłączyć zmieniając jej status.

Zarządzanie kluczami i identyfikatorami portalu nip24.pl

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,
  • getIBANStatus – funkcja do sprawdzania statusu rachunku bankowego podmiotu w wykazie podatników VAT (tzw. białej liście podmiotów VAT).
  • getAccountStatus – funkcja do pobierania aktualnych informacji dotyczących konta użytkownika.

Integracja

Sposób integracji biblioteki zależy od wybranego języka programowania. Dla tych języków, które wspierają zarządzanie bibliotekami w oparciu o centralne repozytorium możliwe jest jego użycie.

// NuGet Gallery
// https://www.nuget.org/packages/NIP24.NIP24Client

PM> Install-Package NIP24.NIP24Client
// Brak wsparcia dla centralnego repozytorium
// Maven
// https://www.nip24.pl/public/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.3</version>
</dependency>
// Packagist (Composer)
// https://packagist.org/packages/nip24/client

composer require nip24/client
# Brak wsparcia dla centralnego repozytorium
' Brak wsparcia dla centralnego repozytorium

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
// id – ciąg znaków reprezentujący identyfikator klucza
// key – ciąg znaków reprezentujący klucz
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
// id – ciąg znaków reprezentujący identyfikator klucza
// key – ciąg znaków reprezentujący klucz
NIP24Client nip24 = new NIP24Client("id", "key");
require_once 'NIP24/NIP24Client.php';

\NIP24\NIP24Client::registerAutoloader();

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

# Utworzenie obiektu klienta usługi
# id – ciąg znaków reprezentujący identyfikator klucza
# key – ciąg znaków reprezentujący klucz
nip24 = NIP24Client('id', 'key')
' Utworzenie obiektu klienta usługi
' id – ciąg znaków reprezentujący identyfikator klucza
' key – ciąg znaków reprezentujący klucz
Dim nip24 As New NIP24Client
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.getIBANStatusExt(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

Funkcja ta jest dostępna wyłącznie w wybranych planach. Weryfikacja rachunku bankowego podmiotu realizowana jest poprzez wywołanie funkcji getIBANStatus(), której parametrami są:

  • type – określa czy zapytanie będzie realizowane po numerze NIP czy REGON (parametr wymagany). Akceptowalne są tylko dwie wartości: NIP lub REGON.
  • number – wartość numeru NIP albo REGON firmy dla której realizowane jest sprawdzenie (parametr wymagany). Format dowolny – akceptowalne są kreski lub spacje między cyframi. Przykład: 111-222-22-22,
  • iban – weryfikowany numer rachunku bankowego firmy (parametr wymagany) zgodny z ISO3166. Format: pierwsze dwa znaki to kod kraju (np: PL), a natępne 28 cyfry to numer rachunku. Przykład: PL 11 1234 1234 1234 1234 1234 1234. Można stosować znaki spacji między grupami cyfr. Uwaga! Jeśli kod kraju nie zostanie podany, to rachunek będzie weryfikowany jako polski.
  • date – dzień na jaki ma zostać wykonane sprawdzenie  (parametr opcjonalny, jeśli nie zostanie podany, to weryfikacja zostanie przeporwadzaona na dzień bieżący). Akceptowalny format daty: YYYY-MM-DD, przykład: ‚2019-09-01

Zwracane wartości pobierane są bezpośrednio z wykazu podatników VAT (tzw. białej listy podatników VAT) Ministerstwa Finansów albo z udostępnianego przez MF pliku.

Poniża lista zwiera zestaw zwracanych wartości wraz z opisem ich interpretacji:

  • nip – numer NIP firmy dla którego realizowane było zapytanie (wartość zwracana tylko jeśli zapytanie było realizowane po numerze NIP),
  • regon – numer REGON firmy dla którego realizowane było zapytanie (wartość zwracana tylko jeśli zapytanie było realizowane po numerze REGON),
  • iban – znormalizowany (bez spacji) numer konta bankowego kontrahenta, który został podany w zapytaniu.
  • valid – odpowiedź z serwisu Ministerstwa Finansów:  TRUE – podany w zapytaniu NIP/REGON pasuje do wskazanego rachunku bankowego, FALSE – podany w zapytaniu NIP/REGON nie pasuje do wskazanego rachunku bankowego
  • id – odpowiedź (requestId) z serwisu Ministerstwa Finansów. Uzyskane w odpowiedzi requestId potwierdza wykonanie zapytania oraz uzyskaną odpowiedź.
  • date – data sprawdzenia powiązania numeru NIP/REGON z numerem konta bankowego kontrahenta  (w formacie: yyyy-mm-dd)
  • source – informacja o url źródła (adres interfejsu API  MF albo nazwa pliku wykorzystanego do weryfikacji)

Dodatkowo, w każdej bibliotece została dodana klasa IBAN do weryfikacji numerów rachunków (wszystkie kraje), która będzie zawierała dwie funkcje:

  • normalize() – funkcja we wszystkich weryfikatorach (NIP, REGON, KRS, EUVAT, IBAN) usuwa zbędne znaki, tak aby parametr wejściowy zawierał tylko odpowiednie znaki.
  • isVAlid() – funkcja sprawdza czy podany numer rachunku bankowego jest poprawnym numerem IBAN. W różnych krajach numer konta bankowego ma różne formaty, a dzięki tej funkcji można łatwo zweryfikować jego popraność. O formatach numerów kont bankowych w poszczególnych krajach można dowiedzieć się więcej tutaj.

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

// Weryfikacja rachunku bankowego kontrahenta w wykazie podatników VA
IBANStatusExt iban = nip24.getIBANStatusExt("NIP", "123-456-78-90", "12 1234 1234 1234 1234 1234 1234", "2019-09-01");

if (iban != null) {
	Console.WriteLine("NIP kontrahenta: " + iban.NIP);
	Console.WriteLine("Numer rachunku bankowego: " + iban.IBAN);
	Console.WriteLine("Status konta bankowego: " + iban.Valid);
	Console.WriteLine("Identyfikator MF (requestId): " + iban.Id);
	Console.WriteLine("Data sprawdzenia: " + iban.Date);
	Console.WriteLine("Źródło: " + iban.Source);
}
else {
	Console.WriteLine("Błąd: " + nip24.LastError);
}
// Weryfikacja rachunku bankowego kontrahenta w wykazie podatników VA
TODO
// Weryfikacja rachunku bankowego kontrahenta w wykazie podatników VA
IBANStatusExt iban = nip24.getIBANStatusExt("NIP", "123-456-78-90", "12 1234 1234 1234 1234 1234 1234", "2019-09-01");
if (iban != null) {
	System.out.println("NIP kontrahenta: " + iban.getNIP());
	System.out.println("Numer rachunku bankowego: " + iban.getName());
	System.out.println("Status konta bankowego: " + iban.getValid());
	System.out.println("Identyfikator MF (requestId): " + iban.getId());
	System.out.println("Data sprawdzenia: " + iban.getDate());
	System.out.println("Źródło: " + iban.getSource());
}			
else {
	System.out.println("Błąd: " + nip24.getLastError());
}
// Weryfikacja rachunku bankowego kontrahenta w wykazie podatników VA
$iban = $nip24->getIBANStatusExt(\NIP24\Number::NIP, $nip, $iban);
if ($iban) {
	echo '<p>IBAN: ' . print_r($iban, true) . '</p>';
}
else {
	echo '<p>Błąd: ' . $nip24->getLastError() . '</p>';
}
# Weryfikacja rachunku bankowego kontrahenta w wykazie podatników VA
TODO
'Weryfikacja rachunku bankowego kontrahenta w wykazie podatników VA
TODO

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 aplikacji i języków programowania.

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: getInvoiceData, getAllData, getVIESData oraz getVATStatus.
      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