Wersja dokumentacji: 2.0 (changelog)

Data wersji: 2025-12-30

Dokumentacja integracyjna interfejsu REST API
dla Krajowego Systemu e-Faktur (KSeF 2.0)

Komponenty

Na potrzeby niniejszej dokumentacji zostały przyjęte 3 podstawowe komponenty, które uczestniczą w procesach biznesowych związanych z obsługą faktur w ramach KSeF 2.0:

• System wywołujący
• REST API KSeF 2.0
• System KSeF 2.0

Diagram: Komponenty 

System wywołujący

System IT klienta, który komunikuje się z Systemem KSeF za pośrednictwem interfejsu REST API KSEF.

Krajowy System e-Faktur (KSeF 2.0)

Krajowy System e-Faktur jest centralnym repozytorium ustrukturyzowanych faktur elektronicznych, które jest zarządzane i utrzymywany przez Ministerstwo Finansów.

REST API KSeF 2.0

Interfejs REST udostępniający operacje (metody) umożliwiające kompleksową realizację procesów biznesowych związanych z obsługą faktur ustrukturyzowanych KSeF

Procesy obsługi faktur KSeF

W rozdziale szczegółowo opisane zostały cztery główne procesy związane z obsługą faktur KSeF:

• Wygenerowanie faktury KSeF (ustrukturyzowanej) zgodnie ze schemą FA_v3
• Wysłanie faktur w sesji interaktywnej do KSeF i pobranie UPO
• Wyszukanie i pobranie faktur z KSeF (kosztowych lub sprzedażowych)
• Pobranie pojedynczej faktury z KSeF (kosztowej lub sprzedażowej)

Poszczególne kroki każdego z procesów zwierają odnośniki do operacji które należy wywołać w celu realizacji danego kroku.

Wygenerowanie faktury KSeF (ustrukturyzowanej)
zgodnej ze schemą FA_v3

Celem opisanego procesu jest umożliwinie wygenerowania faktury KSeF, której format i struktura będzie zgodna z najnowszą, aktualnie obowiązującą schemą. Proces opisuje pozytywny scenariusz i kroki jakie należy wykonać, aby wygenerować fakturę ustrukturyzowaną KSeF z wykorzystaniem interfejsu REST API KseF 2.0. Każde wywołanie operacji udostępnionej w interfejsie REST API KSeF 2.0 może spowodować wygenerowanie błędu. Możliwe do wystąpienia błędy, wynikające z obsługi żądania przez REST API KSeF 2.0, zostały szczegółowo opisane w rozdziale Komunikaty błędów.

Diagram: Wygenerowanie faktury ustrukturyzowanej KSeF

Opis przebiegu procesu:

1. System wywołujący przygotowuje odpowiednio żądanie KsefInvoiceGenerateRequest i wywołuje metodę ksefInvoiceGenerate.

2. Następnie REST API KSeF 2.0 na podstawie danych zawartych w żądaniu generuje plik XML faktury zgodny z bieżącą (aktualną) wersją schemy.

3. Wygenerowany plik XML faktury jest zwracany do systemu wywołującego, który zapisuje plik XML faktury po swojej stronie.

Wysłanie faktur w sesji interaktywnej do KSeF i pobranie UPO

Celem opisanego procesu jest wysłanie faktury (lub faktur) KSeF, do Krajowego Systemu e-Faktur w ramach utworzonej sesji interaktywnej oraz pobranie Urzędowego Poświadczenia Odbioru z KSeF potwierdzającego przyjęcie wysłanych faktur przez system KSeF. Proces opisuje pozytywny scenariusz i kroki jakie należy wykonać, aby przesłać fakturę ustrukturyzowaną do KSeF z wykorzystaniem interfejsu REST API KSeF 2.0. Każde wywołanie operacji udostępnionej w interfejsie REST API KSeF 2.0 może spowodować wygenerowanie błędu. Możliwe do wystąpienia błędy, wynikające z obsługi żądania przez REST API KSeF 2.0, ale też System KSeF zostały szczegółowo opisane w rozdziale Komunikaty błędów.

Diagram: Wysłanie faktur w sesji interaktywnej do KSeF i pobranie UPO

Opis przebiegu procesu:

1. Dla każdej wygenerowanej poza REST API KSeF faktury rekomendujemy wywołanie operacji ksefInvoiceValidate w celu sprawdzenia poprawności faktury ze schemą.
Uwaga! Jedną z przyczyn odrzucenia faktury przez KSeF może być niezgodność z obowiązującą schemą XSD.

2. Po zweryfikowaniu poprawności wygenerowanych faktur, należy wywołać operację ksefSessionOpenOnline w celu utworzenia sesji interaktywnej w ramach której zostanie przeprowadzona wysyłka. Szczegóły opisujące sposoby i rodzaje tworzonej sesji, a także możliwości z nimi związane zostały opisane w rozdziale opisującym daną metodę.

3. Po pomyślnym zestawieniu sesji interaktywnej, System KSeF zwraca identyfikator sesji (SessionId), który należy zapisać po stronie Systemu wywołującego, ponieważ identyfikator ten będzie wykorzystywany do wywołania innych operacji.

4. Następnie – zanim przystąpimy do wysyłki faktur – należy sprawdzić czy sesja, którą wcześniej utworzyliśmy nadal aktywna. Krok jest szczególnie istotny w przypadku, kiedy od utworzenia sesji minęło kilka minut lub jakość połączenia sieciowego jest słaba. W celu weryfikacji aktywności sesji należy wywołać operację ksefSessionStatus, a jako parametr wywołania podać identyfikator sesji interaktywnej (SessionId).

5. Jeśli w odpowiedzi na wywołanie metody ksefSessionStatus, otrzymaliśmy informację o aktywnym statusie sesji, to możemy przystąpić do iteracyjnej wysyłki wszystkich faktur wywołując tyle razy operację ksefInvoiceSend, ile faktur zamierzamy przesłać do KSeF. W odpowiedzi System KSeF powinien zwrócić w atrybucie id, identyfikator techniczny faktury (InvoiceId).

6. Zwrócony identyfikator techniczny faktury (InvoiceId) należy zapisać po stronie Systemu wywołującego, ponieważ identyfikator ten będzie wykorzystywany do wywołania operacji sprawdzającej status odebrania faktury (ksefInvoiceStatus) wysłanej do System KSeF.

7. Po wysłaniu do KSeF wszystkich faktur [5], oraz zapisaniu ich identyfikatorów technicznych [6] należy sprawdzić status odebrania każdej z wysłanych faktur. W tym celu należy dla każdej wysłanej faktury wywołać operację ksefInvoiceStatus z parametrem InvoiceId, zawierający identyfikator techniczny faktury.

8. Jeżeli w odpowiedzi (KsefInvoiceStatusResponse) status danej faktury (StatusInfo.code) ma wartość 200, oznacza to, że faktura została poprawnie zapisana w systemie KSeF i możemy zapisać wygenerowany przez KSeF numer faktury (invoiceKsefNumber) oraz datę akwizycji (acquisitionDat), czyli dokładną datę i godzinę zapisania w Systemie KSeF.

