Wprowadzenie

Udostępnione przez nas API wykorzystuje standardowy protokół HTTP. Wszystkie funkcje API wykorzystują metodę HTTP GET. Każde wywołanie funkcji wymaga autoryzacji zapytania. Dane do autoryzacji zapytania są przesyłane w nagłówku HTTP.

Serwis produkcyjny

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

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.

---

Adres serwisu produkcyjnego: https://www.nip24.pl/api

---

Serwis testowy

Pełną funkcjonalność 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.

---

Adres serwisu produkcyjnego: https://www.nip24.pl/api-test

---

Definicja interfejsu API

Szczegółowa definicja interfejsu API jest dostępna w formacie zgodnym z OpenAPI i można ją pobrać w formie pliku YAML tutaj.

API dostępne jest również w formie interfejsu klienta Swagger UI.

Wykonanie zapytania

Przykład wykonania zapytania do serwisu testowego:

GET /api-test/get/invoice/nip/7171642051 HTTP/1.1 Host: www.nip24.pl:443 Authorization: MAC id="api_key_id", ts="unix_timestamp", nonce="random_str", mac="b64_calculated_mac_value" User-Agent: NIP24Client/client_version platform_name/platform_version Accept: mime_type

Gdzie:

• api_key_id – identyfikator klucza API (na środowisku produkcyjnym wartość identyfikatora wygenerowanego podczas rejestracji, na środowisku testowym wartość test_id),
• unix_timestamp – bieżący czas w formie liczby sekund od tzw. unix epoch,
• random_str – losowy ciąg, różny dla każdego zapytania (min. 8 znaków, max. 16 znaków),
• b64_calculated_mac_value – obliczony HMAC (z użyciem klucza API, na środowisku testowym wartość test_key),
• client_version – wersja klienta API (w naszych bibliotekach to wersja naszej biblioteki API, np. 1.3.0),
• platform_name – nazwa platformy klienta API (w naszych bibliotekach to nazwa języka biblioteki, np. Java, PHP, .NET, Python),
• platform_version – wersja platformy klienta API (w naszych bibliotekach to wersja środowiska biblioteki, np. 1.8.0 dla Java, lub 5.6.4 dla PHP),
• mime_type – nazwa typu MIME, w jakim ma być zwrócona odpowiedź, obsługiwane są dwa typy: application/xml i application/json, jeżeli żądanie nie zawiera nagłówka, domyślnie jest zwracany XML.

Autoryzacja zapytania

Dane autoryzacyjne muszą być przygotowane zgodnie z HTTP Authentication: MAC Access Authentication i jest to zalecana metoda uwierzytelniania. Możliwe jest również użycie metody HTTP Authentication: Basic Authentication, jednak ze względów bezpieczeństwa prosimy o korzystanie z niej tylko wtedy, gdy z jakiegoś powodu użycie pierwszej metody nie jest możliwe.
Każde zapytanie do naszego serwisu musi zostać uwierzytelnione przy użyciu jednej z dwóch dostępnych metod.

Metoda 1 – Uwierzytelnienie z wykorzystaniem MAC Authentication

Specyfikacja użytej metody autoryzacji: HTTP Authentication: MAC Access Authentication. Przygotowanie nagłówka autoryzacyjnego dla zapytania wysłanego do naszego serwisu tą metodą polega na obliczeniu HMAC SHA256 z odpowiednio przygotowanego ciągu i przesłania wyniku w nagłówku HTTP.

Przykład

Ciąg wejściowy do funkcji HMAC ma postać:

ts + '\n' + nonce + '\n' + method + '\n' + path + '\n' + host + '\n' + port + '\n\n'

Gdzie:

• ts – bieżący czas w formie liczby sekund od tzw. unix epoch, należy podawać zawsze bieżący czas wykonywania zapytania (tolerancja serwera +/- 10 min w stosunku do czasu bieżącego),
• nonce – losowy ciąg, różny dla każdego zapytania (min. 8 znaków, max. 16 znaków),
• method – nazwa metody HTTP (zawsze GET),
• path – ścieżka URL zapytania do wykonania,
• host – nazwa serwera NIP24 (zawsze www.nip24.pl),
• port – numer portu serwera NIP24 (zawsze 443),
• '\n' – znak nowej linii (kod ASCII 10 0x0A).

