KSeF REST API

Wersja dokumentacji: 1.1 (changelog)

Data wersji: 2024-04-19

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

Spis treści

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:

System wywołujący
REST API KSeF
System KSeF

KSeF REST API - komponenty Rysunek: 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)

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

REST API KSeF

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_v2 • 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_v2

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. Każde wywołanie operacji udostępnionej w interfejsie REST API KSeF może spowodować wygenerowanie błędu. Możliwe do wystąpienia błędy, wynikające z obsługi żądania przez REST API KSeF, zostały szczegółowo opisane w rozdziale Komunikaty błędów.

KSeF REST API - proces generowania faktury KSeF Rysunek: Wygenerowanie faktury KSeF

Opis przebiegu procesu:

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

2. Następnie REST API KSeF 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. Każde wywołanie operacji udostępnionej w interfejsie REST API KSeF może spowodować wygenerowanie błędu. Możliwe do wystąpienia błędy, wynikające z obsługi żądania przez REST API KSeF, ale też System KSeF zostały szczegółowo opisane w rozdziale Komunikaty błędów.

KSeF REST API - proces wysyłki faktur do KSeF Rysunek: 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ę ksefSessionOpen 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 (InvoiceStatus) ma wartość accepted, oznacza to, że faktura została poprawnie zapisana w systemie KSeF i możemy zapisać wygenerowany przez KSeF numer faktury (ksefReferenceNumber) oraz datę akwizycji (acquisitionTimestamp), czyli dokładną datę i godzinę zapisania w Systemie KSeF.

9. Po pobraniu wszystkich numerów KSeF wystałych faktur (ksefReferenceNumber) 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 może spowodować wygenerowanie błędu. Możliwe do wystąpienia błędy, wynikające z obsługi żądania przez REST API KSeF, ale też System KSeF zostały szczegółowo opisane w rozdziale Komunikaty błędów.

KSeF REST API - proces wyszukania i pobrania faktur z KSeF Rysunek: Wyszukanie i pobranie faktur z KSeF (kosztowych lub sprzedażowych)

Opis przebiegu procesu:

1. W pierwszej kolejności, należy wywołać operację ksefSessionOpen w celu utworzenia sesji interaktywnej w ramach której będą wykonywane pozostałe operacje. 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ę.

2. Po poprawnym 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 kolejnych operacji.

3. Następnie należy odpowiednio przygotować kryteria wyszukiwania (KsefInvoiceQueryStartRequest) i zainicjować asynchroniczny proces wyszukiwania faktu, wywołując operację ksefInvoiceQueryStart.

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

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

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

7. Po pobraniu wszystkich znalezionych faktur (wszystkich paczek), należy zamknąć sesję wywołując operację ksefSessionClose.

8. Krok opcjonalny. Jeśli sesja podczas tworzenia była skonfigurowana na szyfrowanie przesyłanych danych, to wszystkie pobrane paczki należy odszyfrować.

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

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

11. 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 może spowodować wygenerowanie błędu. Możliwe do wystąpienia błędy, wynikające z obsługi żądania przez REST API KSeF, ale też System KSeF zostały szczegółowo opisane w rozdziale Komunikaty błędów.

KSeF REST API - pobranie pojedynczej faktury z KSeF Rysunek: Pobranie pojedynczej faktury z KSeF (kosztowej lub sprzedażowej)

Opis przebiegu procesu:

1. W pierwszym kroku, należy wywołać operację ksefSessionOpen w celu utworzenia sesji interaktywnej w ramach której będą wykonywane pozostałe operacje. 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. Krok opcjonalny. Sprawdzamy czy sesja, którą wcześniej utworzyliśmy nadal jest 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).

4. Jeśli w odpowiedzi na wywołanie metody ksefSessionStatus, otrzymaliśmy informację o aktywnym statusie sesji, to możemy przystąpić do pobrania faktury wywołując operację ksefInvoiceGet.

5. Pobraną fakturę w postaci pliku XML, należy zapisać po stronie Systemu wywołującego.

6. 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 4-5. W przeciwnym przypadku, należy zamknąć sesję wywołując operację ksefSessionClose.

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

Operacje

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

KSeF REST API - interfejs Rysunek: Interfejs REST KSeF API

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 (KsefSessionOpenRequest). Metoda na wejściu nie wymaga żadnego parametru, a na wyjściu zwraca odpowiedź zgodną z KsefPublicKeyResponse.

KSeF REST API - pobranie klucza publicznego KSeF Rysunek: ksefPublicKey

Algorithm

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

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.

KSeF REST API - status sesji Rysunek: ksefSessionStatus

SessionId

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

SessionStatus

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

KsefSessionStatusResponse

Odpowiedź zawierająca status danej sesji interaktywnej status : SessionStatus – Jeden z dwóch możliwych statusów sesji interaktywnej zdefiniowanych w enumie SessionStatus

ksefSessionClose

ksefSessionClose(sessionId : SessionId): KsefSessionCloseResponse Metoda umożliwia zamknięcie sesji 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.

KSeF REST API - zamknięcie sesji Rysunek: ksefSessionClose

SessionId

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

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.

KSeF REST API - pobranie upo Rysunek: ksefSessionUpo

SessionId

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

TextXmlContent

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

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.

KSeF REST API - sprawdzenie statusu odebrania faktury przez KSeF Rysunek: 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)

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.

KsefInvoiceStatusResponse

Klasa reprezentuje odpowiedź systemu KSeF w kontekście statusu przetwarzania przesłanej do KSeF faktury. acquisitionTimestamp : string – Atrybut opcjonalny, informuje o dokładnej dacie i czasie przyjęcia faktury przez KSeF. Atrybut zawiera wartość tylko w przypadku kiedy status przesłanej faktury ma wartość accepted. (Wymagalność: [0..1]) invoiceNumber : string – Atrybut opcjonalny, zwraca informacje o numerze faktury nadanej przez podmiot wystawiający fakturę. Atrybut zawiera wartość tylko w przypadku kiedy status przesłanej faktury ma wartość accepted. (Wymagalność: [0..1]) ksefReferenceNumber : string – Atrybut opcjonalny, zwraca informacje o numerze KSeF faktury, który jest nadawany przez KSeF i w ramach KSeF jest unikalny. Atrybut odnosi się do tego samego co parametr InvoiceKsefNumber. Atrybut zawiera wartość tylko w przypadku kiedy status przesłanej faktury ma wartość accepted. (Wymagalność: [0..1]) status : InvoiceStatus – Atrybut zwraca aktualny status przesłanej faktury. Wartość zgodna z pozycjami w enumeracji InvoiceStatus.

ksefInvoiceGet

ksefInvoiceGet(sessionId : SessionId, invoiceKsefNumber : InvoiceKsefNumber): KsefInvoiceGetContent Metoda pozwala pobrać pojedynczą fakturę z KSeF podając numer KSeF faktury. Uwaga! Wywołanie metody wymaga wcześniejszego otwarcia sesji interaktywnej z wykorzystaniem operacji ksefSessionOpen. Metoda na wejściu wymaga przesłania w ścieżce wywołania (URL) dwóch parametrów: InvoiceKsefNumber oraz SessionId, 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.

KSeF REST API - pobranie faktury z KseF Rysunek: ksefInvoiceGet

SessionId

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

InvoiceKsefNumber

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

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

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

ksefInvoiceQueryStatus

ksefInvoiceQueryStatus(sessionId : SessionId, queryId : QueryId): KsefInvoiceQueryStatusResponse Metoda pozwala uzyskać status wyszukiwania faktur w KSeF. Uwaga! Wywołanie metody wymaga wcześniejszego otwarcia sesji interaktywnej z wykorzystaniem operacji ksefSessionOpen oraz wywołania operacji ksefInvoiceQueryStart w odpowiedzi której zwracany jest identyfikator wyszukiwania (QueryId) Metoda na wejściu wymaga przesłania w ścieżce wywołania (URL) dwóch parametrów: QueryId oraz SessionId, a na wyjściu zwraca odpowiedź zgodną z KsefInvoiceQueryStatusResponse.

KSeF REST API - sprawdzenie statusu wyszukiwania faktur Rysunek: ksefInvoiceQueryStatus

SessionId

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

QueryId

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

KsefInvoiceQueryStatusResponse

Obiekt reprezentuje wynik wyszukiwania faktur w KSeF items[] : 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(sessionId : SessionId, queryId : QueryId, queryPartNumber : QueryPartNumber): KsefInvoiceQueryResultZipContent Metoda pozwala pobrać wszystkie faktury znalezione w KSeF. Uwaga! Wywołanie metody wymaga wcześniejszego wywołania operacji: ksefSessionOpen, która zwróci identyfikator sesji (SessionId) oraz ksefInvoiceQueryStart, która w odpowiedzi zwraca identyfikator wyszukiwania (QueryId). Uwaga! Jeśli sesja (ksefSessionOpen) była otwierana z szyfrowaniem, to 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 (ksefSessionOpen). Metoda na wejściu wymaga przesłania w ścieżce wywołania (URL) trzech parametrów: SessionId, QueryId oraz QueryPartNumber, a na wyjściu zwraca odpowiedź zgodną z ApplicationZipContent.

KSeF REST API - pobranie wyników wyszukiwania faktur KSeF Rysunek: ksefInvoiceQueryResult

SessionId

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

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

POST

Metody typu HTTP POST.

ksefSessionOpen

ksefSessionOpen(invoice : KsefSessionOpenRequest): KsefSessionOpenResponse 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 KsefSessionOpenRequest, a na wyjściu zwraca odpowiedź zgodną z KsefSessionOpenResponse.

KSeF REST API - otwarcie sesji Rysunek: ksefSessionOpen

KsefSessionOpenRequest

Klasa reprezentuje żądanie utworzenia sesji interaktywnej 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ść: [0..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ść: [0..1]) invoiceVersion : KsefInvoiceVersion – Wskazanie w jakiej wersji schemy będą przesyłane faktury KSeF w ramach ustanowionej sesji.

KsefInvoiceVersion

Wersja schemy dla faktur KSeF v1 : – Pierwsza wersja schemy v2 : – Druga wersja schemy (obowiązująca)

KsefSessionOpenResponse

Odpowiedź w przypadku poprawnie utworzonej sesji created : string – Atrybut zawiera datę i czas utworzenia sesji w formacie data-czas. 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.

ksefInvoiceGenerate

ksefInvoiceGenerate(ksefInvoiceGenerateRequest : KsefInvoiceGenerateRequest): KsefInvoiceGenerateResponse Metoda umożliwiająca wygenerowanie faktury ustrukturyzowanej XML zgodnej z bieżącą (aktualną) wersją schemy wykorzystywanej w KSeF.

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

KSeF REST API - generowanie faktury Rysunek: ksefInvoiceGenerate

KsefInvoiceGenerateRequest

Klasa reprezentuje atrybuty wejściowe opisujące fakturę KSeF

KsefInvoiceGenerateResponse

Klasa reprezentuje odpowiedź zwracaną przez operację ksefInvoiceGenerate, która zawiera wygenerowaną fakturę KSeF zgodną ze schemą obowiązującą w KSeF.

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

KSeF REST API - walidacja faktury Rysunek: ksefInvoiceValidate

KsefInvoiceVersion

Wersja schemy dla faktur KSeF v1 : – Pierwsza wersja schemy v2 : – Druga wersja schemy (obowiązująca)

TextXmlContent

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

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 dwóch możliwych 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.

ksefInvoiceSend

ksefInvoiceSend(invoice : KsefInvoiceSendRequest): KsefInvoiceSendResponse Metoda umożliwia wysłanie jednej faktury do systemu KSeF w ramach zestawionej sesji interaktywnej. 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ę ksefSessionOpen w celu zestawienia sesji interaktywnej. Metoda na wejściu wymaga utworzenia żądania zgodnego z KsefInvoiceSendRequest, a na wyjściu zwraca odpowiedź zgodną z KsefInvoiceSendResponse.

KSeF REST API - wysłanie faktury do KSeF Rysunek: ksefInvoiceSend

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 (KsefSessionOpenRequest). (Wymagalność: [0..1]) plain : KsefInvoicePlain – Atrybut określa wariant (choice), który służy do przesłania niezaszyfrowanego XML faktury w sesji utworzonej z bez szyfrowania. (Wymagalność: [0..1]) sessionId : string – Identyfikator sesji uzyskany podczas ustanawiania sesji interaktywnej: ksefSessionOpen.

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

KsefInvoicePlain