9. Po pobraniu wszystkich numerów KSeF wystałych faktur (invoiceKsefNumber) trzeba poprawnie zakończyć sesję interaktywną wywołując operację ksefSessionClose z parametrem SessionId (identyfikator sesji zwrócony podczas jej tworzenia w kroku 3).

10. Dopiero po zamknięciu sesji interaktywnej możliwe jest wywołanie operacji ksefSessionUpo, z parametrem SessionId (identyfikator sesji zwrócony podczas jej tworzenia w kroku 3) zwracającej Urzędowe Potwierdzenie Otrzymania (UPO). UPO jest zwracane jako obiekt TextXmlContent.

11. Ostatnim krokiem procesu jest zapisanie pobranego UPO (TextXmlContent) po stronie Systemu wywołującego.

Wyszukanie i pobranie faktur z KSeF (kosztowych lub sprzedażowych)

Celem opisanego procesu jest asynchroniczne wyszukanie i pobranie znalezionych faktur (kosztowych lub sprzedażowych) w Krajowym Systemie e-Faktur. Poszczególne operacje wykonywane są w ramach utworzonej sesji interaktywnej. Proces opisuje pozytywny scenariusz i kroki jakie należy wykonać, aby wyszukać i pobrać znalezione faktury, które spełniają zdefiniowane kryteria wyszukiwania. W ramach jednego wywołania można wyszukać albo swoje faktury kosztowe albo swoje faktury sprzedażowe. Każde wywołanie operacji udostępnionej w interfejsie REST API KSeF 2.0 może spowodować wygenerowanie błędu. Możliwe do wystąpienia błędy, wynikające z obsługi żądania przez REST API KSeF 2.0, ale też System KSeF zostały szczegółowo opisane w rozdziale Komunikaty błędów.

Diagram: Wyszukanie i pobranie faktur z KSeF (kosztowych lub sprzedażowych).

Opis przebiegu procesu:

1. W pierwszej kolejności należy odpowiednio przygotować kryteria wyszukiwania (KsefInvoiceQueryStartRequest) i zainicjować asynchroniczny proces wyszukiwania faktu, wywołując operację ksefInvoiceQueryStart.

2. Po pomyślnym wysłaniu zapytania, System KSeF zwraca identyfikator wyszukiwania (QueryId), który należy zapisać po stronie Systemu wywołującego, ponieważ identyfikator ten będzie wykorzystywany do wywołania operacji sprawdzenia statusu wyszukiwania (czy udało się znaleźć faktury) oraz do pobrania znalezionych paczek faktur.

3. W celu sprawdzenia czy jakieś faktury spełniają zdefiniowane kryteria wyszukiwania i zostały znalezione, należy wywołać operację ksefInvoiceQueryStatus. W zwróconej odpowiedzi KsefInvoiceQueryStatusResponse, zawartość atrybutu items[] informuje o liczbie paczek ze znalezionymi fakturami. Każda paczka identyfikowana jest przez identyfikator paczki (QueryPartNumber).

4. W celu pobrania faktur spełniających zdefiniowane kryteria wyszukiwania, należy dla każdej zwróconej paczki faktur (QueryPartNumber) wywołać operację ksefInvoiceQueryResult.

5. Po pobraniu wszystkich znalezionych faktur (wszystkich paczek), należy odszyfrować wszystkie pobrane paczki.

6. Następnie należy rozpakować każdą pobraną paczkę (archiwum ZIP) i zapisać po stronie Systemu wywołującego.

7. W celu wygenerowania wizualizacji dla pobranego pliku XML faktury z KSeF należy dla każdej faktury wywołać operację ksefInvoiceVisualize.

8. Ostatnim krokiem procesu jest zapisanie pobranego pliku (PDF lub HTML) zawierającego wizualizację faktury KSeF.

Pobranie pojedynczej faktury z KSeF (kosztowej lub sprzedażowej)

Celem opisanego procesu jest pobranie konkretnej faktury (kosztowej lub sprzedażowej) w Krajowym Systemie e-Faktur. Poszczególne operacje wykonywane są w ramach utworzonej sesji interaktywnej. Proces opisuje pozytywny scenariusz i kroki jakie należy wykonać, aby pobrać pojedynczą fakturę, dla której znany jest numer KSeF fakury. Każde wywołanie operacji udostępnionej w interfejsie REST API KSeF 2.0 może spowodować wygenerowanie błędu. Możliwe do wystąpienia błędy, wynikające z obsługi żądania przez REST API KSeF 2.0, ale też System KSeF zostały szczegółowo opisane w rozdziale Komunikaty błędów.

Diagram: Pobranie pojedynczej faktury z KSeF (kosztowej lub sprzedażowej).

Opis przebiegu procesu:

1. W pierwszym kroku, należy wywołać operację ksefInvoiceGet, której jednym z parametrów jest numer faktury nadany przez KSeF (InvoiceKsefNumber) .

2. Pobraną fakturę w postaci pliku XML, należy zapisać po stronie Systemu wywołującego. Jeśli chcemy posiadamy jeszcze jakieś numery KSeF faktur dla których chcemy pobrać faktury z KSeF, to należy powtórzyć kroki opisane w punktach 1-2.

3. Krok opcjonalny. W zależności od potrzeb biznesowych, ostatnim krokiem procesu może być wygenerowanie wizualizacji faktury w postaci PDF lub HTML. W tym celu należy wywołać operację ksefInvoiceVisualize i w żądaniu wybrać odpowiednie parametry dotyczące wizualizacji.

4. Na koniec pozostaje zapisać zwróconą wizualizację faktury po stronie Systemu wywołującego. 

Operacje

Rozdział zawiera opis metod udostępnionych w ramach interfejsu REST API KSeF 2.0.

Rysunek: Interfejs REST API KSeF 2.0.

GET

Metody typu HTTP GET.

ksefPublicKey

ksefPublicKey(): KsefPublicKeyResponse Metoda umożliwia pobranie klucza publicznego KSeF, który służy do zaszyfrowania klucza symetrycznego AES256, służącego do szyfrowania przesyłanych faktur XML z wykorzystaniem operacji ksefInvoiceSend w trybie z szyfrowaniem w sesji – czyli ustawionych parametrów: encryptedKey oraz initVector podczas tworzenia sesji (KsefSessionOpenOnlineRequest). Metoda na wejściu nie wymaga żadnego parametru, a na wyjściu zwraca odpowiedź zgodną z KsefPublicKeyResponse. 

Diagram: Operacja ksefPublicKey

Algorithm

Wspierane algorytmy kluczy kryptograficznych przez KSeF. Enumeracja została opisana w rozdziale Algorithm. 

KsefPublicKeyResponse

Klasa zawiera klucz publiczny systemu KSeF oraz informacje o algorytmie wg którego został utworzony.

algorithm : Algorithm – Algorytm zgodnie z którym został wygenerowany klucz publiczny

