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 (z wyjątkiem KRS) 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 typu REST (więcej na temat bezpośredniego połączenia z REST API znajdziesz tutaj).

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.

Generowanie identyfikatora oraz klucza dostępowego

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. 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.

faktury ksef api vat vies

Zapisanie tokenu Krajowego Systemu e-Faktur (KSeF)

W celu zapisania tokenu KSeF należy przejść na zakładkę „Klucze API„, a następnie zaznaczyć pole w kolumnie KSEF. Następnie należy wkleić wygenerowany zgodnie z procedurą generowania tokena dostępowego w KSeF, token (losowy ciąg znaków) w pole Token. Pole NIP należy wypełnić tylko wtedy, kiedy konto główne w nip24.pl jest kontem Integratora i poszczególne klucze API mają być przypisane do poszczególnych klientów Integratora. Wpisany w polu Token losowy ciąg znaków musi być skojarzony albo z numerem NIP konta głównego (zakładka Informacje), albo z numerem NIP klienta Integratora i wtedy musi on by wpisany w polu NIP. Aktualnie możliwe jest przeprowadzenie integracji wyłącznie ze środowiskiem testowym KSeF. Oczywiście docelowo możliwe będzie takie skonfigurowanie kluczy API, aby poprawnie działały z środowiskiem produkcyjnym KSeF.

token KSeF konfiguracja

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
JavaScript (Node.js)
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 VAT) z wykorzystaniem API,
getWhitelistStatus – funkcja do sprawdzania statusu rachunku bankowego podmiotu w wykazie podatników VAT (tzw. białej liście VAT) z wykorzystaniem pliku płaskiego,
searchVATRegistry – funkcja do wyszukiwania i pobierania danych w wykazie podatników VAT Ministerstwa Finansów,
getKRSData – funkcja umożliwia pobranie aktualnego odpisu zawierającego pełne dane przedsiębiorcy lub stowarzyszenia udostępnionych przez Krajowego Rejestru Sądowego (Otwarte API KRS). Uwaga! Funkcja dostępna tylko w planach indywidudalnych.
getKRSSection – funkcja umożliwia pobranie danych z konkretnego działu (1-6) z aktualnego odpisu zawierającego dane przedsiębiorcy lub stowarzyszenia udostępnionych przez Otwarte API Krajowego Rejestru Sądowego (Otwarte API KRS).
getAccountStatus – funkcja do pobierania aktualnych informacji dotyczących konta użytkownika.

Integracja

Wszystkie biblioteki wraz z kodami źródłowymi są dostępne do pobrania na stronie Pobierz. Ponadto, kody źródłowe bibliotek są również dostępne w naszym oficjalnym repozytorium w portalu Github.
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.

C#
C/C++
Java
JavaScript
PHP
Python
Visual Basic

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

PM> Install-Package NIP24.NIP24Client

// Brak wsparcia dla centralnego repozytorium

// Maven
// https://www.nip24.pl/maven/

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

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

// NPM
// https://www.npmjs.com/package/nip24client

npm install nip24client

// Packagist (Composer)
// https://packagist.org/packages/nip24/client

composer require nip24/client

# Brak wsparcia dla centralnego repozytorium

pip install nip24-python-client-1.4.1.zip

' 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.

C#
C/C++
Java
JavaScript
PHP
Python
Visual Basic

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");

var NIP24 = require('nip24client');

// 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
var nip24 = new NIP24.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.

Zapytanie o bieżący status działalności firmy

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 aktywną działalność, zarejestrowaną w rejestrze REGON, 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.

C#
C/C++
Java
JavaScript
PHP
Python
Visual Basic

// 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
nip24.isActiveExt(NIP24.Number.NIP, '123-456-78-90').then((active) => {
	console.log(active ? 'Firma prowadzi aktywną działalność' : 'Firma zawiesiła lub zakończyła działalność');
}).catch((e) => {
	console.log(e.message);
});

// 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

Zapytanie o dane do faktury

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) oraz wartość szukanego numeru. Wywołując funkcję system odpytuje bezpośrednio referencyjną bazę danych, co gwarantuje pobranie zawsze najaktualniejszych danych.

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

C#
C/C++
Java
JavaScript
PHP
Python
Visual Basic

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

if (invoice != null) {
	Console.WriteLine("Nazwa: " + invoice.Name);
	Console.WriteLine("Imię i nazwisko: " + invoice.FirstName + " " + invoice.LastName);
	Console.WriteLine("Adres : " + invoice.PostCode + " " + invoice.PostCity + " " + invoice.Street
		+ " " + invoice.StreetNumber);
	Console.WriteLine("NIP: " + invoice.NIP);
}
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", TRUE);

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");

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());
}
else {
	System.out.println("Błąd: " + nip24.getLastError());
}

// Wywołanie metody zwracającej dane do faktury
nip24.getInvoiceDataExt(NIP24.Number.NIP, '123-456-78-90').then((invoice) => {
	console.log(invoice.toString());
}).catch((e) => {
	console.log(e.message);
});

// Wywołanie metody zwracającej dane do faktury
$invoice = $nip24->getInvoiceDataExt(\NIP24\Number::NIP, '123-456-78-90');

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>';
}
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')

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
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")

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

Zapytanie o szczegółowe dane firmy

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) oraz wartość szukanego numeru. Wywołanie funkcji powoduje, że system odpytuje bezpośrednio referencyjną bazę danych w GUS, co gwarantuje pobranie zawsze aktualnych danych.

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

