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.1Host: www.nip24.pl:443Authorization: MAC id="api_key_id", ts="unix_timestamp", nonce="random_str", mac="b64_calculated_mac_value"User-Agent: NIP24Client/client_version platform_name/platform_versionAccept: 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 typuMIME, w jakim ma być zwrócona odpowiedź, obsługiwane są dwa typy:application/xmliapplication/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") = 0a35fa77fc29c30feb48c4b831929f2f85ed833f56b4617832a09facaca1bd55Funkcja 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 + ':' + keyGdzie:
key_id– identyfikator klucza API (w przypadku środowiska testowego, ciągtest_id),key– klucz API (w przypadku środowiska testowego, ciągtest_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/PL7171642051Gdzie:
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.
Polski 
English (UK)