publicKey : string – Klucz publiczny w postaci kodowania DER obiektu ASN.1 SubjectPublicKeyInfo w postaci ciągu base64. Klucz publiczny KSeF służy do szyfrowania klucza symetrycznego (AES256), który to klucz powinien zostać wygenerowany przed utworzeniem sesji z szyfrowaniem, a następnie tym kluczem symetrycznym powinna zostać zaszyfrowane faktury XML przesyłane do KSeF.

ksefSessionStatus

ksefSessionStatus(sessionId : SessionId): KsefSessionStatusResponse Metoda umożliwia pobranie bieżącego statusu sesji. W ścieżce wywołania (URL) przyjmuje parametr SessionId. W odpowiedzi zwraca natomiast KsefSessionStatusResponse. Kliknij w nazwę operacji, aby przejść do Swagger UI.

Diagram: Operacja ksefSessionStatus

SessionId

Parametr został opisany w rozdziale SessionId. 

KsefSessionStatusResponse

Odpowiedź zawierająca status danej sesji interaktywnej lub wsadowej (batch)

sessionInfo : SessionInfo – Jeden z dwóch możliwych statusów sesji interaktywnej zdefiniowanych w klasie SessionInfo.

SessionInfo

Klasa zwraca informacje o aktualnym statusie sesji.

status : StatusInfo – Atrybut typu złożonego, który zwraca szczegółową informację o bieżący statusie sesji.

batch : boolean – Wartość true atrybutu oznacza, że dana sesja jest sesją wsadową, umożliwiającą wysyłkę faktur w trybie batch.

invoiceCount : int – Atrybut określa liczbę przyjętych faktur w ramach sesji.

successfulInvoiceCount : int – Atrybut określa liczbę faktur przeprocesowanych w ramach sesji z sukcesem.

failedInvoiceCount : int – Atrybut określa liczbę faktur przeprocesowanych w ramach sesji z błędem.

ksefSessionClose

ksefSessionClose(sessionId : SessionId): KsefSessionCloseResponse Metoda umożliwia zamknięcie sesji interaktywnej (online) lub wsadowej zestawionej z KSeF.
Uwaga! Poprawne zamknięcie sesji interaktywnej jest niezbędne do pobrania UPO, czyli obiektu potwierdzającego odebrane przez KSeF faktury. W ścieżce wywołania (URL) przyjmuje parametr SessionId. W odpowiedzi zwraca natomiast KsefSessionCloseResponse. Kliknij w nazwę operacji, aby przejść do Swagger UI.

Diagram: Operacja ksefSessionClose

SessionId

Parametr został opisany w rozdziale SessionId. 

KsefSessionCloseResponse

Odpowiedź zawierająca informację czy udało się poprawnie zakończyć sesję interaktywną

result : boolean – Wartość True (1) oznacza poprawne zakończenie sesji, natomiast wartość False (0) informuje, że nie udało się poprawnie zakończyć sesji.

ksefSessionUpo

ksefSessionUpo(sessionId : SessionId): TextXmlContent Metoda umożliwia pobranie Urzędowego Potwierdzenia Odbioru (UPO) dla wszystkich faktur, które zostały przesłane w ramach danej sesji interaktywnej zestawionej z KSeF.
Uwaga! Przed wywołaniem operacji ksefSessionUpo należy wcześniej zamknąć poprawnie sesję interaktywną korzystając z operacji ksefSessionClose. UPO można pobrać tylko dla sesji w której poprawnie została wystawiona przynajmniej jedna faktura. W ścieżce wywołania (URL) przyjmuje parametr SessionId. W odpowiedzi operacja zwraca obiekt TextXmlContent zawierający UPO. Kliknij w nazwę operacji, aby przejść do Swagger UI.

Diagram: Operacja ksefSessionUpo

SessionId

Parametr został opisany w rozdziale SessionId. 

TextXmlContent

Klasa została opisana w rozdziale TextXmlContent.

ksefInvoiceStatus

ksefInvoiceStatus(invoiceId : InvoiceId): KsefInvoiceStatusResponse Metoda umożliwia sprawdzenie statusu przetwarzania wysłanej do KSeF faktury.
Uwaga! Metoda sprawdza status przetwarzania faktury wysłanej do KSeF z wykorzystaniem operacji ksefInvoiceSend. Metoda na wejściu wymaga przesłania w ścieżce wywołania (URL) parametru InvoiceId, a na wyjściu zwraca odpowiedź zgodną z KsefInvoiceStatusResponse. Kliknij w nazwę operacji, aby przejść do Swagger UI.

Diagram: Operacja ksefInvoiceStatus

InvoiceId

Klasa reprezentuje identyfikator techniczny faktury, który jest zwracany jako atrybut id klasy KsefInvoiceSendResponse, a następnie może zostać wykorzystany do sprawdzenia statusu przetwarzania faktury wywołując operację ksefInvoiceStatus.

invoiceId : string – Identyfikator faktury (techniczny)

KsefInvoiceStatusResponse

Klasa reprezentuje odpowiedź systemu KSeF w kontekście statusu przetwarzania przesłanej do KSeF faktury.

invoices[] : InvoiceInfo – Atybut zawiera tablice z informacjami opisującymi status wysłanych faktur.

ksefInvoiceGet

ksefInvoiceGet(invoiceKsefNumber : InvoiceKsefNumber): KsefInvoiceGetContent Metoda pozwala pobrać pojedynczą fakturę z KSeF podając numer KSeF faktury.
Metoda na wejściu wymaga przesłania w ścieżce wywołania (URL) parametru InvoiceKsefNumber, a na wyjściu zwraca odpowiedź zgodną z TextXmlContent jeśli pobierana faktura nie jest szyfrowana lub ApplicationOctetStreamContent w przypadku pobierania faktury w formie zaszyfrowanej. Kliknij w nazwę operacji, aby przejść do Swagger UI.

Diagram: Operacja ksefInvoiceGet

InvoiceKsefNumber

Parametr został opisany w rozdziale InvoiceKsefNumber.

Content

Klasa została opisana w rozdziale Content.

ApplicationOctetStreamContent

Klasa została opisana w rozdziale ApplicationOctetStreamContent.

TextXmlContent

Klasa została opisana w rozdziale TextXmlContent.

ksefInvoiceQueryStatus

ksefInvoiceQueryStatus(queryId : QueryId): KsefInvoiceQueryStatusResponse Metoda pozwala uzyskać status wyszukiwania faktur w KSeF.
Metoda na wejściu wymaga przesłania w ścieżce wywołania (URL) parametru: QueryId, a na wyjściu zwraca odpowiedź zgodną z KsefInvoiceQueryStatusResponse. Kliknij w nazwę operacji, aby przejść do Swagger UI.

Diagram: Operacja ksefInvoiceQueryStatus

QueryId

Klasa zawiera identyfikator wyszukiwania, który jest generowany przez KSeF
queryId : string – Identyfikator procesu wyszukiwania

KsefInvoiceQueryStatusResponse

Obiekt reprezentuje wynik wyszukiwania faktur w KSeF

numberOfInvoices : int – Łączna liczba zwróconych faktur w paczce.

