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 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 z wykorzystaniem Basic Authentication
Uwierzytelnienie 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, 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@www.ksefapi.pl/api-test/invoice/generateGdzie:
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.
Klucz oraz identyfikator są generowane przez użytkownika po zalogowaniu się na swoje konto (zakładka Klucze API i tokeny KSeF). Pole Token Klienta KSeF musi zostać uzupełnione tokenem wygenerowanym w systemie KSeF zgodnie z instrukcją opisaną w Przewodniku po KSeF:
