Integracja z KSeF: jak działa moduł KSeF 2.0 w KRONENWERK

KRONENWERK zawiera moduł KSeF 2.0, który uwierzytelnia się tokenem KSeF podatnika, otwiera sesję interaktywną, przesyła faktury FA(3) zaszyfrowane kluczem Ministerstwa, odpytuje o numer KSeF, pobiera UPO i odczytuje faktury przychodzące. Moduł został zbudowany i przetestowany na środowiskach Ministerstwa, ale nie był używany z produkcyjnym KSeF, a KRONENWERK nie sprzedaje obecnie subskrypcji polskim firmom, dopóki nie zostanie to udowodnione. Dla przesyłania status to JESZCZE NIEGOTOWE. Państwa integracja korzystałaby ze zwykłego API wokół modułu — klienci, wersje robocze, webhooki — i nic specyficznego dla KSeF nie jest udostępniane w API.

Czym jest KSeF, w jednym akapicie

KSeF (Krajowy System e-Faktur) to polski centralny system typu clearance: faktura ustrukturyzowana w schemacie FA(3) jest przesyłana do systemu Ministerstwa Finansów, który ją waliduje, nadaje numer KSeF i zwraca urzędowe poświadczenie odbioru (UPO). Dopóki ten numer nie istnieje, plik nie jest fakturą w sensie prawnym. To odróżnia Polskę od Niemiec, gdzie zgodny plik wysłany dowolną drogą wypełnia obowiązek, oraz od Belgii, gdzie drogą jest sieć Peppol. Tło znajduje się na stronie KSeF wyjaśniony; schemat na stronie FA(3); centrum wiedzy pod adresem e-fakturowanie w Polsce.

Co robi moduł KSeF 2.0 w KRONENWERK

Moduł implementuje KSeF API 2.0 zgodnie ze specyfikacją OpenAPI opublikowaną przez Ministerstwo (ścieżki i nazwy pól skopiowane stamtąd, a nie odtworzone z pamięci). Działa per podatnik: każde wywołanie odbywa się w kontekście jednego NIP z tokenem KSeF tego podatnika, a tokeny dostępu są buforowane per NIP i odświeżane przed wygaśnięciem.

Ministerstwo przewiduje dwie metody uwierzytelniania; moduł używa metody tokenem KSeF, w której wysyłany jest dokument JSON zawierający uprzednio uzyskany token systemowy, a nie żądanie XML podpisane XAdES. Token należy do firmy i jest jej wydawany wewnątrz KSeF; KRONENWERK przechowuje go w postaci zabezpieczonej i używa wyłącznie do uwierzytelniania. Ministerstwo dokumentuje obie metody i zaznacza, że certyfikaty samopodpisane są akceptowane wyłącznie w środowisku testowym.

Dlaczego moduł zależy od środowiska i nie jest jeszcze gotowy

Ministerstwo publikuje trzy środowiska, a moduł jest skonfigurowany w danym momencie na dokładnie jedno z nich:

Moduł KRONENWERK był ćwiczony na nieprodukcyjnych środowiskach Ministerstwa. Nie był używany z produkcyjnym KSeF, gdzie wysyłka jest czynnością prawną, od której zależy sytuacja podatkowa drugiej strony. Dopóki nie zostanie wykonana i zweryfikowana prawdziwa wysyłka z prawdziwym UPO, KRONENWERK oznacza przesyłanie jako JESZCZE NIEGOTOWE i nie sprzedaje subskrypcji polskim firmom. Jest to stwierdzenie o dowodzie, a nie o pokryciu kodu testami: różnica między „klient przechodzi swoje testy” a „Ministerstwo przyjęło naszą fakturę” jest tą, która się liczy, i tą, która wciąż pozostaje otwarta.

Samo generowanie FA(3) — tworzenie XML z faktów wersji roboczej i walidacja względem schematu — jest OBSŁUGIWANE Z OGRANICZENIAMI: dokument jest tworzony, ale plik FA(3) bez numeru KSeF nie jest fakturą, więc jego użyteczność ogranicza powyższy status przesyłania.

Jak deweloper korzystałby z API wokół modułu

Nic w API KRONENWERK nie jest specyficzne dla KSeF. Jeśli polska ścieżka stanie się dostępna, integracja wygląda dokładnie tak jak dla każdego innego kraju: praca związana z KSeF odbywa się wewnątrz wystawiania i przesyłania, które pozostają w produkcie.