C#
C/C++
Java
JavaScript
PHP
Python
Visual Basic

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

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", TRUE);

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");

if (all != null) {
	System.out.println(all);
}
else {
	System.out.println("Błąd: " + nip24.getLastError());
}

// Wywołanie metody zwracającej szczegółowe dane firmy
nip24.getAllDataExt(NIP24.Number.NIP, '123-456-78-90').then((all) => {
	console.log(all.toString());
}).catch((e) => {
	console.log(e.message);
});

// Wywołanie metody zwracającej szczegółowe dane firmy
$all = $nip24->getAllDataExt(\NIP24\Number::NIP, '123-456-78-90');

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')

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")

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 (registryEntity),
symbol i nazwę rejestru lub ewidencji (m.in. CEIDG, KRS) (registry),
datę wpisu i numer w rejestrze lub ewidencji (m.in. numer KRS) (record),
symbol i nazwę podstawowej formy prawnej (basicLegalForm),
symbol i nazwę szczególnej formy prawnej (specificLegalForm),
symbol i nazwę formy własności (ownershipForm),
dane wspólników spółek cywilnych (businessPartners)
listę kodów PKD (Polska Klasyfikacja Działalności) (PKDs).

Potwierdzenie aktywności numeru VAT EU

Potwierdzenie aktywności numeru VAT EU realizowane jest poprzez wywołanie funkcji getVIESData(), której parametrem jest numer VAT EU, który chcemy zweryfikować. Funkcja umożliwia weryfikację numerów VAT EU nadawanych przez wszystkie kraje członkowskie Unii Europejskiej.

Interpretacja zwracanych wartości:

uid – unikalny identyfiaktor zapytania generowany przez nip24.pl,
countryCode – kod kraju w którym jest zarejestrowana firma skojarzona z numerem EU VAT podanym w zapytaniu,
vatNumber- numer EU VAT weryfikowanej firmy podany w zapytaniu,
valid – odpowiedź z serwisu VIES, informująca o aktualnym statusie EU VAT sprawdzanego podmiotu:
- true – podany w zapytaniu numer EU VAT jest ważny,
- false – podany w zapytaniu numer EU VAT jest nie ważny,
traderName – nazwa handlowa firmy,
traderCompanyType – zawsze zwracany ciąg znaków ’–’,
traderAddress – adres firmy pod którym jest zarejestrowana firma,
id – unikalny identtyfikator zapytania generowany przez system VIES
date – data wykonania zapytania
source – źródło danych

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

C#
C/C++
Java
JavaScript
PHP
Python
Visual Basic

// 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
nip24.getVIESData('PL1234567890').then((vies) => {
	console.log(vies.toString());
}).catch((e) => {
	console.log(e.message);
});

// 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

Sprawdzenie statusu podmiotu w rejestrze VAT

Sprawdzenie statusu podmiotu realizowane jest poprzez wywołanie funkcji getVATStatus(), której parametrami są: typ szukanego numeru (NIP, REGON lub KRS) oraz wartość szukanego numeru. Dane pobierane są bezpośrednio z Portalu Podatkowego Ministerstwa Finansów. Wywołanie funkcji z parametrem NIP powoduje, że system odpytuje bezpośrednio Portal Podatkowy Ministerstwa Finansów, co gwarantuje najszybsze sprawdzenie statusu.

Interpretacja zwracanych wartości:

nip – numer NIP firmy dla którego realizowane było zapytanie,
regon – numer REGON firmy,
name – nazwa firmy skojarzona z podanym numerem NIP,
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.”,
id – identyfikator odpowiedzi (requestId) z serwisu Ministerstwa Finansów – potwierdza wykonanie zapytania,
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.

C#
C/C++
Java
JavaScript
PHP
Python
Visual Basic

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

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");

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
nip24.getVATStatusExt(NIP24.Number.NIP, '123-456-78-90').then((vat) => {
	console.log(vat.toString());
}).catch((e) => {
	console.log(e.message);
});

// Sprawdzenie statusu firmy w rejestrze VAT
$vat = $nip24->getVATStatusExt(\NIP24\Number::NIP, '123-456-78-90');

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')

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")

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

Sprawdzanie statusu rachunku bankowego podmiotu w wykazie podatników VAT (tzw. białej liście VAT) z wykorzystaniem API

Sprawdzenie statusu rachunku bankowego podmiotu realizowane jest poprzez wywołanie funkcji getIBANStatus(), której parametrami są: typ szukanego numeru (NIP, REGON lub KRS), wartość szukanego numeru, numer rachunku bankowego do sprawdzenia oraz data, której ma dotyczyć sprawdzenie. Dane pobierane są bezpośrednio z wykazu podatników VAT (tzw. białej listy podatników VAT) Ministerstwa Finansów. Wywołanie funkcji z parametrem NIP lub REGON powoduje, że system odpytuje bezpośrednio wykaz podatników VAT, co gwarantuje najszybsze sprawdzenie statusu.

Interpretacja zwracanych wartości:

nip – numer NIP firmy dla którego realizowane było zapytanie,
regon – numer REGON firmy,
iban- numer IBAN sprawdzanego rachunku bankowego,
valid – odpowiedź z serwisu Ministerstwa Finansów, bieżący status sprawdzanego podmiotu:
- true – podany w zapytaniu NIP/REGON pasuje do wskazanego rachunku bankowego,
- false – podany w zapytaniu NIP/REGON nie pasuje do wskazanego rachunku bankowego,,
id – identyfikator odpowiedzi (requestId) z serwisu Ministerstwa Finansów – potwierdza wykonanie zapytania,
date – data sprawdzenia powiązania numeru NIP/REGON z numerem konta bankowego podmiotu,
source – źródło odpowiedzi (adres URL interfejsu API MF).

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

C#
C/C++
Java
JavaScript
PHP
Python
Visual Basic

// Wywołanie metody zwracającej informacje o rachunku bankowym
IBANStatus iban = nip24.GetIBANStatus(Number.NIP, "123-456-78-90", "12 1234 1234 1234 1234 1234 1234",
	new DateTime(2019, 9, 1));

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);
}

// Wywołanie metody zwracającej informacje o rachunku bankowym
IBANStatus* iban = nip24_get_iban_status(nip24, NIP, "123-456-78-90", "12 1234 1234 1234 1234 1234 1234",
	time(NULL));

if (iban != NULL) {
	printf("NIP: %s\n", iban->NIP);
	printf("IBAN: %s\n", iban->IBAN);
	printf("Aktywny: %d\n", iban->Valid);
}
else {
	printf("Błąd: %s\n", nip24_get_last_err(nip24));
}

// Wywołanie metody zwracającej informacje o rachunku bankowym
IBANStatus iban = nip24.getIBANStatus(Number.NIP, "123-456-78-90", "12 1234 1234 1234 1234 1234 1234",
	new Date(2019, 9, 1));

if (iban != null) {
	System.out.println("NIP kontrahenta: " + iban.getNIP());
	System.out.println("Numer rachunku bankowego: " + iban.getIBAN());
	System.out.println("Status konta bankowego: " + iban.isValid());
	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());
}

// Wywołanie metody zwracającej informacje o rachunku bankowym
nip24.getIBANStatusExt(NIP24.Number.NIP, '123-456-78-90', '12 1234 1234 1234 1234 1234 1234',
	'2019-09-01').then((iban) => {
	
	console.log(iban.toString());
}).catch((e) => {
	console.log(e.message);
});

// Wywołanie metody zwracającej informacje o rachunku bankowym
$iban = $nip24->getIBANStatusExt(\NIP24\Number::NIP, '123-456-78-90', '12 1234 1234 1234 1234 1234 1234',
	'2019-09-01');

if ($iban) {
	echo '<p>IBAN: ' . print_r($iban, true) . '</p>';
}
else {
	echo '<p>Błąd: ' . $nip24->getLastError() . '</p>';
}

# Wywołanie metody zwracającej informacje o rachunku bankowym
iban = nip24.getIBANStatusExt(Number.NIP, '123-456-78-90', '12 1234 1234 1234 1234 1234 1234', '2019-09-01')

if iban:
    pprint(vars(iban))
else:
    print u'Błąd: ' + nip24.getLastError()

' Wywołanie metody zwracającej informacje o rachunku bankowym
Dim iban As IBANStatus
Set iban = nip24.GetIBANStatus(Number_NIP, "123-456-78-90", "12 1234 1234 1234 1234 1234 1234", "2019-09-01")

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

Sprawdzanie statusu rachunku bankowego podmiotu w wykazie podatników VAT (tzw. białej liście VAT) z wykorzystaniem pliku płaskiego

W odróżnieniu od funkcji getIBANStatus(), która sprawdza status rachunku bankowego kontrahenta z wykorzystaniem API, funkcja getWhitelistStatus() sprawdza poprawność numeru konta bankowego kontrahenta w wykazie podatników VAT (tzw. białej listy podatników VAT) z wykorzystaniem pliku płaskiego publikowanego przez Ministerstwo Finansów. Uwaga! Funkcja nie posiada żadnych limitów dotyczących wywołania.

Interpretacja zwracanych wartości:

uid – identyfikator zapytania z systemu nip24.pl,
nip – numer NIP firmy dla którego realizowane było zapytanie,
iban – znormalizowany (bez spacji) numer IBAN konta bankowego kontrahenta, który został podany w zapytaniu,
valid – informacja zwrotana czy rachnek bankowy figuruje w wykazie VAT i jest przypisany do danego kontrahenta:
- true – podany w zapytaniu NIP pasuje do wskazanego rachunku bankowego,
- false – podany w zapytaniu NIP nie pasuje do wskazanego rachunku bankowego,
virtual – informacja o typie rachunku bankowego. Dwie możliwe wartości wirtualny (true) czy standardowy (false),
status – liczbowy status VAT podatnika:
- status = 1, podatnik nie figuruje w wykazie VAT (białej liście),
- status = 2, podatnik jest czynnym płatnikiem VAT,
- status = 3, podatnik jest zwolniony z podatku VAT,
result – opisowy status VAT podatnika:
- Podmiot o podanym identyfikatorze podatkowym NIP nie jest zarejestrowany jako podatnik VAT lub podany rachunek bankowy nie figuruje w wykazie VAT (tzw. białej liście),
- Podmiot o podanym identyfikatorze podatkowym NIP jest zarejestrowany jako podatnik VAT czynny,
- Podmiot o podanym identyfikatorze podatkowym NIP jest zarejestrowany jako podatnik VAT zwolniony,
hashIndex – indeks (numer kolejny) znalezionego skrótu w pliku płaskim,
maskIndex – indeks (numer kolejny) znalezionej maski w pliku płaskim (tylko dla numerów wirtualnych),
date – data sprawdzenia powiązania numeru NIP z numerem konta bankowego kontrahenta (w formacie: rrrr-mm-dd), maksymalnie można weryfikować kontrahentów na 90 dni wstecz,
source – informacja o adresie URL pliku płaskiego wykorzystanego do weryfikacji.

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

