Integracja z KSeF 2.0: Techniczny przewodnik po API, strukturze FA(3) i uwierzytelnianiu

Wdrożenie KSeF to ogromne wyzwanie dla działów IT, deweloperów i software house'ów. Sukces integracji zależy od dogłębnego zrozumienia architektury systemu, metod uwierzytelniania i nowej struktury logicznej FA(3). Ten artykuł to techniczne kompendium wiedzy, które pomoże Ci sprawnie przeprowadzić integrację. Jeśli szukasz informacji biznesowych i prawnych, znajdziesz je w naszym kompleksowym przewodniku po KSeF.

Architektura KSeF 2.0 – co zmienia się w stosunku do KSeF 1.0?

KSeF 2.0 to ewolucja, a nie całkowita rewolucja w stosunku do pierwszej wersji systemu. Jednak wprowadzone zmiany są kluczowe dla stabilności i funkcjonalności. Najważniejsze różnice z perspektywy technicznej to nowe API, obsługa certyfikatów i trybów offline oraz nowa struktura e-faktury.

Środowiska KSeF: Testowe, Przedprodukcyjne i Produkcyjne

Ministerstwo Finansów udostępnia trzy oddzielne środowiska, aby umożliwić deweloperom i firmom bezpieczne testowanie i wdrażanie integracji.

• Środowisko Testowe (Test): Uruchomione 30 września 2025 r. Służy do pierwszych testów integracji, walidacji schemy i sprawdzania logiki działania API. Dane na tym środowisku są regularnie czyszczone.
• Środowisko Przedprodukcyjne (Demo): Uruchomione 15 października 2025 r. Jest to stabilniejsza wersja, będąca wiernym odzwierciedleniem środowiska produkcyjnego. Idealne do końcowych testów wydajnościowych i akceptacyjnych.
• Środowisko Produkcyjne (Prod): Uruchomione 1 lutego 2026 r. To właściwy, oficjalny system KSeF, w którym przetwarzane są prawnie wiążące e-faktury.

Dostęp do środowisk testowych i przedprodukcyjnych jest otwarty, a aktualne adresy URL i specyfikację OpenAPI można znaleźć na oficjalnej stronie informacyjnej Ministerstwa Finansów.

Uwierzytelnianie i Autoryzacja w API KSeF 2.0 – przegląd metod

Bezpieczeństwo i prawidłowa identyfikacja użytkownika to fundamenty KSeF. System przewiduje kilka metod uwierzytelniania, które można dostosować do potrzeb organizacji.

• Token autoryzacyjny: To podstawowa i najwygodniejsza metoda dla aplikacji. Generuje się go jednorazowo poprzez uwierzytelnienie za pomocą np. podpisu kwalifikowanego lub Profilu Zaufanego. Token jest długoterminowy i służy do podpisywania kolejnych żądań do API, bez konieczności każdorazowego używania certyfikatu. Ważne: tokeny z KSeF 1.0 nie będą działać w KSeF 2.0.
• Podpis kwalifikowany i pieczęć kwalifikowana: Mogą być używane bezpośrednio do autoryzacji sesji interaktywnej (np. w Aplikacji Podatnika) lub do generowania tokenów. Pieczęć kwalifikowana jest szczególnie ważna dla osób prawnych (spółek), ponieważ pozwala na uwierzytelnienie całej organizacji, a nie konkretnej osoby fizycznej.
• Certyfikat KSeF (typu 1 i 2): To nowość w KSeF 2.0.
  • Certyfikat typu 1 pełni funkcję uwierzytelniającą, podobnie jak podpis kwalifikowany. Może służyć do logowania i autoryzacji w systemie.
  • Certyfikat typu 2 jest kluczowy dla trybów offline. Służy do cyfrowego podpisywania kodów QR na fakturach wystawianych poza systemem, co pozwala nabywcy zweryfikować autentyczność wystawcy jeszcze przed przesłaniem faktury do KSeF.

Struktura logiczna e-Faktury FA(3) – najważniejsze zmiany i pola

Sercem każdej e-faktury jest plik XML zgodny ze strukturą logiczną opublikowaną przez Ministerstwo Finansów. W KSeF 2.0 obowiązywać będzie nowa wersja schemy – FA(3), która zastąpi dotychczasową FA(2).

Kluczowe zmiany w FA(3) w porównaniu do FA(2)

• Obsługa załączników: Struktura FA(3) wprowadza możliwość dołączania do faktury załączników binarnych. To odpowiedź na potrzeby biznesowe firm, które przesyłają wraz z fakturą np. protokoły odbioru czy specyfikacje. Załącznik jest dodawany w dedykowanym module e-Urzędu Skarbowego i powiązany z numerem KSeF faktury.
• Nowe pola i role: Pojawiają się nowe, opcjonalne pola, np. do precyzyjniejszego określenia terminu płatności. Wprowadzono także nową rolę "pracownik" (w węźle Podmiot3), co ułatwi rozliczanie wydatków pracowniczych.
• Większa elastyczność: Zwiększono liczbę znaków w niektórych polach, np. w nazwie towaru/usługi (pole P_7), co było częstym postulatem przedsiębiorców.
• Wsparcie dla JST i GV: Dodano rozwiązania dedykowane dla jednostek samorządu terytorialnego i grup VAT.

Każda faktura wysyłana do KSeF musi być w 100% zgodna ze schemą XSD. Brak wymaganego pola lub nieprawidłowy format danych spowoduje odrzucenie dokumentu przez bramkę API. Dlatego kluczowe jest dokładne testowanie generowanych plików XML.

Tryby pracy z KSeF: Online, Offline24 i awaryjny – jak je zaimplementować?

System KSeF został zaprojektowany z myślą o zapewnieniu ciągłości fakturowania, nawet w przypadku problemów technicznych. Dlatego Twoja aplikacja powinna być gotowa do obsługi trzech trybów pracy.

• Tryb online: To standardowy tryb pracy. Aplikacja wysyła fakturę XML do KSeF, system ją waliduje, nadaje numer KSeF i datę wystawienia, a następnie zwraca Urzędowe Poświadczenie Odbioru (UPO).
• Tryb offline24: Pozwala na wystawienie faktury w systemie finansowo-księgowym bez bieżącego połączenia z KSeF. Faktura otrzymuje datę wystawienia zgodną z datą w pliku XML. Na jej wizualizacji muszą znaleźć się dwa kody QR. Taki dokument należy przesłać do KSeF najpóźniej następnego dnia roboczego. To rozwiązanie na wypadek chwilowych problemów z internetem.
• Tryb awaryjny: Jest uruchamiany tylko w przypadku oficjalnego ogłoszenia awarii KSeF przez Ministerstwo Finansów. W tym czasie faktury wystawia się poza systemem, oznaczając je specjalnymi kodami QR. Po zakończeniu awarii przedsiębiorca ma 7 dni roboczych na przesłanie tych faktur do KSeF.

Podsumowanie i zasoby dla deweloperów

Integracja z KSeF 2.0 jest złożonym procesem, ale dzięki dobremu przygotowaniu technicznemu i wykorzystaniu udostępnionych środowisk testowych można go przeprowadzić sprawnie. Kluczowe jest zrozumienie mechanizmów autoryzacji, nowej struktury FA(3) oraz logiki trybów offline. Pełny obraz wdrożenia, w tym aspekty prawne i organizacyjne, opisaliśmy w naszym ogólnym artykule o Krajowym Systemie e-Faktur.