Dla zapytania o dane do faktury dla NIP 7171642051 wysłanego do serwisu testowego dn. 2019-11-25 00:00:00 UTC ciąg wejściowy do funkcji HMAC będzie wyglądał następująco:

str = "1574640000\ndt831hs59s\nGET\n/api-test/get/invoice/nip/7171642051\nwww.nip24.pl\n443\n\n"

Plik z ciągiem wejściowym dla tego przykładu do pobrania tutaj.

Z przygotowanego ciągu obliczamy HMAC SHA256, jako hasło HMAC podajemy klucz API, czyli w przypadku API testowego wartość test_key:

HMAC_SHA256(str, "test_key") = 0a35fa77fc29c30feb48c4b831929f2f85ed833f56b4617832a09facaca1bd55

Funkcja HMAC SHA256 zwraca 32 bajty binarne (powyżej dla czytelności przedstawione jako ciąg heksadecymalny). Plik z wartością binarną do pobrania tutaj.
Wartość binarną obliczonego HMAC należy zakodować algorytmem Base64, otrzymujemy:

CjX6d/wpww/rSMS4MZKfL4Xtgz9WtGF4MqCfrKyhvVU=

Tą wartość należy przesłać jako wartość MAC w nagłówku z danymi do autoryzacji. Ostatecznie:

Authorization: MAC id="test_id", ts="1574640000", nonce="dt831hs59s", mac="CjX6d/wpww/rSMS4MZKfL4Xtgz9WtGF4MqCfrKyhvVU="

Metoda 2 – Uwierzytelnienie z wykorzystaniem Basic Authentication

Specyfikacja stosowanej metody autoryzacji: HTTP Authentication: Basic Authentication. Przygotowanie nagłówka autoryzacyjnego dla zapytania wysłanego do naszego serwisu tą metodą polega na zakodowaniu odpowiednio przygotowanego ciągu funkcją Base64 i przesłania wyniku w nagłówku HTTP.

Przykład

Ciąg wejściowy do funkcji Base64 ma postać:

str = key_id + ':' + key

Gdzie:

• key_id – identyfikator klucza API (w przypadku środowiska testowego, ciąg test_id),
• key – klucz API (w przypadku środowiska testowego, ciąg test_key).

Dla środowiska testowego ciągiem wejściowym dla funkcji Base64 będzie ciąg:

str = "test_id:test_key"

Po zastosowaniu funkcji Base64 otrzymujemy:

Base64(str) = dGVzdF9pZDp0ZXN0X2tleQ==

Tą wartość należy przesłać jako wartość Basic w nagłówku z danymi do autoryzacji. Ostatecznie:

Authorization: Basic dGVzdF9pZDp0ZXN0X2tleQ==

Przykład

Poniższy przykład przedstawia zapytanie, które można wywołać w środowisku testowym z poziomu przeglądarki internetowej. Po prostu skopiuj i wklej go w pasku adresu w przeglądarce:

https://test_id:test_key@www.nip24.pl/api-test/get/vies/euvat/PL7171642051

Gdzie:

• test_id – identyfikator klucza do zastosowania tylko w środowisku testowym. Aby uwierzytelnić się w środowisku produkcyjnym, parametr powinien zawierać poprawny identyfikator klucza używanego do autoryzacji,
• test_key – klucz do zastosowania tylko w środowisku testowym. Aby uwierzytelnić się w środowisku produkcyjnym, parametr powinien zawierać poprawną wartość klucza używanego do autoryzacji.

Identyfikator klucza oraz klucz są generowane przez użytkownika po zalogowaniu się na jego konto w portalu nip24.pl (zakładka Klucze API).
Zobacz stronę dokumentacji, aby uzyskać więcej informacji na temat generowania identyfikatorów i kluczy.

Błędna odpowiedź (error response)

W przypadku jakiegokolwiek błędu związanego z obsługą żądania, zwracany jest następujący komunikat o błędzie:

Szczegółowy opis zwracanych atrybutów:

• code – unikalny kod błędu do automatycznej obsługi błędów,
• description – opis błędu możliwego do przechwycenia przez człowieka,
• details – szczegółowy opis błędu (opcjonalnie),

Kody błędów