C#
C/C++
Java
JavaScript
PHP
Python
Visual Basic

// Wywołanie metody sprawdzającej status podmiotu na białej liście podatników VAT
WLStatus whitelist = nip24.GetWhitelistStatus(Number.NIP, "123-456-78-90", "12 1234 1234 1234 1234 1234 1234",
	new DateTime(2019, 9, 1));

if (whitelist != null) {
	Console.WriteLine("NIP kontrahenta: " + whitelist.NIP);
	Console.WriteLine("Numer rachunku bankowego: " + whitelist.IBAN);
	Console.WriteLine("Status konta bankowego: " + whitelist.Valid);
	Console.WriteLine("Status VAT: " + whitelist.Result);
	Console.WriteLine("Data sprawdzenia: " + whitelist.Date);
	Console.WriteLine("Źródło: " + whitelist.Source);
}
else {
	Console.WriteLine("Błąd: " + nip24.LastError);
}

// Wywołanie metody sprawdzającej status podmiotu na białej liście podatników VAT
WLStatus* whitelist = nip24_get_whitelist_status(nip24, NIP, "123-456-78-90", "12 1234 1234 1234 1234 1234 1234",
	time(NULL));

if (whitelist != NULL) {
	printf("NIP: %s\n", whitelist->NIP);
	printf("IBAN: %s\n", whitelist->IBAN);
	printf("Aktywny: %d\n", whitelist->Valid);
}
else {
	printf("Błąd: %s\n", nip24_get_last_err(nip24));
}

// Wywołanie metody sprawdzającej status podmiotu na białej liście podatników VAT
WLStatus whitelist = nip24.getWhitelistStatus(Number.NIP, "123-456-78-90", "12 1234 1234 1234 1234 1234 1234",
	new Date(2019, 9, 1));

if (whitelist != null) {
	System.out.println("NIP kontrahenta: " + whitelist.getNIP());
	System.out.println("Numer rachunku bankowego: " + whitelist.getIBAN());
	System.out.println("Status konta bankowego: " + whitelist.isValid());
	System.out.println("Status VAT: " + whitelist.getResult());
	System.out.println("Data sprawdzenia: " + whitelist.getDate());
	System.out.println("Źródło: " + whitelist.getSource());
}			
else {
	System.out.println("Błąd: " + nip24.getLastError());
}

// Wywołanie metody sprawdzającej status podmiotu na białej liście podatników VAT
nip24.getWhitelistStatusExt(NIP24.Number.NIP, '123-456-78-90', '12 1234 1234 1234 1234 1234 1234',
	'2019-09-01').then((whitelist) => {
	
	console.log(whitelist.toString());
}).catch((e) => {
	console.log(e.message);
});

// Wywołanie metody sprawdzającej status podmiotu na białej liście podatników VAT
$whitelist = $nip24->getWhitelistStatusExt(\NIP24\Number::NIP, '123-456-78-90',
	'12 1234 1234 1234 1234 1234 1234', '2019-09-01');

if ($whitelist) {
	echo '<p>IBAN: ' . print_r($whitelist, true) . '</p>';
}
else {
	echo '<p>Błąd: ' . $nip24->getLastError() . '</p>';
}

# Wywołanie metody sprawdzającej status podmiotu na białej liście podatników VAT
whitelist = nip24.getWhitelistStatusExt(Number.NIP, '123-456-78-90', '12 1234 1234 1234 1234 1234 1234',
	'2019-09-01')

if whitelist:
    pprint(vars(whitelist))
else:
    print u'Błąd: ' + nip24.getLastError()

' Wywołanie metody sprawdzającej status podmiotu na białej liście podatników VAT
Dim whitelist As WLStatus
Set whitelist = nip24.GetWhitelistStatus(Number_NIP, "123-456-78-90", "12 1234 1234 1234 1234 1234 1234",
	"2019-09-01")

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

Wyszukiwanie danych w rejestrze VAT Ministerstwa Finansów

Wyszukiwanie i pobieranie danych firmy z rejestru VAT Ministerstwa Finansów realizowane jest poprzez wywołanie funkcji searchVATRegistry(), której parametrami wejściowymi są:

type – typ numeru (NIP, REGON, KRS, IBAN) po którym realizowane będzie wyszukiwanie,
number – numer określonego typu,
date – data (opcjonalna, brak – dzień bieżący).

Dane pobierane są bezpośrednio z wykazu podatników VAT (tzw. białej listy podatników VAT) Ministerstwa Finansów.

Interpretacja zwracanych wartości:

uid – unikalny identyfikator zapytania nadany przez serwis nip24.pl,
name – firma (nazwa) lub imię i nazwisko,
nip (opcjonalnie) – numer NIP firmy dla którego realizowane było zapytanie,
regon (opcjonalnie) – numer identyfikacyjny REGON,
krs (opcjonalnie) – numer KRS, jeżeli został nadany,
residenceAddress (opcjonalnie) – pełny adres siedziby wraz z kodem pocztowym,
workingAddress (opcjonalnie) – adres stałego miejsca prowadzenia działalności lub adres miejsca zamieszkania w przypadku braku adresu stałego miejsca prowadzenia działalności,
vatStatus – liczbowy status VAT podatnika:
- 1 – podatnik nie figuruje w wykazie VAT (białej liście),
- 2 – podatnik jest czynnym płatnikiem VAT,
- 3 – podatnik jest zwolniony z podatku VAT,
vatResult – opisowy status VAT podatnika:
- dla vatStatus = 1 – tekst „Niezarejestrowany”,
- dla vatStatus = 2 – tekst „Czynny”,
- dla vatStatus = 3 – tekst „Zwolniony”,
representatives (opcjonalnie) – imiona i nazwiska osób wchodzących w skład organu uprawnionego do reprezentowania podmiotu oraz ich numery NIP,
authorizedClerks (opcjonalnie) – imiona i nazwiska prokurentów oraz ich numery NIP,
partners (opcjonalnie) imiona i nazwiska lub firmę (nazwa) wspólnika oraz jego numer NIP,
registrationLegalDate (opcjonalnie) – data rejestracji jako podatnika VAT,
registrationDenialDate (opcjonalnie) – data odmowy rejestracji jako podatnika VAT,
registrationDenialBasis (opcjonalnie) – podstawa prawna odmowy rejestracji,
restorationDate (opcjonalnie) – data przywrócenia jako podatnika VAT,
restorationBasis (opcjonalnie) – podstawa prawna przywrócenia jako podatnika VAT,
removalDate (opcjonalnie) – data wykreślenia odmowy rejestracji jako podatnika VAT,
removalBasis (opcjonalnie) – podstawa prawna wykreślenia odmowy rejestracji jako podatnika VAT,
ibans- numer(y) IBAN kont bankowych przypisanych do danej firmy, zgłoszone jako konta firmowe do białej listy podatników VAT,
hasVirtualAccounts (opcjonalnie) – podmiot posiada maski kont wirtualnych,
id – identyfikator odpowiedzi (requestId) z serwisu Ministerstwa Finansów – potwierdza wykonanie zapytania,
date – data sprawdzenia powiązania numeru NIP/REGON z numerem konta bankowego podmiotu,
source – źródło odpowiedzi (adres URL interfejsu API MF).

Uwaga! Korzystanie z funkcji może zostać ograniczone ze względu na limity nałożone przez Ministerstwo Finansów na API wykazu podatników VAT.

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

C#
C/C++
Java
PHP
Python
Visual Basic

// Wywołanie metody wyszukującej dane w rejestrze VAT
SearchResult result = nip24.SearchVATRegistry(Number.NIP, "123-456-78-90");

if (result != null) {
	Console.WriteLine(result);
}
else {
	Console.WriteLine("Błąd: " + nip24.LastError + " (kod: " + nip24.LastErrorCode + ")");
}

// Wywołanie metody wyszukującej dane w rejestrze VAT
SearchResult* result = nip24_search_vat_registry(nip24, NIP, "123-456-78-90", 0);

if (result != NULL) {
	printf("Wyniki: %d\n", result->ResultsCount);

	if (result->ResultsCount > 0) {
		printf("Nazwa: %s\n", result->Results.VATEntity[0]->Name);
		printf("NIP: %s\n", result->Results.VATEntity[0]->NIP);

		if (result->Results.VATEntity[0]->IBANsCount > 0) {
			printf("IBAN: %s\n", result->Results.VATEntity[0]->IBANs[0]);
		}

		printf("Status: %d\n", result->Results.VATEntity[0]->VATStatus);
		printf("Wynik: %s\n", result->Results.VATEntity[0]->VATResult);
	}
}
else {
	printf("Błąd: %s (kod: %d)\n", nip24_get_last_err(nip24), nip24_get_last_err_code(nip24));
}

// Wywołanie metody wyszukującej dane w rejestrze VAT
SearchResult result = nip24.searchVATRegistry(Number.NIP, "123-456-78-90");

if (result != null) {
	System.out.println(result);
}			
else {
	System.err.println("Błąd: " + nip24.getLastError() + " (kod: " + nip24.getLastErrorCode() + ")");
}

// Wywołanie metody wyszukującej dane w rejestrze VAT
$result = $nip24->searchVATRegistryExt(\NIP24\Number::NIP, '123-456-78-90');

if ($result) {
	echo '<pre>' . print_r($result, true) . '</pre>';
}
else {
	echo '<p>Błąd: ' . $nip24->getLastError() . ' (kod: ' . $nip24->getLastErrorCode() . ')</p>';
}

# Wywołanie metody wyszukującej dane w rejestrze VAT
result = nip24.searchVATRegistryExt(Number.NIP, '123-456-78-90')

if result:
    print(result)
else:
    print('Błąd: ' + nip24.getLastError() + ' (kod: ' + str(nip24.getLastErrorCode()) + ')')

' Wywołanie metody wyszukującej dane w rejestrze VAT
Dim result As SearchResult
Set result = nip24.SearchVATRegistry(Number_NIP, "123-456-78-90")

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

Pobieranie danych z KRS

Zakres informacyjny danych udostępnianych z KRS poprzez API odpowiada odpisowi aktualnemu, króry jest wydawany przez Centralną Informację Krajowego Rejestru Sądowego.

