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.

pl_PLPolski