packageSize : int – Rozmiar paczki w bajtach dla kontroli, czy po odebraniu wszystkich części zgadza się ich łączna suma.

isTruncated : boolean – Wartość true atrybutu określa, że osiągnięto maksymalny dopuszczalny zakres wyników zapytania (10 000).

partNumbers[]: string – Atrybut zawiera tablicę z identyfikatorami paczek (każda paczka to plik ZIP) znalezionych faktur (QueryPartNumber), które spełniły kryteria wyszukiwania zdefiniowane w klasie KsefInvoiceQueryStartRequest.

ksefInvoiceQueryResult

ksefInvoiceQueryResult(queryId : QueryId, queryPartNumber : QueryPartNumber): KsefInvoiceQueryResultZipContent Metoda pozwala pobrać wszystkie faktury znalezione w KSeF.
Uwaga! Wywołanie metody wymaga wcześniejszego wywołania operacji ksefInvoiceQueryStart, która w odpowiedzi zwraca identyfikator wyszukiwania (QueryId).
Uwaga! Pobrane paczki faktur w postaci ZIP (identyfikowane za pomocą QueryPartNumber), należy przed rozpakowaniem odszyfrować. Każdą paczkę należy odszyfrować z wykorzystaniem symetrycznego klucza AES256 (encryptedKey), który był generowany przy tworzeniu sesji (ksefSessionOpenOnline). Metoda na wejściu wymaga przesłania w ścieżce wywołania (URL) dwóch parametrów: QueryId oraz QueryPartNumber, a na wyjściu zwraca odpowiedź zgodną z ApplicationZipContent. Kliknij w nazwę operacji, aby przejść do Swagger UI.

Diagram: Operacja ksefInvoiceQueryResult

QueryId

Klasa zawiera identyfikator wyszukiwania, który jest generowany przez KSeF.
queryId : string – Identyfikator procesu wyszukiwania

QueryPartNumber

Klasa reprezentuje numer paczki wyszukiwania.

partNumber : string – Identyfikator fragmentu (paczki) wyniku wyszukiwania

ApplicationZipContent

Klasa reprezentuje archiwum ZIP z fakturami KSeF w postaci XML
description : string – = Archiwum ZIP z fakturami XML

ksefSessionInvoices

ksefSessionInvoices(sessionId : SessionId): KsefSessionInvoicesResponse Metoda umożliwia sprawdzenie statusu przetwarzania wszystkich wysłanych do KSeF faktur.
Uwaga! Metoda sprawdza status przetwarzania faktur wysłanych do KSeF z wykorzystaniem operacji ksefSessionOpenBatch. Metoda na wejściu wymaga przesłania w ścieżce wywołania (URL) parametru SessionId, a na wyjściu zwraca odpowiedź zgodną z KsefSessionInvoicesResponse. Kliknij w nazwę operacji, aby przejść do Swagger UI.

Diagram: Operacja ksefSessionInvoices

KsefSessionInvoicesResponse

invoices[] : InvoiceInfo – Atybut zawiera tablice z informacjami opisującymi status wysłanych faktur.

InvoiceInfo

Klasa reprezentuje obiekt zawierający informacje o statusie wysłanych faktur

status : StatusInfo – Atrybut zawiera kompletne informacje opisujące status faktury.

ordinal : string – Atrybut zawiera numer sekwencyjny faktury w ramach sesji.

invoiceNumber : string – Atrybut zawiera numer faktury.

ksefNumber : string – Atrybut zawiera nadany numer KSeF.

acquisitionDate : string – Atrybut określa dokłady czas przyjęcia faktury w przez system KSeF (nadania numeru KseF). Zwracany format zgodny z date-time.

permanentStorageDate : string – Data trwałego zapisu faktury w repozytorium KSeF. Wartość uzupełniana asynchronicznie w momencie trwałego zapisu; zawsze późniejsza niż acquisitionDate. Podczas sprawdzania statusu może być jeszcze niedostępna Zwracany format zgodny z date-time.

StatusInfo

Klasa zawiera szczegółowe informacje dotyczące statusu przesłanych faktur.

code : int – Kod statusu faktury

description : string – Słowny opis statusu faktury

details : string – Dodatkowe szczegóły statusu

extensions[ ] : StatusInfoAttribute – Zbiór dodatkowych informacji związanych ze statusem faktury, zapisanych jako pary klucz–wartość. Umożliwia rozszerzenie modelu o dane specyficzne dla danego przypadku.

Poniższa tabela zawiera możliwe do zwórcenia przez KSeF informacje dotyczące statusów faktur:

Code	Description	Details	Extensions
100	Faktura przyjęta do dalszego przetwarzania	–	–
150	Trwa przetwarzanie	–	–
200	Sukces	–	–
405	Przetwarzanie anulowane z powodu błędu sesji	–	–
410	Nieprawidłowy zakres uprawnień	–	–
415	Brak możliwości wysyłania faktury z załącznikiem	–	–
430	Błąd weryfikacji pliku faktury	–	–
435	Błąd odszyfrowania pliku	–	–
440	Duplikat faktury	–	’originalSessionReferenceNumber’, 'originalKsefNumber’
450	Błąd weryfikacji semantyki dokumentu faktury	–	–
500	Nieznany błąd ({statusCode})	–	–
550	Operacja została anulowana przez system	Przetwarzanie zostało przerwane z przyczyn wewnętrznych systemu. Spróbuj ponownie	–

StatusInfoAttribute

Klasa reprezentuje dodatkowe informacje dotyczące statusu przesłanych faktur w formacie klucz-wartość.

key : string – Atrybut zawiera nazwę (klucz).

value : string – Atrybut zawiera wartość odpowiadającą danemu kluczowi (atrybut key).

 

POST

Metody typu HTTP POST.

ksefSessionOpenOnline

ksefSessionOpenOnline(invoice : KsefSessionOpenOnlineRequest): KsefSessionOpenOnlineResponse Metoda umożliwia zestawienie sesji interaktywnej z systemem KSeF, dzięki której możliwe będzie wysłanie faktur do KSeF z wykorzystaniem operacji ksefInvoiceSend. Metoda na wejściu wymaga utworzenia żądania zgodnego z KsefSessionOpenOnlineRequest, a na wyjściu zwraca odpowiedź zgodną z KsefSessionOpenOnlineResponse. Kliknij w nazwę operacji, aby przejść do Swagger UI.

Diagram: Operacja ksefSessionOpenOnline

KsefSessionOpenOnlineRequest

Klasa została opisana w rozdziale KsefSessionOpenOnlineRequest.

EncryptionInfo

Klasa została opisana w rozdziale EncryptionInfo.

KsefInvoiceVersion

Klasa została opisana w rozdziale KsefInvoiceVersion.

KsefSessionOpenOnlineResponse

Odpowiedź w przypadku poprawnie utworzonej sesji zawierająca następujące atrybuty:

id : string – Atrybut zawiera identyfikator utworzonej sesji. Należy go zapisać po stronie systemu wywołującego, ponieważ będzie on wykorzystywany w większości pozostałych operacji.

