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

Specyfikacja użytej metody autoryzacji: HTTP Authentication: MAC Access Authentication. Każde zapytanie do naszego serwisu musi być uwierzytelnione tą metodą. Autoryzacja 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="