1. Proszę utworzyć polskiego klienta przez POST /customers, podając country: "PL" i NIP nabywcy w polu vatId. FA(3) identyfikuje nabywcę po NIP, a klienta bez NIP nie można zafakturować przez KSeF.
2. Proszę rozpocząć wersję roboczą przez POST /invoices/drafts z nagłówkiem Idempotency-Key.
3. Osoba uzupełnia i wystawia wersję roboczą w produkcie. Moduł polski renderuje XML FA(3) i go waliduje; numer jest zużywany, a zdarzenie invoice.issued trafia do kolejki.
4. Osoba przesyła wystawioną fakturę z produktu. Moduł uwierzytelnia się tokenem KSeF firmy zapisanym w Ustawienia → Doręczanie, otwiera sesję, wysyła, odpytuje, zamyka i zapisuje numer KSeF oraz UPO. Nieznany wynik blokuje ponowną wysyłkę, dopóki zapytanie uzgadniające nie sprawdzi w KSeF, czy dokument już tam jest.
5. Państwa endpoint otrzymuje invoice.issued, a później invoice.paid lub invoice.cancelled. Numer KSeF, UPO i stan przesyłania są widoczne w produkcie i nie są dziś dostępne w API.

Co firma musi skonfigurować, gdy ścieżka będzie dostępna: dane podstawowe podmiotu prawnego z NIP (wyprowadzonym z numeru podatkowego), token KSeF wprowadzony w Ustawienia → Doręczanie — KRONENWERK natychmiast go weryfikuje, wykonując uwierzytelnione wywołanie właśnie zapisanym tokenem, i odmawia zachowania tokenu, który nie działa — a dla Państwa integracji klucz API z zakresami customers:write, customers:read, invoices:write, invoices:read i companies:read oraz endpoint webhooka. Ogólne mechanizmy API opisano na stronie API księgowego i stronie API faktur.

Podstawy KSeF API 2.0, ze źródłami

Jeśli rozważają Państwo zamiast tego integrację bezpośrednią, materiały Ministerstwa są źródłem pierwotnym i od nich należy zacząć.

• Przewodnik dla integratorów: przewodnik Ministerstwa (w aktualnej rewizji datowany na 5 maja 2026 r.) obejmuje uwierzytelnianie, uprawnienia, certyfikaty KSeF, tryby offline, kody QR, sesje interaktywne i wsadowe, pobieranie faktur, pobieranie przyrostowe, zarządzanie tokenami KSeF, klucze szyfrujące, limity i dane testowe, z przykładami w C# i Javie z jego otwartych klientów referencyjnych. github.com/CIRFMF/ksef-docs.
• OpenAPI: każde środowisko serwuje własną specyfikację pod /docs/v2; testowa znajduje się pod adresem api-test.ksef.mf.gov.pl/docs/v2. Błędy to dokumenty problem zgodne z RFC 7807 z polem detail i listą errors[].
• Uwierzytelnianie: należy pobrać challenge (ważny dziesięć minut), a następnie albo wysłać XML AuthTokenRequest podpisany XAdES certyfikatem kwalifikowanym lub certyfikatem KSeF, albo wysłać dokument JSON z tokenem KSeF; odpytać o status; odebrać token dostępu JWT i token odświeżania. Strona uwierzytelniająca musi posiadać co najmniej jedno aktywne uprawnienie dla wybranego kontekstu (NIP, identyfikator wewnętrzny lub złożony identyfikator VAT UE). uwierzytelnianie.md.
• Sesje: sesja interaktywna przyjmuje faktury pojedynczo i zwraca status dla każdej faktury; zamknięcie sesji uruchamia generowanie zbiorczego UPO. Sesja wsadowa jest udokumentowana osobno dla wysyłki masowej. Klucze publiczne do szyfrowania klucza sesji i tokenu KSeF są publikowane przez Ministerstwo i podlegają rotacji.
• Środowiska i konserwacja: TEST i DEMO nigdy nie mogą otrzymywać faktur produkcyjnych ani prawdziwych danych stron; Ministerstwo planuje prace konserwacyjne na środowiskach testowych w godzinach 16:00–18:00 i publikuje zmiany wpływające na API w swoim changelogu. srodowiska.md.

Przewodnik KSeF dla deweloperów zagłębia się w schemat i model sesji.

Jak KRONENWERK to obsługuje

JESZCZE NIEGOTOWE w zakresie przesyłania. Moduł KSeF 2.0 — uwierzytelnianie tokenem, sesja, wysyłka FA(3), pobieranie UPO i odbiór — jest zbudowany i zależny od środowiska, a nie był używany z produkcyjnym KSeF. KRONENWERK nie sprzedaje obecnie subskrypcji polskim firmom, dopóki nie zostanie to udowodnione, i nic na tej stronie nie powinno być odczytywane jako sugestia akceptacji przez administrację lub akceptacji produkcyjnej. Generowanie FA(3) jest OBSŁUGIWANE Z OGRANICZENIAMI. API nie udostępnia żadnego endpointu, zdarzenia ani pola specyficznego dla KSeF; gdy ścieżka zostanie udowodniona, integracje będą korzystać z tych samych wywołań dla klientów, wersji roboczych i webhooków co wszędzie indziej. Strona krajowa Polski znajduje się pod adresem Polska; zakres e-fakturowania produktu na stronie e-fakturowanie.