Co się zmienia w API KSeF 2.0 i dlaczego FA(3) zastępuje FA(2)

AITekst opracowany z wykorzystaniem sztucznej inteligencji. Zasady i ograniczenia

Aktualizacja schematu to więcej niż podmiana numeru wersji API KSeF 2.0, gdyż struktura FA(3) wprowadza szereg nowych pól obowiązkowych i opcjonalnych, które nie występowały w poprzedniej iteracji. Ministerstwo Finansów opublikowało dokumentację techniczną KSeF 2.0, w której kluczową modyfikacją jest rozszerzenie sekcji płatności oraz danych identyfikacyjnych kontrahentów. Przykładowo, w strukturze FA(3) pole rachunekBankowySprzedawcy staje się elementem krytycznym dla poprawnej walidacji dokumentu w środowisku produkcyjnym, podczas gdy w FA(2) dopuszczano większą dowolność w formatowaniu danych bankowych.

Struktura logiczna FA(3) powstała w wyniku szerokich konsultacji z ekspertami i dostawcami oprogramowania, co zaowocowało doprecyzowaniem węzłów dotyczących rozliczeń VAT oraz procedur celnych. Integracja KSeF w nowym standardzie wymaga od działów IT przeprowadzenia mapowania pól systemów ERP na nową strukturę XML. Dotychczasowe adresy API pozostaną aktywne tylko w krótkim okresie przejściowym, a brak migracji do wersji 2.0 uniemożliwi uzyskanie numeru KSeF ID, co de facto oznacza wystawienie faktury nielegalnej w świetle przepisów obowiązujących od 2026 roku.

Wdrożenie systemu zostało podzielone na etapy, aby umożliwić stabilną adaptację różnym grupom podatników. Harmonogram uwzględnia wielkość przedsiębiorstwa oraz roczny obrót, nakładając najsurowsze terminy na podmioty o największej skali działalności. Poniższa tabela przedstawia kluczowe daty graniczne oraz skutki niedopełnienia obowiązku integracji z systemem centralnym.

W związku z powyższym, dostawcy systemów powinni wykonać różnicowe dumpy XML/JSON już teraz, aby precyzyjnie porównać brakujące pola między wersjami FA(2) i FA(3). Pozwoli to na uniknięcie błędów walidacji schematu XSD w momencie uruchomienia środowiska produkcyjnego. Należy pamiętać, że od 1 lutego 2026 r. wszyscy podatnicy będą musieli odbierać faktury przy użyciu KSeF, niezależnie od terminu wdrożenia obowiązku ich wystawiania.

Autentykacja i bezpieczeństwo: MCU, tokeny, certyfikat KSeF - wybierz przed zimą

Wybór metody uwierzytelniania w KSeF to nie tylko kwestia techniczna, ale decyzja wpływająca na bezpieczeństwo danych, ciągłość fakturowania i możliwość automatyzacji pracy. Profil Zaufany (ePUAP) jest metodą najprostszą, lecz ograniczoną głównie do środowisk testowych i sandboxowych, ponieważ wymaga każdorazowej interakcji człowieka, co wyklucza automatyzację procesów maszynowych. Autoryzacja środowiska KSeF 2.0 to jednorazowe potwierdzenie uprawnień, które w przypadku JDG może być wykonane przez właściciela, jednak w strukturach korporacyjnych wymaga bardziej zaawansowanych narzędzi.

Kwalifikowany podpis elektroniczny lub pieczęć elektroniczna z numerem NIP stanowią fundament bezpiecznej komunikacji PKI (Public Key Infrastructure). Zapewniają one najwyższy poziom autentyczności, jednak wiążą się z kosztami subskrypcji oraz koniecznością odnawiania certyfikatów co 2 lub 3 lata, co wymaga procedury rotacji kluczy. Token KSeF, będący obecnie popularną metodą uwierzytelniania, pozostanie funkcjonalny wyłącznie do 31 grudnia 2026 r. Po tej dacie jedynym dopuszczalnym standardem dla nowych uprawnień i masowej komunikacji będzie certyfikat MCU (Moduł Certyfikatów Użytkownika).

Certyfikat MCU, który staje się obowiązkowy od 1 listopada 2025 r. dla procesów nadawania nowych uprawnień, wprowadza ścisły rozdział ról w systemie. MCU wymusza rolę „integrator” oddzieloną od roli „księgowy”, co zwiększa bezpieczeństwo danych finansowych poprzez ograniczenie dostępu do wrażliwych sekcji systemu tylko dla uprawnionych procesów API. Należy odnotować, że obowiązuje limit 100 certyfikatów na jeden podmiot w systemie EZD RP, co wymusza na dużych organizacjach optymalizację zarządzania kluczami.

Proces wdrożenia technicznego po stronie działu IT powinien przebiegać według ściśle określonego schematu, zapewniającego ciągłość operacyjną:

1. Zarejestruj podmiot w systemie MCU w celu uzyskania uprawnień administracyjnych.
2. Wygeneruj Request Podpisania Certyfikatu (CSR) dedykowany dla środowiska produkcyjnego.
3. Skonfiguruj reguły zapory sieciowej (firewall) w celu ograniczenia dostępu do API po konkretnych adresach IP.
4. Przeprowadź test procedury unieważniania certyfikatu (revoke) w środowisku demo.
5. Zapisz i zarchiwizuj procedurę rotacji certyfikatów oraz kluczy prywatnych.

Zaleca się przechowywanie suchego backupu kluczy poza modułem HSM (Hardware Security Module), co pozwoli na uniknięcie blokady procesów biznesowych w przypadku awarii sprzętowej urządzenia kryptograficznego.

Środowiska testowe: gdzie i jak uruchomić ciągłą integrację bez ryzyka

Efektywna integracja ze środowiskiem API KSeF 2.0 wymaga zrozumienia ról trzech dostępnych instancji systemu. Środowisko testowe (TE) oraz środowisko demo (TR) służą do weryfikacji poprawności struktury FA(3) i testowania logiki biznesowej bez wywoływania skutków prawno-podatkowych. Wersja produkcyjna KSeF 2.0 (PRD) będzie dostępna od 1 lutego 2026 r. i tam każda wysłana faktura staje się dokumentem oficjalnym. Wykorzystanie semantycznej trójki kod-test-produkcja pozwala na budowę stabilnego pipeline'u CI/CD.

Automatyzacja procesów testowych jest kluczowa dla zachowania spójności systemu przy częstych aktualizacjach oprogramowania ERP. Poniższy fragment konfiguracji GitHub Actions dla technologii .NET ilustruje podstawowy krok weryfikacji połączenia z API KSeF w ramach cyklu CI:

name: Test KSeF API Connection
run: |
Secret z certyfikatem należy zapisać jako base64 w ustawieniach repozytorium
dotnet test ./KSeF.Tests.dll
curl -X GET ""
-H "Authorization: Bearer ${{ secrets.KSEF_AUTH_TOKEN_B64 }}"

Wysyłanie faktur do KSeF odbywa się w sesjach - interaktywnej (do 5 dokumentów) lub wsadowej (paczki do 1000 faktur). Sesja wsadowa charakteryzuje się wysoką wydajnością, umożliwiając przesył 500 dokumentów w czasie około 5 sekund. Zaleca się ustawienie nightly build wyłącznie dla gałęzi deweloperskich „ksef-2.0”, co pozwala na optymalizację kosztów zasobów obliczeniowych i limitów czasowych autoryzacji, która trwa maksymalnie 9 minut.