KSeF 2.0 wyjaśniony: uwierzytelnianie, sesje, UPO, tryby offline, kody QR

KSeF 2.0 to wersja Krajowego Systemu e-Faktur, która jako jedyna obowiązuje od 1 lutego 2026 r., kiedy wyłączono KSeF 1.0. Oprogramowanie uwierzytelnia się podpisem kwalifikowanym lub tokenem KSeF i otrzymuje tokeny dostępowe JWT, otwiera sesję interaktywną lub wsadową, wysyła zaszyfrowany AES XML FA(3) i otrzymuje z powrotem 35-znakowy numer KSeF dla każdej faktury oraz Urzędowe Poświadczenie Odbioru (UPO) dla sesji. Tryby offline, kody QR i certyfikaty KSeF obejmują przypadki, w których faktura dociera do nabywcy poza systemem.

Co zmieniło się między KSeF 1.0 a 2.0

KSeF 2.0 to nowy kontrakt API, nie poprawka: uwierzytelnianie oddzielono od sesji, tokeny JWT zastąpiły dawne logowanie powiązane z sesją, szyfrowanie stało się obowiązkowe w każdym trybie, nazwy ujednolicono w stylu REST i dodano moduł certyfikatów.

Własny przegląd Ministerstwa dla integratorów wymienia kluczowe zmiany: uwierzytelnianie jako niezależny krok dający tokeny wielokrotnego użytku, odświeżalne i odwoływalne; jeden model inicjalizacji zarówno dla POST /sessions/online, jak i POST /sessions/batch, z których każdy przyjmuje kod formularza i zaszyfrowany klucz AES; obowiązkowe szyfrowanie każdej faktury po stronie klienta z RSA-OAEP (SHA-256, MGF1-SHA-256) chroniącym klucz sesji; spójne identyfikatory (NIP, PESEL, odcisk palca) jako jawne wyliczenia; oraz wewnętrzne certyfikaty KSeF do uwierzytelniania i wystawiania offline. API jest opisane w OpenAPI 3.0.4 z interaktywną dokumentacją pod adresem api.ksef.mf.gov.pl/docs/v2, a Ministerstwo publikuje biblioteki klienckie open source dla C# i Javy.

Środowiska: test, demo, produkcja

Istnieją trzy środowiska publiczne, a tylko produkcyjne ma skutki prawne.

Harmonogram Ministerstwa: otwarte testy API rozpoczęły się 30 września 2025 r., API demo otwarto 15 października 2025 r., środowisko testowe KSeF 1.0 zamknięto 1 września 2025 r., a produkcyjny KSeF 2.0 uruchomiono 1 lutego 2026 r. po przerwie technicznej od 26 do 31 stycznia. Adresy URL zwracane przez API zawsze wskazują na wywołane środowisko. Planowane prace serwisowe na środowiskach testowych mogą odbywać się w godzinach 16:00–18:00, a w changelogu ogłaszane są wyłącznie zmiany istotne dla integracji.

Uwierzytelnianie: podpis, token KSeF, certyfikaty

Każde chronione wywołanie wymaga JWT accessToken. Aby go uzyskać, klient dowodzi, kim jest (podmiot uwierzytelniający) i w czyim imieniu działa (kontekst, zwykle NIP), a KSeF sprawdza, czy podmiot posiada co najmniej jedno aktywne uprawnienie w tym kontekście.

1. Challenge. POST /auth/challenge zwraca challenge ważny przez 10 minut.
2. Dowód tożsamości, na jeden z dwóch sposobów:
   • Podpis XAdES. Klient buduje XML AuthTokenRequest (challenge, identyfikator kontekstu — NIP, identyfikator wewnętrzny lub złożony NIP-VAT-UE — oraz typ identyfikatora podmiotu certificateSubject lub certificateFingerprint, opcjonalnie polityka dozwolonych adresów IP) i go podpisuje. Akceptowani podpisujący: certyfikat kwalifikowany osoby fizycznej zawierający PESEL lub NIP, kwalifikowana pieczęć organizacji zawierająca NIP, podpis Profilem Zaufanym, certyfikat KSeF lub certyfikat dostawcy usług Peppol. Certyfikaty samopodpisane są akceptowane wyłącznie na środowisku TEST.
   • Token KSeF. Żądanie JSON z wcześniej wygenerowanym tokenem systemowym. Tokeny generuje się przez POST /tokens po co najmniej jednym uwierzytelnieniu XAdES, zawierają listę uprawnień, takich jak InvoiceRead, InvoiceWrite, CredentialsRead, CredentialsManage, i są poufnymi sekretami.
3. Tokeny. Odpowiedź daje accessToken i refreshToken; tokeny dostępowe wygasają, można je odświeżyć bez ponownego uwierzytelniania, a są automatycznie odwoływane po utracie uprawnień. Sesje są wymienione pod GET /auth/sessions i odwoływane przez DELETE /auth/sessions/current lub według numeru referencyjnego.