Pobrane poprzez API dane osób fizycznych ujawnionych w rejestrze są zanonimizowane w zakresie imion, nazwisk i ich numerów PESEL, zgodnie z zasadami przetwarzania tych danych wynikających z Rozporządzenia Parlamentu Europejskiego i Rady (UE) 2016/679 z dnia 27 kwietnia 2016 r. w sprawie ochrony osób fizycznych w związku z przetwarzaniem danych osobowych i w sprawie swobodnego przepływu takich danych oraz uchylenia dyrektywy 95/46/WE (ogólne rozporządzenie o ochronie danych) (Dz. Urz. UE L 119 z 04.05.2016 ze zm.)

Wyszukiwanie i pobieranie aktualnego odpisu KRS przedsiębiorcy lub stowarzyszenia z Otwartego API Krajowego Rejestru Sądowego, może być realizowane z wykorzystaniem dwóch funkcji: getKRSData() oraz getKRSSection().

Pobranie wszystkich danych aktualnego odpisu KRS

Uwaga! Funkcja dostępna jest wyłącznie w planach Indywidualnych. W planach standrdowych dostępna jest natomiast funkcja getKRSSection(), która została opisana poniżej.

Funkcja getKRSData(type, number) umożliwia pobranie danych zapisanych we wszystkich działach aktualnego odpisu KRS dla danego przedsiębiorcy lub stowarzyszenia. Parametrami wejściowymi funkcji są:

type – typ numeru (NIP, REGON, KRS) po którym realizowane będzie wyszukiwanie,
number – konkretny numer określonego typu,

Interpretacja zwracanych wartości:

uid – identyfikator zapytania z systemu nip24.pl,
date – data i czas zwrócenia odpowiedzi,
source – źródło danych jako URL,
data – zawiera obiekt Odpis, obiekt ten zawiera następujące atrybuty i klasy:
- rodzaj – informacja czy odpis jest Aktualny czy Pełny. Na ten moment serwis nip24.pl daje możliwość odpytywania tylko o aktualne odpisy
- naglowekA – zawiera ogólne informacje opisujące odpis, takie jak: rejestr, numer KRS, data i czas wygenerowania odpisu, stan na dzień, data rejestracji w KRS oraz numer i datę ostatniego wpisu, a także sygnaturę akt sprawy dotyczacej ostatniego wpisu.
- dane – zawiera obiekt Dane, obiekt ten zawiera atrybuty odpowiadające każdemu z działów, który może (poszczególne klasy i atrybuty są opcjonalne i zależą m.in. od formy prawnej podmiotu) zawierać następujące klasy i atrybuty:
  - Dzial1:
    - organSprawujacyNadzor
      - nazwaOrganu
      - sklad
        
        nazwisko
        
        imiona
        
        identyfikator
        
        funkcjaWOrganie
        
        czyZawieszona
    - danePodmiotu
      - formaPrawna
      - nazwa
      - czyProwadziDzialalnoscZInnymiPodmiotami
      - czyPosiadaStatusOPP
      - identyfikatory
      - daneOWczesniejszejRejestracji
    - siedzibaIAdres
      - ulica
      - nrDomu
      - nrLokalu
      - miejscowosc
      - kodPocztowy
      - poczta
      - kraj
    - jednostkiTerenoweOddzialy
      - nazwa
      - siedziba
      - adres
    - umowaStatut
      - informacjaOZawarciuZmianieUmowyStatutu
    - pozostaleInformacje
      - czasNaJakiUtworzonyZostalPodmiot
      - informacjaOLiczbieUdzialow
      - czyUmowaStatutPrzyznajeUprawnieniaOsobiste
      - czyObligatoriuszeMajaPrawoDoUdzialuWZysku
    - wspolnicySpzoo
      - nazwisko
      - imiona
      - identyfikator
      - posiadaneUdzialy
      - czyPosiadaCaloscUdzialow
    - jedynyAkcjonariusz
      - nazwa
      - krs
      - czyPosiadaCaloscAkcji
      - identyfikator
    - sposobPowstaniaPodmiotu
      - okolicznosciPowstania
      - opisSposobuPowstaniaInformacjaOUchwale
      - nrDataDecyzjiPrezesaUOKiK
      - podmioty
        
        nazwa
        
        krajNazwaRejestruEwidencji
        
        numerWRejestrzeAlboEwidencji
        
        nazwaSaduOrganuProwadzacegoRejestrEwidencje
        
        identyfikatory
    - kapital
      - wniesioneAporty
      - lacznaLiczbaAkcjiUdzialow
      - wysokoscKapitaluZakladowego
      - wartoscJednejAkcji
      - czescKapitaluWplaconegoPokrytego
    - emisjeAkcji
      - nazwaSeriiAkcji
      - liczbaAkcjiWSerii
      - czyAkcjeUprzywilejowaneLiczbaAkcjiRodzajUprzywilejowania
    - wzmiankaOPodjeciuUchwalyOEmisjachObligacjiZamiennych
      - dataPodjeciaUchwaly
    - wzmiankaOUpowaznieniuDoEmisjiWarrantowSubskrypcyjnych
      - czyZarzadJestUprawnionyDoEmisjiWarrantowSubskrypcyjnych
  - Dzial2:
    - nazwaOrganu
    - reprezentacja
      - nazwaOrganu
      - sposobReprezentacji
      - sklad
        
        nazwisko
        
        imiona
        
        identyfikator
        
        funkcjaWOrganie
        
        czyZawieszona
    - prokurenci
      - rodzajProkury
      - osoba
        
        nazwisko
        
        imiona
        
        identyfikator
  - Dzial3:
    - celDzialalnosciOrganizacji
    - informacjaODniuKonczacymRokObrotowy
    - przedmiotDzialalnosci
      - przedmiotPrzewazajacejDzialalnosci
      - przedmiotPozostalejDzialalnosci
    - przedmiotDzialalnosciOPP
      - nieodplatnyPkd
      - odplatnyPkd
    - sprawozdaniaGrupyKapitalowej
      - wzmiankaOZlozeniuOpiniiBieglegoRewidentaSprawozdaniaZBadania
      - wzmiankaOZlozeniuSkonsolidowanegoRocznegoSprawozdaniaFinansowego
      - wzmiankaOZlozeniuSkonsolidowanegoSprawozdaniaZPlatnosciNaRzeczAdministracjiPublicznej
      - wzmiankaOZlozeniuSprawozdaniaZDzialalnosciSpolkiDominujacej
      - wzmiankaOZlozeniuUchwalyPostanowieniaOZatwierdzeniuSkonsolidowanegoRocznegoSprawozdaniaFinansowego
    - wzmiankiOZlozonychDokumentach
      - wzmiankaOZlozeniuOpiniiBieglegoRewidentaSprawozdaniaZBadania
      - wzmiankaOZlozeniuRocznegoSprawozdaniaFinansowego
      - wzmiankaOZlozeniuUchwalyPostanowieniaOZatwierdzeniuRocznegoSprawozdaniaFinansowego
      - wzmiankaOZlozeniuSprawozdaniaZDzialalnosci
  - Dzial4:
    - zabezpieczenieMajatkuOddalenieWnioskuOUpadlosc
      - oddalenieWnioskuOUpadlosc
      - dalszePelnienieFunkcjiPoUkonczeniuPostepowaniaRestrukturyzacyjnego
      - zabezpieczenieMajatkuDluznikaWPostepowaniuUpadlosciowym
    - zaleglosci
      - charakterZaleglosci
      - zakonczenieEgzekucji
      - wszczecieEgzekucji
      - umorzenieEgzekucji
      - wysokoscZaleglosci
  - Dzial5:
    - kurator
      - nazwisko
      - imiona
      - identyfikator
      - podstawaPowolaniaZakresDzialania
      - dataPowolania
      - dataDoKtorejMaDzialac
  - Dzial6:
    - postepowanieUpadlosciowe
      - sposobProwadzeniaPostepowania
      - informacjaOUchyleniuUkladu
      - informacjaOOgloszeniuUpadlosci
        
        organWydajacy
        
        sygnatura
        
        data
      - opisZakonczeniaProcesuUpadlosci
        
        opisSposobuZakonczeniaPostepowania
        
        dataZakonczeniaPostepowania
      - daneSyndyka
        
        nazwisko
        
        imiona
        
        identyfikator
        
        podmiot
    - polaczeniePodzialPrzeksztalcenie
      - okreslenieOkolicznosci
      - opisPolaczeniaPodzialuPrzeksztalcenia
      - podmiotyPrzejmowane
    - likwidacja
      - otwarcieLikwidacji
      - sposobReprezentacjiPodmiotuPrzezLikwidatorow
      - likwidatorzy
    - rozwiazanieUniewaznienie
      - okreslenieOkolicznosci
      - informacjaORozwiazaniuUniewaznieniu
    - zawieszenieWznowienie
      - dataZawieszenia
      - dataWznowienia
    - postepowanieUkladowe
      - uchylenieUkladu
      - otwarciePostepowaniaUkladowego
        
        organWydajacy
        
        sygnatura
        
        dataNadaniaKlauzuliWykonalnosci
      - zakonczeniePostepowaniaUkladowego
        
        data
        
        opis
    - postepowanieRestrukturyzacyjneNaprawczePrzymusowaRestrukturyzacja
      - uchylenieUkladu
      - otwarciePostepowaniaRestrukturyzacyjnegoNaprawczegoPrzymusowejRestrukturyzacji
        
        organWydajacy
        
        sygnatura
        
        dataNadaniaKlauzuliWykonalnosci
        
        rodzajPostepowania
      - zakonczeniePostepowaniaRestrukturyzacyjnegoNaprawczegoPrzymusowejRestrukturyzacji
        
        data
        
        opis

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

C#
Java
PHP

// Wywołanie metody pobierającej pełne dane z KRS
KRSData result = nip24.GetKRSData(Number.KRS, "0000966600");

if (result != null) {
	Console.WriteLine(result);
}
else {
	Console.WriteLine("Błąd: " + nip24.LastError + " (kod: " + nip24.LastErrorCode + ")");
}

// Wywołanie metody pobierającej pełne dane z KRS
KRSData* result = nip24_get_krs_data(nip24, KRS, "0000966600");

if (result != NULL) {
	printf("Numer KRS: %s\n", result->data->naglowekA->NumerKRS);
	printf("Nazwa: %s\n", result->data->danePodmiotu->Nazwa);
}
else {
	printf("Błąd: %s (kod: %d)\n", nip24_get_last_err(nip24), nip24_get_last_err_code(nip24));
}