created : string – Atrybut zawiera datę i czas utworzenia sesji w formacie data-czas.

ksefSessionOpenBatch

ksefSessionOpenBatch(invoice : KsefSessionOpenBatchRequest): KsefSessionOpenBatchResponse Metoda umożliwia zestawienie sesji wsadowej z systemem KSeF, dzięki której możliwe będzie wysłanie wielu faktur do KSeF w ramach jednej paczki. Metoda na wejściu wymaga utworzenia żądania zgodnego z KsefSessionOpenBatchRequest, a na wyjściu zwraca odpowiedź zgodną z KsefSessionOpenBatchResponse. Kliknij w nazwę operacji, aby przejść do Swagger UI.

Diagram: Operacja ksefSessionOpenBatch

KsefSessionOpenBatchRequest

Klasa reprezentuje atrybuty wejściowe dla operacji otwarcia sesji w trybie wsadowym.

invoiceVersion : KsefInvoiceVersion – Jedna z dwóch możliwych wersji schemy zdefiniowanych w enumie KsefInvoiceVersion. Wymagalność: [1]

encryptionInfo : EncryptionInfo – Typ został opisany w rozdziale EncryptionInfo. Wymagalność: [1]

offline : boolean – Atrybut określa czy przesyłane faktury są wystawione w trybie offline24. Wymagalność: [1]

batchInfo : BatchInfo – Typ został opisany w rozdziale BatchInfo. Wymagalność: [1]

BatchInfo

Klasa reprezentuje informacje opisujące paczkę wysyłanych faktur.

batchSize : int – Atrybut określający rozmiar całej paczki. Rozmiar pliku paczki w bajtach. Wymagalność: [1]. Maksymalny rozmiar paczki to 5GB. Zakres: [1 .. 5000000000]

batchHash : string – Atrybut zawierający hash (funkcję skrótu) z całej paczki, zakodowany w formacie Base64. Wymagalność: [1]

batchParts: BatchPartInfo – Atrybut typu tablicowego (array) zawierający informację o danych częściach paczki. Typ został opisany w rozdziale BatchPartInfo. Wymagalność: [1]. Maksymalna liczba części to 50. Zakres: [1 .. 50]. Maksymalny dozwolony rozmiar części przed zaszyfrowaniem to 100MB.

BatchPartInfo

Klasa reprezentuje daną część paczki.

ordinal: int – Atrybut porządkowy wskazujący kolejny numer części paczki. Wymagalność: [1]

partSize: int – Atrybut określający rozmiar części paczki. Wymagalność: [1]

partHash: string – Atrybut zawierający hash (funkcję skrótu) z danej części paczki, zakodowany w formacie Base64. Wymagalność: [1]

KsefSessionOpenBatchResponse

Klasa reprezentuje zwracaną odpowiedź po poprawnym zestawieniu sesji wsadowej 

PartUploadInfo

ordinal : int – Atrybut porządkowy, określa część pliku paczki.

method : string – Metoda HTTP, której należy użyć przy wysyłce części pliku paczki.

url : string – Adres pod który należy wysłać część pliku paczki.

headers : PartUploadHeader –  Atrybut typu tablicowego (array), który został opisany w rozdziale PartUploadHeader.

PartUploadHeader

Klasa reprezentuje nagłówek, którego należy użyć przy wysyłce części pliku paczki

name : string – Nazwa nagłówka

value : string – Wartość nagłówka

ksefInvoiceGenerate

ksefInvoiceGenerate(ksefInvoiceGenerateRequest : KsefInvoiceGenerateRequest): KsefInvoiceGenerateResponse Metoda umożliwiająca wygenerowanie faktury ustrukturyzowanej XML zgodnej z bieżącą (aktualną) wersją schemy wykorzystywanej w KSeF. Kliknij w nazwę operacji, aby przejść do Swagger UI.

Uwaga! Szczegółowy opis klas i atrybutów wejściowych dla operacji, został zamieszczony na dedykowanej podstronie: REST API – generowanie faktur KSeF 2.0.

Diagram: Operacja ksefInvoiceGenerate

KsefInvoiceGenerateRequest

Klasa reprezentuje atrybuty wejściowe opisujące fakturę KSeF. Klasa została szczegółowo opisna w rozdziale KsefInvoiceGenerateRequest.

KsefInvoiceGenerateResponse

Klasa reprezentuje odpowiedź zwracaną przez operację ksefInvoiceGenerate, która zawiera wygenerowaną fakturę KSeF zgodną ze schemą obowiązującą w KSeF. Klasa została szczegółowo opisna w rozdziale KsefInvoiceGenerateResponse.

ksefInvoiceValidate

ksefInvoiceValidate(ksefInvoice : KsefInvoice): KsefInvoiceValidateResponse Metoda umożliwia weryfikację faktury KSeF na zgodność ze schemą. Jako parametr wywołania operacji należy przesłać obiekt TextXmlContent zawierający wygenerowaną fakturę KSeF. Do wygenerowania faktury można wykorzystać zewnętrzne narzędzie lub operację ksefInvoiceGenerate. W odpowiedzi operacja zwraca obiekt KsefInvoiceValidateResponse z informacją w jakiej wersji schemy jest wygenerowana faktura oraz czy jest ona zgodna z tą strukturą. Kliknij w nazwę operacji, aby przejść do Swagger UI.

Diagram: Operacja ksefInvoiceValidate

TextXmlContent

Klasa została opisana w rozdziale TextXmlContent.

KsefInvoiceValidateResponse

Odpowiedź zawierająca informacje dotyczące wersji schemy w jakiej została wygenerowana przesłana faktura KSeF oraz czy jest ona zgodna z tą schemą.
invoiceVersion : KsefInvoiceVersion – Jedna z obsługiwanych wersji schemy zdefiniowanych w enumie KsefInvoiceVersion.

valid : boolean – Wartość True (1) oznacza zgodność przesłanej do weryfikacji faktury ze schemą, natomiast w przypadku wykrycia niezgodności pliku XML faktury ze schemą, to zwracany jest kodHttp i obiekt Error z opisem pierwszego wykrytego błędu niezgodności ze schemą w atrybucie details.

canonicalForm : string – Atrybut zawiera  kanoniczną formę przesłanej do walidacji faktury. Wartość jest kodowana z wykorzystaniem Base64.

ksefInvoiceSend

ksefInvoiceSend(invoice : KsefInvoiceSendRequest): KsefInvoiceSendResponse Metoda umożliwia wysłanie jednej faktury do systemu KSeF w ramach zestawionej sesji interaktywnej. Kliknij w nazwę operacji, aby przejść do Swagger UI.
Uwaga! Metodę można wywołać dowolną liczbę razy w ramach zestawionej sesji i dzięki temu przesłać do KSeF więcej faktur.
Uwaga! Aby wysłać faktury do KSeF z wykorzystaniem tej metody, należy wcześniej wywołać operację ksefSessionOpenOnline w celu zestawienia sesji interaktywnej. Metoda na wejściu wymaga utworzenia żądania zgodnego z KsefInvoiceSendRequest, a na wyjściu zwraca odpowiedź zgodną z KsefInvoiceSendResponse. 

Diagram: Operacja ksefInvoiceSend

KsefInvoiceSendRequest

Klasa została opisana w rozdziale KsefInvoiceSendRequest.

KsefInvoiceEncrypted

Klasa została opisana w rozdziale KsefInvoiceEncrypted.

KsefInvoiceSendResponse

Klasa reprezentuje odpowiedź uzyskaną z KSeF w przypadku przesłania faktury zakończonego sukcesem.
Uwaga! Odpowiedź informuje o poprawnym wysłaniu faktury do KSeF, jednak aby mieć pewność, że faktura została poprawnie zapisana w KSeF należy wywołać operację ksefInvoiceStatus, której jednym z parametrów wejściowych jest identyfikator techniczny faktury zwrócony jako wartość atrybutu id.
created : string – Atrybut zawiera informacje o dokładnej dacie i czasie przesłania faktury do KSeF
id : string – Atrybut zawiera identyfikator techniczny faktury wysłanej do KSeF

ksefInvoiceQueryStart

ksefInvoiceQueryStart (KsefInvoiceQueryStartRequest : KsefInvoiceQueryStartRequest): KsefInvoiceQueryStartResponse Metoda pozwala określić i wysłać do KSeF kryteria wyszukiwania faktur. Kliknij w nazwę operacji, aby przejść do Swagger UI.
Uwaga! Wywołanie metody wymaga wcześniejszego otwarcia sesji interaktywnej z wykorzystaniem operacji ksefSessionOpenOnline. Metoda na wejściu wymaga przesłania żądania zgodnego z KsefInvoiceQueryStartRequest. Metoda zwraca obiekt zgodny z KsefInvoiceQueryStartResponse, który zawiera identyfikator wyszukiwania.

Diagram: Operacja ksefInvoiceQueryStart

KsefInvoiceQueryStartRequest

Klasa została opisana w rozdziale KsefInvoiceQueryStartRequest.

SubjectType

Enumeracja została opisana w rozdziale SubjectType. 

KsefInvoiceQueryStartRange

Klasa została opisana w rozdziale KsefInvoiceQueryStartRange.

KsefInvoiceQueryStartResponse

Obiekt reprezentuje odpowiedź z systemu KSeF zawierającą identyfikator wyszukiwania, które to wyszukiwanie zostało uruchomione asynchronicznie po stronie KSeF.
queryId : string – Atrybut określa identyfikator wyszukiwania, który jest generowany przez KSeF.

ksefInvoiceVisualize

ksefInvoiceVisualize(KsefInvoiceVisualizeRequest : KsefInvoiceVisualizeRequest): KsefInvoiceVisualizeContent Metoda umożliwiająca wygenerowanie wizualizacji faktury ustrukturyzowanej XML w jednym z formatów: HTML oraz PDF. Metoda na wejściu wymaga przygotowania żądania zgodnie z KsefInvoiceVisualizeRequest, a w odpowiedzi zwraca obiekt typu TextHtmlContent dla wizualizacji HTML albo ApplicationPdfContent dla wizualizacji w pliku PDF. Kliknij w nazwę operacji, aby przejść do Swagger UI.

Diagram: Operacja ksefInvoiceVisualize

KsefInvoiceVisualizeRequest

Klasa została opisana w rozdziale KsefInvoiceVisualizeRequest.

OutputFormat

Enumeracja została opisana w rozdziale OutputFormat.

OutputLanguage

Enumeracja została opisana w rozdziale OutputLanguage.

Content

Klasa została opisana w rozdziale Content.

ApplicationPdfContent

Klasa reprezentuje wygenerowaną wizualizację faktury KSeF w postaci pliku PDF.
description : string – = Wizualizacja PDF

TextHtmlContent

Klasa reprezentuje wygenerowaną wizualizację faktury KSeF w postaci pliku HTML.
description : string – = Wizualizacja HTML

Parametry

Rozdział zawiera zestawienie wszystkich parametrów w podziale na typ:

• path – parametr przekazywany w ścieżce URL
• requestBody – parametr przekazywany w treści żądania

 Diagram: Parametry

Path

Parametry wywołania operacji zawarte w ścieżce (path).

SessionId

Klasa reprezentuje identyfikator sesji generowany przez system KSEF
sessionId : string – Unikalny identyfikator sesji

InvoiceId

Klasa reprezentuje identyfikator techniczny faktury, który jest zwracany jako atrybut id klasy KsefInvoiceSendResponse, a następnie może zostać wykorzystany do sprawdzenia statusu przetwarzania faktury wywołując operację ksefInvoiceStatus.
invoiceId : string – Identyfikator faktury (techniczny)

InvoiceKsefNumber

Numer KSeF faktury generowany przez KSeF.
invoiceKsefNumber : string – Wygenerowany przez KSeF Identyfikator faktury. Wygenerowanie tego identyfikatora potwierdza zapisanie przesłanej faktury w KSeF.

QueryId

Klasa zawiera identyfikator wyszukiwania, który jest generowany przez KSeF.
queryId : string – Identyfikator procesu wyszukiwania

QueryPartNumber

Klasa reprezentuje numer paczki wyszukiwania.
partNumber : string – Identyfikator fragmentu (paczki) wyniku wyszukiwania

RequestBody

Paramtery typu requestBody.

KsefInvoiceEncrypted

Obiekt reprezentuje przesyłaną fakturę w formie zaszyfrowanej.
encryptedInvoice : string – Atrybut zawierający plik XML faktury w postaci zaszyfrowanej, która jest wysyłana do KSeF. Plik XML faktury jest zaszyfrowany algorytmem AES256 z użyciem wektora inicjalizującego (atrybut initVector klasy KsefSessionOpenOnlineRequest) i klucza symetrycznego wygenerowanego przy tworzeniu sesji.
invoiceHash : string – Atrybut zawiera wartość skrótu z funkcji SHA256 z oryginalnej (niezaszyfrowanej) postaci XML faktury, która jest wysyłana do KSeF.
invoiceSize : int – Atrybut zawierający wyliczoną wielkość faktury (rozmiar w bajtach oryginalnej, niezaszyfrowanej postaci XML faktury), która jest wysyłana do KSeF.

KsefInvoiceQueryStartRange

Klasa reprezentuje okres dla jakiego mają zostać wyszukane faktury. Daty from oraz to, określają datę PermanentStorage, czyli datę trwałego zapisu faktury w repozytorium systemu KSeF. Dla przyrostowego pobierania faktur konieczne jest użycie daty typu PermanentStorage, które zapewnia wiarygodność danych. Oznacza moment trwałej materializacji rekordu, jest odporna na asynchroniczne opóźnienia procesu przyjmowania danych i pozwala bezpiecznie wyznaczać okna przyrostu.
from : string – Data od której będą wyszukiwane faktury.
to : string – Data do której będą wyszukiwane faktury.

KsefInvoiceQueryStartRequest

Klasa reprezentuje żądanie pozwalające na zdefiniowanie parametrów wyszukiwania.