Certyfikaty KSeF są wydawane przez sam system i nie są certyfikatami kwalifikowanymi. Certyfikat ma dokładnie jeden typ: Authentication (użycie klucza: podpis cyfrowy) do logowania albo Offline (użycie klucza: niezaprzeczalność) do podpisywania drugiego kodu QR na fakturach offline; nie może robić obu rzeczy. Wnioskowanie (/certificates/enrollments) jest możliwe wyłącznie po uwierzytelnieniu XAdES, we własnym imieniu podmiotu, z CSR w formacie PKCS#10, a certyfikat jest ważny maksymalnie dwa lata. Domyślne limity: 300 wniosków i 100 aktywnych certyfikatów na NIP, 12 i 6 na PESEL lub odcisk palca.

Same uprawnienia nadaje się w systemie: firma, która nie ma pieczęci kwalifikowanej, wyznacza osobę fizyczną na formularzu ZAW-FA, a ta osoba nadaje następnie dalsze prawa, na przykład księgowemu lub certyfikatowi integratora oprogramowania.

Sesje: interaktywna i wsadowa

Sesja interaktywna wysyła faktury pojedynczo i pasuje do oprogramowania fakturującego; sesja wsadowa wysyła ZIP zawierający do 10 000 faktur w zaszyfrowanych częściach o rozmiarze najwyżej 100 MB i pasuje do przesyłania masowego. Obie zaczynają się od tego samego JSON: kodu formularza (wersji schematu) i klucza AES sesji zaszyfrowanego kluczem publicznym Ministerstwa.

Interaktywna

