8 stycznia 2020 robert

Dokumentacja REST API

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

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

Wszystkie odpowiedzi zwracane przez serwis są w formacie 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.