range : KsefInvoiceQueryStartRange – Wybór okresu dla jakiego mają zostać wyszukane faktury. Wymagalność: [1].
encryptionInfo : EncryptionInfo – Typ został opisany w rozdziale EncryptionInfo. Wymagalność: [1].
subjectType : SubjectType – Określenie jakiego typu faktury wyszukujemy. Wymagalność: [1]:

• sprzedażowe (Subject1),
• kosztowe (Subject2),
• podmiotu trzeciego (Subject3),
• podmiotu uprawnionego (SubjectAuthorized)

SubjectType

Enumeracja określa możliwe typy podmiotu
Subject1 : – Atrybut oznacza podmiot wystawiający fakturę
Subject2 : – Atrybut oznacza podmiot przyjmujący fakturę
Subject3 : – Atrybut oznacza podmiot trzeci
SubjectAuthorized : – Atrybut oznacza podmiot uprawniony

KsefInvoiceSendRequest

Klasa reprezentuje żądanie wysłania faktury w dwóch trybach: szyfrowania albo braku szyfrowania faktur
encrypted : KsefInvoiceEncrypted – Atrybut określa wariant (choice), który służy do przesłania faktury zaszyfrowanej w sesji utworzonej z szyfrowaniem, czyli ustawione parametry: encryptedKey oraz initVector podczas tworzenia sesji (KsefSessionOpenOnlineRequest). Wymagalność: [1]

sessionId : string – Identyfikator sesji uzyskany podczas ustanawiania sesji interaktywnej: ksefSessionOpenOnline. Wymagalność: [1]

KsefSessionOpenOnlineRequest

Klasa reprezentuje żądanie utworzenia sesji interaktywnej.

invoiceVersion : KsefInvoiceVersion – Wskazanie w jakiej wersji schemy będą przesyłane faktury KSeF w ramach ustanowionej sesji. Wymagalność: [1]

encryptionInfo : EncryptionInfo – Typ został opisany w rozdziale EncryptionInfo. Wymagalność: [1]

EncryptionInfo

encryptedKey : string – Jeśli w ramach sesji interaktywnej ma być wykorzystane szyfrowanie przesyłanych danych (faktury), to w atrybucie powinien zostać zawarty symetryczny klucz szyfrujący (AES256) wygenerowany przed otworzeniem nowej sesji i zaszyfrowany kluczem publicznym RSA platformy KSeF pobranym z wykorzystaniem operacji ksefPublicKey. Wymagalność: [1]

initVector : string – Atrybut opisuje tzw. wektor inicjalizacyjny. Dopuszczalny algorytm szyfrowania kluczem symetrycznym AES to AES/CBC/PKCS5Padding (PKCS#7). Dopuszczalny klucz symetryczny to AES o długości 256 bitów wspierany losowym wektorem inicjalizacyjnym długości 16 bajtów. Wymagalność: [1]

KsefInvoiceVisualizeRequest

Klasa umożliwia zdefiniowanie parametrów związanych z wizualizacją faktury ustrukturyzowanej (faktury KSeF)
templateName: string – Atrybut definiuje nazwę szablonu jaki ma być wykorzystany do wizualizacji faktury.

offline: boolean – Atrybut określa czy do wizualizacji ma zostać dołączony kod QR. Opcja może mieć zastosowanie dla faktur wystawianych kontrahentom zagranicznym, którzy i tak nie będą mieć dostępu do KSeF, a sposób przekazania (dostarczenia) faktury będzie zależał od podmiotu wystawiającego.

invoiceKsefNumber: string – Atrybut zawiera unikalny numer KSeF faktury nadany przez Krajowy System e-Faktur podczas poprawnego wysłania faktury do KSeF. 

invoiceData: string – Atrybut przekazuje plik XML faktury KSeF dla której ma zostać wykonana wizualizacja.

outputFormat: OutputFormat – Atrybut może przyjmować jedną z dwóch możliwych do wprowadzenia wartości zdefiniowanych w enumeracji OutputFormat.

outputLanguage : OutputLanguage – Atrybut może przyjmować jedną z trzech możliwych do wprowadzenia wartości zdefiniowanych w enumeracji OutputLanguage.

 

Enumeracje

Rozdział zawiera zestawienie wszystkich enumeracji możliwych do użycia w interfejsie.

Diagram: Enumeracje

InvoiceStatus

Enumeracja określająca możliwe statusu przesłanej faktury zwrócone przez KsefInvoiceStatusResponse
processing : string – Zwrócony z KSeF status oznacza że wysłana faktura nadal jest przetwarzana. Należy odczekać chwilkę i jeszcze raz sprawdzić status faktury.
accepted : string – Zwrócony z KSeF status oznacza że wysłana faktura została poprawnie odebrana i został dla niej nadany unikalny numer KSeF (InvoiceKsefNumber).
rejected : string – Zwrócony z KSeF status oznacza że wysłana faktura została odrzucona przez KSeF. W szczegółach komunikatu błędu (Error), należy sprawdzić co było powodem odrzucenia faktury.

Algorithm

Wspierane algorytmy kluczy kryptograficznych przez KSeF
RSA : – Obsługiwany algorytm kluczy kryptograficznych

KsefInvoiceVersion

Wersja schemy dla faktur KSeF  
v2 : – Druga wersja schemy
v3 : – Trzecia wersja schemy (obowiązująca).

OutputFormat

Enumeracja definiuje format w jakim ma zostać wygenerowana wizualizacja faktury
html : string – Wartość określa, że wizualizacja faktury powinna być zwrócona w formacie HTML.
pdf : string – Wartość określa, że wizualizacja faktury powinna być zwrócona w formacie PDF.

OutputLanguage

Enumeracja definiuje język w jakim ma zostać wygenerowana wizualizacja faktury
pl : string – Wartość określa, że wizualizacji faktury powinna być w języku polskim.
en : string – Wartość określa, że wizualizacji faktury powinna być w języku angielskim.
pl_en : string – Wartość określa, że wizualizacji faktury powinna być w języku polskim i angielskim.

SessionStatus

Enumeracja definiuje jakie statusy może mieć sesja interaktywna
active : string – Atrybut oznacza aktywną sesję
closed : string – Atrybut oznacza zakończoną sesję.

SubjectType

Enumeracja określa możliwe typy podmiotu
subject1 : – Atrybut oznacza podmiot wystawiający fakturę
subject2 : – Atrybut oznacza podmiot przyjmujący fakturę
subject3 : – Atrybut oznacza podmiot trzeci
subjectAuthorized : – Atrybut oznacza podmiot uprawniony

Odpowiedzi typu content

Rozdział identyfikuje i grupuje klasy związane z poszczególną zawartością, jaka może wystąpić podczas wymiany informacji z KSeF.

Diagram:  Odpowiedzi typu content

Content

Nadrzędna klasa opisująca zawartość po której dziedziczą pozostałe klasy
description : string – Opis zawartości dla danej klasy
format : binary – Format zawartości – zawsze BINARY
type : string – Typ zawartości – zawsze STRING

ApplicationZipContent

Klasa reprezentuje archiwum ZIP z fakturami KSeF w postaci XML
description : string – Archiwum ZIP z fakturami XML

ApplicationOctetStreamContent

Klasa reprezentuje dane w jednej z dwóch możliwych postaci: a) zaszyfrowaną pojedynczą fakturę KSeF (XML), b) zaszyfrowane archiwum ZIP z wieloma fakturami KSeF (XML)
description : string – Zaszyfrowana pojedyncza faktura XML albo zaszyfrowane archiwum ZIP z fakturami XML

