API KSeF 2.0 dla programistów: uwierzytelnianie, sesje, FA(3), UPO, offline

KSeF 2.0 to interfejs REST API Ministerstwa Finansów dla Krajowego Systemu e-Faktur. Integracja uwierzytelnia się za pomocą wyzwania (challenge) podpisanego certyfikatem kwalifikowanym lub zaszyfrowanego tokenem KSeF, wymienia wynik na krótkotrwały JWT, otwiera sesję z wygenerowanym przez siebie kluczem AES, przesyła faktury XML FA(3) zaszyfrowane tym kluczem, odpytuje o ich status i pobiera UPO — urzędowe poświadczenie, które nadaje fakturze numer KSeF i byt prawny. Ten przewodnik podąża za tą sekwencją, a następnie omawia wysyłkę wsadową, tryby offline, limity oraz to, jak moduł KSeF w KRONENWERK odwzorowuje ten proces.

Środowiska

Istnieją trzy publiczne środowiska i nie są one wymienne. Wszystko poniżej dotyczy wszystkich trzech; o wyborze decyduje adres bazowy.

Dokumentacja API jest udostępniana pod ścieżką /docs/v2 pod każdym adresem bazowym, a ten sam opis OpenAPI, przewodniki i oficjalne biblioteki klienckie (C# i Java) publikuje organizacja CIRFMF Ministerstwa na GitHubie. Od 1 października 2025 r. środowiska testowe mają zaplanowane okna serwisowe (16:00–18:00), podczas których wywołania mogą się nie powieść. Nigdy nie należy przesyłać faktur produkcyjnych ani prawdziwych danych podmiotów do środowisk TEST lub DEMO.

Uwierzytelnianie

Każde chronione wywołanie zawiera token dostępowy JWT. Jego uzyskanie to pięcioetapowy proces, którego pierwszy i ostatni krok są takie same niezależnie od rodzaju poświadczenia.

1. Challenge. POST /auth/challenge zwraca wartość wyzwania i znacznik czasu. Jest ważne przez 10 minut.
2. Potwierdzenie tożsamości na jeden z dwóch sposobów:
   • Podpis XAdES. Należy zbudować XML AuthTokenRequest zawierający wyzwanie, identyfikator kontekstu (NIP, identyfikator wewnętrzny lub identyfikator VAT UE podmiotu, w imieniu którego Państwo działają) oraz typ identyfikatora podmiotu, podpisać go w formacie XAdES certyfikatem kwalifikowanym (osobisty lub organizacyjny certyfikat kwalifikowany, Profil Zaufany, certyfikat KSeF lub certyfikat dostawcy Peppol) i wysłać do POST /auth/xades-signature.
   • Token KSeF. Należy połączyć {ksefToken}|{timestampMs}, zaszyfrować RSA-OAEP (SHA-256, MGF1) opublikowanym kluczem publicznym Ministerstwa, zakodować w Base64 i wysłać razem z wyzwaniem i kontekstem do POST /auth/ksef-token. Tokeny KSeF są wydawane wewnątrz KSeF przez osobę, która już posiada uprawnienia do podmiotu; nadają się do integracji bezobsługowych.
   Każde z tych wywołań zwraca tymczasowy token uwierzytelniający i numer referencyjny.
3. Odpytywanie. GET /auth/{referenceNumber} z tokenem tymczasowym, aż status będzie ostateczny. Weryfikacja jest asynchroniczna — system sprawdza podpis i certyfikat wobec OCSP/CRL.
4. Wymiana. POST /auth/token/redeem jednorazowo wymienia token tymczasowy na accessToken (JWT, około 15 minut, dokładny czas życia jest w jego polu exp) oraz refreshToken (około 7 dni).
5. Odświeżanie. POST /auth/token/refresh z tokenem odświeżającym zwraca nowy token dostępowy z aktualnymi uprawnieniami podmiotu.

Uprawnienia nadaje się w KSeF per podmiot i per rola (wystawianie, odczyt, zarządzanie poświadczeniami itd.); token dostępowy odzwierciedla uprawnienia z chwili wydania i jest unieważniany po ich odebraniu. Polityka autoryzacji może ograniczyć token do adresów lub zakresów IP. Oba tokeny należy przechowywać jako sekrety.

Sesja interaktywna: wysyłka, status, UPO

Sesja interaktywna przesyła faktury pojedynczo, synchronicznie na poziomie transmisji i asynchronicznie na poziomie przetwarzania. Jest to tryb używany przez większość oprogramowania do fakturowania.

1. Przygotowanie klucza. Należy wygenerować 256-bitowy klucz AES i 128-bitowy IV. Klucz szyfruje się kluczem publicznym RSA Ministerstwa (RSAES-OAEP, MGF1 z SHA-256). Biblioteki klienckie Ministerstwa zawierają CryptographyService, który to wykonuje.
2. Otwarcie. POST /sessions/online z wersją schematu (FA(3) — aktualny schemat faktury; FA(2) jest nadal wymieniany w dokumentacji) i zaszyfrowanym kluczem. Odpowiedź zawiera referenceNumber sesji i validUntil. Sesja żyje 12 godzin, a pod jednym tokenem dostępowym może być otwartych równolegle kilka sesji.
3. Wysyłka. POST /sessions/online/{referenceNumber}/invoices z fakturą zaszyfrowaną AES-256-CBC z dopełnieniem PKCS#7 i zakodowaną w Base64, plus skrót SHA-256 i rozmiar zarówno pliku jawnego, jak i zaszyfrowanego. Odpowiedź potwierdza przyjęcie; walidacja wobec schematu i reguł biznesowych zaczyna się natychmiast i asynchronicznie.
4. Odpytywanie. GET /sessions/{referenceNumber}/invoices wymienia status każdej faktury: przyjęta z numerem KSeF lub odrzucona z podaniem przyczyny. Należy odpytywać z wykładniczym opóźnieniem, a nie w ciasnej pętli.
5. Zamknięcie. POST /sessions/online/{referenceNumber}/close kończy sesję i uruchamia generowanie zbiorczego UPO.
6. Pobranie UPO. UPO (Urzędowe Poświadczenie Odbioru) to podpisany dokument XML wymieniający przyjęte faktury z ich numerami KSeF i znacznikami czasu przyjęcia. Należy je przechowywać razem z fakturami: jest dowodem, że faktura została wystawiona w sensie prawnym.

To numer KSeF, a nie Państwa numer wewnętrzny, widzi nabywca w swojej skrzynce KSeF i to on może być wymagany w tytule płatności. Datą wystawienia dla celów VAT jest data przyjęcia faktury przez KSeF, która może różnić się od daty w FA(3) — kwestia ta w każdym konkretnym przypadku wymaga potwierdzenia przez specjalistę.

Sesja wsadowa

Sesja wsadowa przesyła wiele faktur jako jeden zaszyfrowany plik ZIP. Nadaje się do przetwarzania na koniec miesiąca i migracji.

1. Pliki XML FA(3) należy umieścić w archiwum ZIP.
2. Binarny ZIP należy podzielić na części o rozmiarze maksymalnie 100 MB, numerowane po kolei.
3. Każdą część szyfruje się AES-256-CBC według tego samego schematu klucza co powyżej; oblicza się SHA-256 i rozmiar każdej zaszyfrowanej części.
4. POST /sessions/batch z zaszyfrowanym kluczem, metadanymi ZIP, wersją schematu i listą części. Odpowiedź zwraca referenceNumber oraz, dla każdej części, adres URL, metodę i nagłówki do przesłania.
5. Każdą część przesyła się jako surowe dane binarne pod jej adres URL. Okno przesyłania wynosi 20 minut na zadeklarowaną część, sumowane.
6. POST /sessions/batch/{referenceNumber}/close, następnie odpytanie o status sesji i pobranie zbiorczego UPO jak w sesji interaktywnej.

Oba typy sesji przyjmują do 10 000 faktur. Faktura może mieć maksymalnie 1 MB lub 3 MB z załącznikiem.

Odczyt faktur

Strona odbiorcza jest symetryczna. POST /invoices/query/metadata zwraca metadane faktur dla typu podmiotu (wystawca, odbiorca itd.) i zakresu dat, stronicowane za pomocą pageOffset i pageSize. GET /invoices/ksef/{ksefNumber} pobiera jedną fakturę po numerze KSeF. Do pobierania masowego POST /invoices/exports uruchamia asynchroniczny eksport pod dostarczonym przez Państwa kluczem szyfrującym, a GET /invoices/exports/{referenceNumber} raportuje postęp i zwraca zaszyfrowaną paczkę. Integracja, która musi widzieć każdą fakturę zakupu, odpytuje zapytanie o metadane przyrostowo, zamiast wielokrotnie eksportować.

Tryby offline

Trzy tryby pozwalają podatnikowi wystawiać poza KSeF i przesyłać później. Każdy ma własny warunek uruchomienia i termin, a każdy jest prawnie odrębny.

Faktura offline to zwykła FA(3) z dwoma wydrukowanymi lub osadzonymi kodami QR: KOD I, który pozwala nabywcy zweryfikować fakturę w KSeF, oraz KOD II, który potwierdza tożsamość wystawcy na podstawie jego certyfikatu KSeF. Przy późniejszym przesyłaniu należy ustawić offlineMode: true w żądaniu wysyłki w dowolnym typie sesji. Jeśli KSeF stanie się niedostępny w oknie przesyłania, termin biegnie od nowa i może sięgać 7 dni roboczych od zakończenia przerwy.

Limity i błędy

Ministerstwo dokumentuje limity per kontekst (podmiot, w imieniu którego Państwo działają) i per poświadczenie, a nie per klucz API: 10 000 faktur na sesję, 1 MB lub 3 MB na fakturę, 100 MB na część wsadu oraz limity wniosków o certyfikaty i aktywnych certyfikatów per identyfikator (dla NIP: 300 wniosków i 100 aktywnych certyfikatów w chwili odczytu). Istnieją limity częstotliwości żądań — dokumentacja mówi, że system ogranicza liczbę żądań w celu ochrony stabilności — opisane w osobnym dokumencie o limitach; należy projektować z myślą o HTTP 429 z ponawianiem i wykładniczym opóźnieniem, a nie o stałej wartości.

Błędy wracają jako status HTTP z treścią JSON opisującą problem: 400 dla wadliwych żądań, 401 dla brakującego lub wygasłego tokenu, 403 dla uprawnienia, którego token nie zawiera, a błędy walidacji poszczególnych faktur są raportowane w statusie sesji, a nie w wywołaniu wysyłki. Błędy schematu (XML nie pasuje do FA(3)) i błędy semantyczne (nieistniejący NIP, data poza dozwolonym oknem, duplikat) ujawniają się na różnych etapach; należy czytać wpis statusu każdej faktury, zamiast ufać kodowi 2xx przy przesłaniu.

Jak KRONENWERK to obsługuje

JESZCZE NIEGOTOWE Moduł KSeF 2.0 w KRONENWERK implementuje opisany powyżej przepływ: uwierzytelnianie tokenem (challenge, zaszyfrowany token KSeF, wymiana, odświeżanie), sesję interaktywną z kluczem AES generowanym dla każdej sesji, generowanie i wysyłkę FA(3), odpytywanie o status, pobieranie UPO oraz odczyt otrzymanych faktur. Jest zależny od środowiska poprzez konfigurację — ten sam kod kieruje się do TEST, DEMO lub produkcji zgodnie z ustawieniami — i nie był używany wobec produkcyjnego KSeF. Z tego powodu KRONENWERK obecnie nie sprzedaje subskrypcji polskim firmom i nic na tej stronie nie należy odczytywać jako gotowości produkcyjnej. Samo generowanie FA(3) jest OBSŁUGIWANE Z OGRANICZENIAMI: XML jest tworzony i sprawdzany wobec schematu przy wystawianiu, ale przesyłanie oraz wynikający z niego numer KSeF i UPO zależą od sprawdzenia modułu w produkcji. Publiczne API nie udostępnia operacji KSeF: POST /invoices/drafts tworzy szkic, wystawianie odbywa się w produkcie, a żaden punkt końcowy nie przesyła FA(3), nie zwraca numeru KSeF ani nie pobiera UPO. Zob. integracja KSeF — co oferuje API, KSeF — wyjaśnienie i FA(3) — format, oraz przegląd Polski i stronę krajową — aktualny status.