Obiekt reprezentuje przesyłaną fakturę w formie jawnej (niezaszyfrowaną) invoice : string – Atrybut zawierający plik XML faktury w niezaszyfrowanej postaci bajtów z kodowaniem UTF-8, która jest wysyłana do KSeF.

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. Uwaga! Wywołanie metody wymaga wcześniejszego otwarcia sesji interaktywnej z wykorzystaniem operacji ksefSessionOpen. Metoda na wejściu wymaga przesłania żądania zgodnego z KsefInvoiceQueryStartRequest. Metoda zwraca obiekt zgodny z KsefInvoiceQueryStartResponse, który zawiera identyfikator wyszukiwania.

KSeF REST API - rozpoczęcie procesu wyszukania faktur w KSeF Rysunek: ksefInvoiceQueryStart

KsefInvoiceQueryStartRequest

Klasa reprezentuje żądanie pozwalające na zdefiniowanie parametrów wyszukiwania range : KsefInvoiceQueryStartRange – Wybór okresu dla jakiego mają zostać wyszukane faktury (Wymagalność: [0..1]) sessionId : string – Identyfikator aktywnej sesji subjectType : SubjectType – Określenie jakiego typu faktury wyszukujemy:

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

KsefInvoiceQueryStartRange

Klasa reprezentuje okres dla jakiego mają zostać wyszukane faktury from : string – Data od której będą wyszukiwane faktury. to : string – Data do której będą wyszukiwane faktury.

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.

KSeF REST API - wizualizacja faktury KSeF Rysunek: ksefInvoiceVisualize

KsefInvoiceVisualizeRequest

Klasa umożliwia zdefiniowanie parametrów związanych z wizualizacją faktury ustrukturyzowanej (faktury KSeF) includeLogo : boolean – Atrybut określa czy do wizualizacji ma zostać dołączone logo. includeQrCode : 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. invoiceData : string – Atrybut przekazuje plik XML faktury KSeF dla której ma zostać wykonana wizualizacja. invoiceKsefNumber : string – Atrybut zawiera unikalny numer KSeF faktury nadany przez Krajowy System e-Faktur podczas poprawnego wysłania faktury do KSeF. outputFormat : OutputFormat – Atrybut może przyjmować jedną z dwóch możliwych do wprowadzenia wartości zdefiniowanych w enumeracji OutputFormat:

html
pdf

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

pl
en
pl_en

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.

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

KSeF REST API - parametry Rysunek: 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

InvoiceKsefNumber

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

KsefInvoicePlain

Obiekt reprezentuje przesyłaną fakturę w formie jawnej (niezaszyfrowaną). invoice : string – Atrybut zawierający plik XML faktury w niezaszyfrowanej postaci bajtów z kodowaniem UTF-8, która jest wysyłana do KSeF.

KsefInvoiceQueryStartRange

Klasa reprezentuje okres dla jakiego mają zostać wyszukane faktury. 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ść: [0..1]) sessionId : string – Identyfikator aktywnej sesji subjectType : SubjectType – Określenie jakiego typu faktury wyszukujemy:

sprzedażowe (subject1),
kosztowe (subject2),
podmiotu trzeciego (subject3),
podmiotu uprawnionego (subjectAuthorized)

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 (KsefSessionOpenRequest). (Wymagalność: [0..1]) plain : KsefInvoicePlain – Atrybut określa wariant (choice), który służy do przesłania niezaszyfrowanego XML faktury w sesji utworzonej z bez szyfrowania. (Wymagalność: [0..1]) sessionId : string – Identyfikator sesji uzyskany podczas ustanawiania sesji interaktywnej: ksefSessionOpen.

KsefSessionOpenRequest

KsefInvoiceVisualizeRequest

Klasa umożliwia zdefiniowanie parametrów związanych z wizualizacją faktury ustrukturyzowanej (faktury KSeF). includeLogo : boolean – Atrybut określa czy do wizualizacji ma zostać dołączone logo. includeQrCode : 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. invoiceData : string – Atrybut przekazuje plik XML faktury KSeF dla której ma zostać wykonana wizualizacja. invoiceKsefNumber : string – Atrybut zawiera unikalny numer KSeF faktury nadany przez Krajowy System e-Faktur podczas poprawnego wysłania faktury do KSeF. outputFormat : OutputFormat – Atrybut może przyjmować jedną z dwóch możliwych do wprowadzenia wartości zdefiniowanych w enumeracji OutputFormat:

html
pdf

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

pl
en
pl_en

Enumeracje

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

KSeF REST API - Enumeracje Rysunek: 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.