TextXmlContent

Klasa reprezentuje Fakturę KSeF lub Urzędowe Potwierdzenie Otrzymania (UPO) w postaci XML
description : string – Faktura lub UPO

ApplicationPdfContent

Klasa reprezentuje wygenerowaną wizualizację faktury KSeF w postaci pliku PDF
description : string – = Wizualizacja PDF

TextHtmlContent

Klasa reprezentuje wygenerowaną wizualizację faktury KSeF w postaci pliku HTML
description : string – = Wizualizacja HTML

Komunikaty błędów

Rozdział zawiera opis klasy odpowiedzialnej za obsługę komunikatów błędów.

Error

Klasa reprezentuje strukturę zwracanych błędów
code : string – Unikalny kod błędu
description : string – Opis błędu
details : string – Szczegółowy opis błędu. Atrybut wykorzystywany w szczególności podczas generowania pliku XML faktury (ksefInvoiceGenerate) w przypadku kiedy wystąpił błąd niezgodności ze schemą. Zawsze zwracana jest informacja o pierwszym napotkanym błędzie. (Wymagalność: [0..1]). Błędy występujące w obszarze generowania faktur zostały szczegółowo opisane w rozdziale Komunikaty błędów – Faktura.

Autoryzacja i szyfrowanie

Zbiór błędów związany z obszarem autroyzacji i szyfrowania.

Diagram: Komunikaty błędów – autoryzacja i szyfrowanie

AES_IV_LENGTH – Niepoprawna długość wektora inicjującego

code = 1002
description = Wektor inicjujący ma nieprawidłową długość

AES_KEY_LENGTH – Niepoprawna długość klucza symetrycznego, służącego do szyfrowania danych

code = 1003
description = Klucz symetryczny ma nieprawidłową długość

AUTH_CHALLENGE – Błąd pobrania wyzwania autoryzującego

code = 1001
description = Nie udało się pobrać wyzwania autoryzacyjnego z systemu KSeF

B64_DECODE – Błędnie kodowana wartość z wykorzystaniem base64

code = 1005
description = Nieprawidłowe kodowanie base64 wartości

KSEF_PUBLIC_KEY – Błąd pobierania klucza publicznego KSeF

code = 1004
description = Nie udało się pobrać klucza publicznego systemu KSeF

Sesja

Zbiór błędów związany z zarząaniem sesją interaktywną.

Diagram: Komunikaty błędów – sesja

SESSION_ACCESS – Błąd dostępu do sesji

code = 1110
description = Użytkownik nie ma dostępu do podanej sesji

SESSION_CLOSE – Błąd podczas próby zamknięcia sesji interaktywnej

code = 1106
description = Nie udało się zamknąć sesji w systemie KSeF

SESSION_INIT – Błąd inicjacji sesji interaktywnej z systemem KSeF

code = 1102
description = Nie udało się zainicjować nowej sesji w systemie KSeF

SESSION_NO_UPO – Obiekt UPO nie został jeszcze wygenerowany

code = 1111
description = Brak UPO

SESSION_OPEN – Błąd tworzenia nowej sesji interaktywnej z KSeF

code = 1103
description = Nie udało się utworzyć nowej sesji w systemie KSeF

SESSION_REF_NUM – Niepoprawny identyfikator sesji interaktywnej KSeF

code = 1104
description = Brak identyfikatora nowej sesji KSeF

SESSION_SAVE – Błąd aktualizacji sesji

code = 1108
description = Nie udało się zaktualizować danych sesji KSeF

SESSION_STATUS – Błąd pobierania statusu sesji interaktywnej w KSeF

code = 1105
description = Nie udało się pobrać bieżącego statusu sesji z systemu KSeF

SESSION_TOKEN – Błąd przygotowania wyzwania autoryzacyjnego

code = 1101
description = Nie udało się przygotować odpowiedzi na wyzwanie autoryzacyjne dla systemu KSeF

SESSION_UNKNOWN – Błędny identyfikator sesji

code = 1109
description = Nieznany identyfikator sesji KSeF

SESSION_UPO – Błąd pobrania UPO

code = 1107
description = Nie udało się pobrać UPO z systemu KSeF

Faktura

Zbiór błędów związany z generowaniem, wysyłką, pobieraniem oraz wizualizacją faktur.

Diagram: Komunikaty błędów – faktura

INVOICE_FORMAT – Błędny format przesłanej faktury

code = 1203
description = Faktura ma nieprawidłowy format

INVOICE_INPUT – Brak wymaganych metadanych opisujących fakturę

code = 1208
description = Brak wymaganych metadanych faktury

INVOICE_SAVE – Wystąpił błąd podczas aktualizacji danych faktury

code = 1206
description = Nie udało się zaktualizować danych faktury

INVOICE_SEND – Wystąpił błąd podczas przesyłania faktury do KSeF

code = 1204
description = Nie udało się wysłać faktury do systemu KSeF

INVOICE_SIZE – Za duży rozmiar faktury

code = 1202
description = Faktura ma niedopuszczalny rozmiar

INVOICE_STATUS – Wystąpił błąd podczas pobierania statusu faktury

code = 1205
description = Nie udało się pobrać bieżącego statusu faktury z systemu KSeF

INVOICE_UNKNOWN – Błędny identyfikator faktury

code = 1207
description = Nieznany identyfikator faktury

INVOICE_VERSION – Błędna wersja schemy faktury

code = 1201
description = Nieprawidłowa wersja formatu faktury

INVOICE_VISUALIZE – Wystąpił błąd podczas generowania wizualizacji faktury

code = 1209
description = Nie udało się wygenerować wizualizacji faktury

Wyszukiwanie

Zbiór błędów związany z wszykiwaniem faktur w KSeF

Diagram: Komunikaty błędów – wyszukiwanie

QUERY_INVOICE_INIT – Wystąpił błąd podczas inicjacji procesu wyszukiwania faktur

code = 1302
description = Nie udało się rozpocząć procesu wyszukiwania faktur

QUERY_INVOICE_PARAMS – Błędne kryteria wyszukiwania

code = 1301
description = Nieprawidłowe lub niekompletne kryteria wyszukiwania faktur

QUERY_INVOICE_RESULT – Wystąpił błąd podczas pobierania wyników wyszukiwania faktur

code = 1304
description = Nie udało się pobrać wyniku wyszukiwania faktur

QUERY_INVOICE_STATUS – Wystąpił błąd podczas sprawdzania statusu wyszukiwania faktur

code = 1303
description = Nie udało się pobrać statusu procesu wyszukiwania faktur