1. Wygenerować 256-bitowy klucz AES i 128-bitowy IV; zaszyfrować klucz przy użyciu RSA-OAEP aktualnym kluczem publicznym z GET /security/public-key-certificates.
2. POST /sessions/online z kodem formularza (FA(3)) i zaszyfrowanym kluczem. Odpowiedź daje referenceNumber i validUntil; sesja żyje 12 godzin, a kilka może być otwartych równolegle.
3. POST /sessions/online/{referenceNumber}/invoices z każdą fakturą zaszyfrowaną AES-256-CBC (dopełnienie PKCS#7), jej hashem i rozmiarem. Odpowiedź zwraca numer referencyjny dokumentu.
4. Odpytywać GET /sessions/{referenceNumber} i GET /sessions/{referenceNumber}/invoices o status każdej faktury, numer KSeF i UPO faktury.
5. POST /sessions/online/{referenceNumber}/close. Zamknięcie uruchamia asynchroniczne generowanie zbiorczego UPO dla sesji.

Wsadowa

Klient pakuje pliki XML do ZIP, dzieli ZIP binarnie na części o rozmiarze najwyżej 100 MB przed szyfrowaniem, szyfruje każdą część, opisuje części w fileParts przy otwieraniu POST /sessions/batch, wgrywa je pod zwrócone adresy URL i zamyka sesję. Ministerstwo zaleca zapisywanie hasha SHA-256 dla każdego oryginalnego XML, aby statusy KSeF można było dopasować do dokumentów lokalnych. Domyślne limity na kontekst: 1 MB na fakturę (3 MB z załącznikiem), 10 000 faktur na sesję, 500 na identyfikator zbiorczy.

Numer KSeF i UPO

Numer KSeF jest dowodem, że faktura istnieje; UPO (Urzędowe Poświadczenie Odbioru) jest urzędowym potwierdzeniem sesji i jej faktur.

Numer ma zawsze 35 znaków: NIP-RRRRMMDD-XXXXXXXXXXXX-CC — dziesięciocyfrowy NIP sprzedawcy, data przyjęcia faktury do przetwarzania, dwunastoznakowa szesnastkowa część techniczna i dwuznakowa suma kontrolna CRC-8 (wielomian 0x07, wartość początkowa 0x00). Oprogramowanie może zwalidować numer offline, przeliczając sumę kontrolną. Nie wolno go mylić z własnym numerem faktury sprzedawcy w polu P_2.

Przed nadaniem numeru KSeF sprawdza dwie rzeczy: czy XML jest zgodny z aktualnym schematem oraz czy nadawca ma prawo wystawiać w tym kontekście. Odrzucony plik nie jest fakturą; poprawia się go i przesyła ponownie, a nie „koryguje" fakturą korygującą. Dla faktury online datą wystawienia jest data przesłania, o ile pole P_1 jest z nią zgodne, nawet jeśli numer nadejdzie następnego dnia.

Tryby offline

Cztery tryby pozwalają kontynuować wystawianie, gdy połączenie lub system nie są dostępne; trzy z nich wymagają późniejszego przesłania faktury do KSeF, z offlineMode: true, w terminie ustawowym.

W trybach offline datą wystawienia jest data w P_1, a nie data przesłania. Z wyjątkiem trybu awaryjnego nabywca otrzymuje fakturę w KSeF i nie dostaje kopii przed przesłaniem; w trybie awaryjnym plik FA(3) jest doręczany nabywcy w uzgodniony sposób i numerowany później. Jeśli ogłoszona awaria przypada w oknie offline24 lub niedostępności, termin przesuwa się na 7 dni roboczych po zakończeniu tej awarii. Faktury wystawionej poza KSeF nie wolno nigdy wystawić ponownie w systemie — powstałyby dwie faktury dla jednej sprzedaży.

Kody QR na wizualizacjach

Wizualizacja przekazana poza KSeF — PDF, wydruk, załącznik e-mail — zawiera kod QR, aby każdy mógł zweryfikować fakturę w systemie; faktury offline zawierają dwa.

• KOD I prowadzi do strony weryfikacji i pozwala posiadaczowi sprawdzić oraz, z dodatkowymi danymi, pobrać fakturę. Pod nim widnieje numer KSeF, jeśli jest znany, lub słowo OFFLINE przed nadaniem numeru.
• KOD II potwierdza tożsamość wystawcy dla faktur offline. Jest podpisany certyfikatem KSeF typu Offline; certyfikatu Authentication nie można użyć. KSeF weryfikuje, czy certyfikat istnieje, jest ważny, nieodwołany i niezablokowany oraz czy jego podmiot posiada aktywne uprawnienia do wystawiania w danym kontekście.

Kody są generowane lokalnie przez klienta z danych faktury (ISO/IEC 18004:2024), a host linku odpowiada środowisku. Wizualizację można przekazać nabywcy dopiero po zarejestrowaniu faktury w KSeF, z wyjątkiem trybu awaryjnego.

Odbieranie faktur

Nabywcy pobierają faktury z KSeF zamiast otrzymywać je e-mailem. API oferuje zapytania o faktury i przyrostowe pobieranie nowo wystawionych faktur w kontekście nabywcy, a Ministerstwo potwierdza, że oprogramowanie może pobierać je automatycznie. Nabywcy zagraniczni bez NIP nie mogą się zalogować i zamiast tego otrzymują kopię z KOD I. Plik FA(3), który wraca z systemu, jest udokumentowany na stronie schematu FA(3).

Jak KRONENWERK to obsługuje

Jeszcze niegotowe w zakresie przesyłania. Moduł KSeF 2.0 w KRONENWERK — uwierzytelnianie tokenem, sesja interaktywna, przesyłanie FA(3), pobieranie UPO i odbieranie — jest zbudowany i zależny od środowiska, a nie był używany z produkcyjnym KSeF. Generowanie FA(3) i walidacja schematu są Obsługiwane z ograniczeniami. KRONENWERK nie sprzedaje subskrypcji polskim firmom, dopóki przesyłanie produkcyjne nie zostanie potwierdzone; zob. centrum Polska oraz stronę kraju Polska.

Projekt jest zgodny z regułą, którą narzuca system: faktura nie jest „wystawiona" w KRONENWERK, dopóki KSeF nie zwróci numeru, a przesłanie, którego odpowiedź zaginęła, jest uzgadniane przez zapytanie KSeF, co posiada, a nie wysyłane ponownie, ponieważ ślepe ponowienie utworzyłoby drugą fakturę o mocy prawnej. Programiści integrujący własne systemy mogą porównać to z integracją KSeF oraz przewodnikiem KSeF krok po kroku. Ta strona opisuje system Ministerstwa; nie stanowi porady podatkowej ani prawnej.

Najczęściej zadawane pytania

Czy potrzebuję podpisu kwalifikowanego, aby korzystać z API KSeF?

Do pierwszego uwierzytelnienia — tak: certyfikat kwalifikowany, pieczęć kwalifikowana, podpis Profilem Zaufanym lub certyfikat KSeF. Później oprogramowanie może używać tokena KSeF lub certyfikatu KSeF typu Authentication.

Jaka jest różnica między numerem KSeF a UPO?

Numer KSeF to 35-znakowy identyfikator nadawany każdej przyjętej fakturze; UPO to urzędowe poświadczenie generowane dla sesji, dostępne po jej zamknięciu, a także dla pojedynczej faktury.

Co oznacza offline24?

Podatnik wystawia fakturę FA(3) bez połączenia i musi przesłać ją do KSeF do następnego dnia roboczego; nabywca otrzymuje ją w KSeF, a wizualizacja zawiera dwa kody QR.

Czy mogę testować na prawdziwych danych w środowisku testowym?

Nie. Ministerstwo wskazuje, że dane w środowisku TEST są współdzielone między integratorami i muszą używać losowych NIP-ów oraz danych zanonimizowanych; DEMO używa prawdziwych danych uwierzytelniających, ale nie ma skutków prawnych.

Czy każda faktura jest szyfrowana?

Tak. W KSeF 2.0 każda faktura, interaktywna czy wsadowa, jest szyfrowana po stronie klienta kluczem AES, który sam jest szyfrowany kluczem publicznym Ministerstwa przy otwieraniu sesji.