KSeF REST API – dokumentacja techniczna (integracyjna)
dla Krajowego Systemu e-Faktur
Wprowadzenie
Niniejsza dokumentacja opisuje interfejs REST API umożliwiający kompleksową realizację obsługi faktur ustrukturyzowanych w systemie KSeF.
Szczegółowa definicja interfejsu API jest dostępna w formacie zgodnym z OpenAPI i można ją pobrać w formie pliku JSON.
API dostępne jest również w formie interfejsu klienta Swagger UI.
Rejestracja i utworzenie konta
Aby móc przetestować możliwości REST KSEF API niezbędne jest przeprowadzenie procesu rejestracji, czyli założenia dedykowanego konta w serwisie. W tym celu należy wejść na stronę Rejestracja i wypełnić odpowiedni formularz. Warunkiem koniecznym do korzystania z systemu serwisu jest akceptacja <TODO> Regulaminu. Poprawne wypełnienie formularza i kliknięcie przycisku Zarejestruj powoduje utworzenie konta w systemie oraz automatyczną jego aktywację.
Podczas pierwszego logowania generowany jest automatycznie identyfikator wraz z odpowiadającym mu kluczem. Identyfikator i klucz można znaleźć po zalogowaniu na swoje konto w zakładce Klucze API. Identyfikator ma charakter publiczny i nie wymaga ochrony, natomiast klucz ma charakter prywatny i nie powinien być udostępniany osobom trzecim.
Uwaga! Aby skorzystać z operacji udostępnionych w REST KSEF API, należy zapisać token dostępowy, wygenerowany odpowiednio dla środowiska produkcyjnego lub testowego KSeF oraz włączyć dostęp do danego typu środowiska.
Środowiska
Dla ułatwienia integracji naszym Klientom w obszarze faktur KSeF, przygotowaliśmy dwa tożsame ze sobą środowiska: testowe oraz produkcyjne, które są spięte ze środowiskiem testowym i produkcyjnym KSeF.
Środowisko testowe
Pełną funkcjonalność wszystkich udostępnionych operacji w interfejsie REST KSEF API oraz bibliotek, można sprawdzić korzystając z udostępnionego środowiska testowego.
Środowisko testowe REST KSEF API jest zintegrowane ze środowiskiem testowym Krajowego Systemu e-Faktur i jest dostępne pod adresem: https://ksefapi.pl/api-test/
Wszystkie dostępne w ramach testowego środowiska REST KSEF API operacje są również dostępne z poziomu udostępnionych bibliotek.
Dzięki środowisku testowemu REST KSEF API możliwe jest sprawdzenie wszystkich operacji oferowanych w płatnych pakietach KSeF, bez konieczności ich wykupowania.
Uwaga! Aby skorzystać z operacji REST KSEF API na środowisku testowym, wystarczy zapisać token dostępowy wygenerowany w środowisku testowym KSeF i aktywować dostęp do tego typu środowiska.
Środowisko produkcyjne
Środowisko produkcyjne REST KSEF API jest zintegrowane ze środowiskiem produkcyjnym Krajowego Systemu e-Faktur i jest dostępne pod adresem: https://ksefapi.pl/api/
Uwaga! Aby skorzystać z operacji REST KSEF API na środowisku produkcyjnym, należy zapisać token dostępowy, wygenerowany w środowisku produkcyjnym KSeF, aktywować dostęp do tego typu środowiska oraz wykupić dowolny pakiet KSEF.
Uwierzytelnienie i autoryzacja zapytań
Udostępniony interfejs API wykorzystuje standardowy protokół HTTP. Operacje (metody) API wykorzystują metody HTTP GET lub POST. Każde wywołanie operacji wymaga autoryzacji zapytania. Autoryzacja wykonywanych zapytań możliwa jest na dwa różne sposoby:
- Uwierzytelnienie z wykorzystaniem
MAC Authentication
- Uwierzytelnienie z wykorzystaniem
Basic Authentication
Metoda 1 – 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 (tylko dwie możliwe wartości:GET albo POST),path
– ścieżka URL operacji do wywołania,host
– nazwa serwera usługi API (zawszewww.ksefapi.pl
),port
– numer portu serwera usługi API (zawsze 443),'\n'
– znak nowej linii (kod ASCII 10 0x0A).
Dla wywołania operacji ksefInvoiceGenerate
wysłanego do serwisu testowego dn. 2024-04-07 00:00:00 UTC ciąg wejściowy do funkcji HMAC będzie wyglądał następująco:
str = "1574640000\ndt831hs59s\nPOST\n/ksef/api-test/invoice/generate\nwww.ksefapi.pl\n443\n\n"
Plik z ciągiem wejściowym dla tego przykładu do pobrania <TODO – przygotować plik dla nowej daty > tutaj.
Z przygotowanego ciągu obliczamy HMAC SHA256, jako hasło HMAC podajemy wartość klucza API, którą należy odczytać z zakładki „Klucze API” po zalogowaniu się na swoje konto.
HMAC_SHA256(str, "<wartość klucza z zakładki Klucze API>") = <TODO podmienić hash>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 <TODO przygotrować plik > tutaj.
Wartość binarną obliczonego HMAC należy zakodować algorytmem Base64
, otrzymujemy:
<TODO - zaktualizować wartość> CjX6d/wpww/rSMS4MZKfL4Xtgz9WtGF4MqCfrKyhvVU=
Tą wartość należy przesłać jako wartość MAC w nagłówku z danymi do autoryzacji. Ostatecznie:
Authorization: MAC id="<wartość identyfikatora z zakładki Klucze API>", ts=<TODO wartość dla innej daty>"1574640000", nonce="dt831hs59s", mac=<TODO nowa wartość>"CjX6d/wpww/rSMS4MZKfL4Xtgz9WtGF4MqCfrKyhvVU="
Metoda 2 – 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, który można znaleźć na zakładce Klucze API.key
– klucz API, któego wartość można znaleźć na zakładce Klucze API.
Gdyby identyfikator klucza miał wartość test_id
, a klucz miał wartość test_key
, to 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@<TODO zmienić nazwę DNS>www.ksefapi.pl/ksef/api-test/invoice/generate
Gdzie:
test_id
– przykładowa wartość identyfikatora klucza. Aby uwierzytelnić się w środowisku produkcyjnym lub testowym, parametr powinien zawierać poprawny identyfikator klucza używanego do autoryzacji,test_key
– przykładowa wartość klucza. Aby uwierzytelnić się w środowisku produkcyjnym lub testowym, 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 (zakładka Klucze API
).