Kod błędu	Komunikat błędu	Opis
7	The VAT number is invalid	Podano nieprawidłowy NIP (nie zgadza się suma kontrolna algorytmu)
8	Invalid request format	Błędny format przesłanego żądania
10	Invalid API path	W konfiguracji biblioteki został wpisany błędny adres URL ścieżki do API. Poprawna ścieżka do API produkcyjnego: https://nip24.pl/api/
11	Internal service error	Błąd wewnętrzny serwisu
20	NIP, REGON or KRS number was not provided	Wymagany parametr nie został przesłany w żądaniu
22	EU VAT number is invalid	Podany w parametrze wejściowym numer EU VAT ma niepoprawny format. Zobacz tabelę poprawnych numerów EU VAT
23	Failed to get data from VIES system	Błąd pobierania danych z systemu VIES
26	This feature is not available on the currently selected plan	Funkcja nie jest dostępna w aktualnie wybranym planie. Użyj bezpłatnej funkcji getAccountStatus w celu pobrania informacji o aktualnym stanie konta
27	This function does not support this search mode	Funkcja nie jest dostępna w trybie wyszukiwania
30	Searching by NIP number is not available in the currently selected plan	Wyszukiwanie po numerze NIP nie jest dostępne w aktualnie wybranym planie
33	Querying the given data is not possible in the test mode	Obsłużenie żądania nie jest możliwe w trybie testowym
35	No access query authorization required	Brak dostępu. Wysłanie żądania wymaga poprawnej autoryzacji. Wybierz jedną z dwóch możliwych metod uwierzytelnienia.
36	The service is temporarily unavailable due to scheduled technical work	Usługa niedostępna ze względu na prace serwisowe
43	The number of user queries for the current month could not be retrieved	Błąd podczas pobierania informacji o liczbie aktualnie wykorzystanych żądań
54	Incorrect date or time on the user\s computer or system	Błędna data lub czas na systemie z którego wysyłane zostało żądanie. Poproszę ustawić poprawna datę i czas
55	Invalid MAC string value in header with query credentials	Wartość MAC przesłana w nagłówku nie zgadza się danymi uwierzytelniającymi
57	Invalid key value in header with query credentials	Błędny klucz API w nagłówku żądania
58	The maximum number of concurrent queries for this Member State has been reached	System VIES zwrócił informację o tym, że system podatkowy Państwa Członkowskiego którego dotyczyło żądanie osiągnął w danej chwili limit wydajności. Spróbuj ponownie za chwilę
59	The application at the Member State is not replying or not available	System VIES lub system konkretnego Państwa Członkowskiego nie odpowiada
101	The connection IP number does not match the IP number assigned to the API key	Adres IP z którego zostało wysłane żądanie nie jest zgodny z adresem IP w konfiguracji konta
102	API key is blocked	Użyty do uwierzytelnienia klucz API jest zablokowany
103	Invalid API key	Błędny klucz API
104	The maximum number of queries available for the selected plan has been reached	Maksymalna liczba wykonanych zapytań w danym planie została wykorzystana. Zaloguj się na swoje konto aby dokupić więcej zapytań
105	Account blocked or deleted	Konto zostało zablokowane lub usunięte. Skontaktuj się z biurem obsługi klienta.
106	Invalid account type	Błąd najczęściej zwracany w przypadku niepoprawnie wpisanego identyfikatora. Sprawdź poprawność w wysłanego w żądaniu identyfikatora
107	The pre-paid account has not been paid	Konto użytkownika nie zostało opłacone. Zaloguj się na swoje konto aby opłacić usługi
108	Invalid API key ID	Nie został odnaleziony klucz korespondujący z przesłanym identyfikatorem. Sprawdź poprawność przesłanego w żądaniu identyfikatora
201	Failed to connect to the VIES API service	Błąd połączenia z systemem VIES
202	VIES API service response has invalid format	System VIES zwrócił niepoprawną odpowiedź
203	Invalid number type	Błęndy typ numeryczny
204	NIP is invalid	Błędny numer NIP
205	EU VAT ID is invalid	Błędny numer EU VAT
206	Function generated an exception	Funkcja wygenerowała wyjątek. Skontaktuj się ze wsparciem w celu uzyskania pomocy: kontakt@nip24.pl
207	Date has an invalid format	Format daty jest błędny. Zastosuj format: YYYY-MM-DD HH:MM:SS
208	Invalid input parameter	Błędny parametr wejściowy