// Wywołanie metody pobierającej pełne dane z KRS
KRSData result = nip24.getKRSData(Number.KRS, "0000966600");

if (result != null) {
	System.out.println(result);
}			
else {
	System.err.println("Błąd: " + nip24.getLastError() + " (kod: " + nip24.getLastErrorCode() + ")");
}

// Wywołanie metody pobierającej pełne dane z KRS
$result = $nip24->getKRSData(\NIP24\Number::KRS, '0000966600');

if ($result) {
	echo '<pre>' . print_r($result, true) . '</pre>';
}
else {
	echo '<p>Błąd: ' . $nip24->getLastError() . ' (kod: ' . $nip24->getLastErrorCode() . ')</p>';
}

Pobranie danych z konkretnego działu aktualnego odpisu KRS

Funkcja getKRSSection() umożliwia pobranie danych zapisanych we wszystkich działach aktualnego odpisu KRS dla danego przedsiębiorcy lub stowarzyszenia. Parametrami wejściowymi funkcji są:

type – typ numeru (NIP, REGON, KRS) po którym realizowane będzie wyszukiwanie,
number – konkretny numer określonego typu,
section – numer działu, możliwe wartości z przedziału [1-6]

Uwaga! Opis poszczególnych pól zwracanych w ramach wywołania funkcji dla poszczególnego działu jest zgodny z opisem zawartym powyżej (dla funkcji getKRSData()).

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

C#
Java
PHP

// Wywołanie metody pobierającej dane konkretnego działu z aktualnego odpisu KRS (np. dział 1)
KRSData result = nip24.GetKRSSection(Number.KRS, "0000966600", 1);

if (result != null) {
	Console.WriteLine(result);
}
else {
	Console.WriteLine("Błąd: " + nip24.LastError + " (kod: " + nip24.LastErrorCode + ")");
}

// Wywołanie metody pobierającej dane konkretnego działu z aktualnego odpisu KRS (np. dział 1)
KRSSection* result = nip24_get_krs_section(nip24, KRS, "0000966600", 1);

if (result != NULL) {
	printf("Numer KRS: %s\n", result->data->naglowekA->NumerKRS);
	printf("Nazwa: %s\n", result->data->dane->dzial1.danePodmiotu->Nazwa);
}
else {
	printf("Błąd: %s (kod: %d)\n", nip24_get_last_err(nip24), nip24_get_last_err_code(nip24));
}

// Wywołanie metody pobierającej dane konkretnego działu z aktualnego odpisu KRS (np. dział 1)
KRSData result = nip24.getKRSSection(Number.KRS, "0000966600", 1);

if (result != null) {
	System.out.println(result);
}			
else {
	System.err.println("Błąd: " + nip24.getLastError() + " (kod: " + nip24.getLastErrorCode() + ")");
}

// Wywołanie metody pobierającej dane konkretnego działu z aktualnego odpisu KRS (np. dział 1)
$result = $nip24->getKRSSection(\NIP24\Number::KRS, '0000966600', 1);

if ($result) {
	echo '<pre>' . print_r($result, true) . '</pre>';
}
else {
	echo '<p>Błąd: ' . $nip24->getLastError() . ' (kod: ' . $nip24->getLastErrorCode() . ')</p>';
}

Pobieranie informacji o stanie konta użytkownika

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.

C#
C/C++
Java
JavaScript
PHP
Python
Visual Basic

// 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
nip24.getAccountStatus().then((account) => {
	console.log(account.toString());
}).catch((e) => {
	console.log(e.message);
});

// 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

Rejestracja biblioteki .NET jako obiektu COM

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:

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

Wykorzystanie biblioteki .NET w aplikacji MS Excel

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:

Zarejestrować bibliotekę nip24Library.dll jako obiekt COM w systemie Windows.
Uruchomić aplikację Excel. Na wstążce wybrać zakładkę DEVELOPER, a następnie kliknąć przycisk Visual Basic.
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.
Z menu Insert wybrać Module i w nowym oknie wkleić kod funkcji zaprezentowany w przykładach dla Visual Basic.
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

Dokumentacja

Wprowadzenie

Rejestracja

Logowanie

Generowanie identyfikatora oraz klucza dostępowego

Zapisanie tokenu Krajowego Systemu e-Faktur (KSeF)

Interfejs GUI

Interfejs API

Integracja

Uwierzytelnienie

Zapytanie o bieżący status działalności firmy

Zapytanie o dane do faktury

Zapytanie o szczegółowe dane firmy

Potwierdzenie aktywności numeru VAT EU

Sprawdzenie statusu podmiotu w rejestrze VAT

Sprawdzanie statusu rachunku bankowego podmiotu w wykazie podatników VAT (tzw. białej liście VAT) z wykorzystaniem API

Sprawdzanie statusu rachunku bankowego podmiotu w wykazie podatników VAT (tzw. białej liście VAT) z wykorzystaniem pliku płaskiego

Wyszukiwanie danych w rejestrze VAT Ministerstwa Finansów

Pobieranie danych z KRS

Pobranie wszystkich danych aktualnego odpisu KRS

Pobranie danych z konkretnego działu aktualnego odpisu KRS

Pobieranie informacji o stanie konta użytkownika

Rejestracja biblioteki .NET jako obiektu COM

Wykorzystanie biblioteki .NET w aplikacji MS Excel