Wraz z opublikowaniem KSeF API 2.0 Ministerstwo Finansów otwiera nowy rozdział w integracji systemów fakturowania z Krajowym Systemem e-Faktur. Nowa wersja interfejsu wprowadza istotne zmiany – od nowoczesnego uwierzytelniania przez tokeny JWT, przez obowiązkowe szyfrowanie faktur, aż po uproszczone i spójne REST-owe endpointy. Dla firm i dostawców oprogramowania to szansa na bezpieczniejszą, bardziej przewidywalną i zgodną z rynkowymi standardami integrację, której wdrożenie warto rozpocząć już dziś.

Ministerstwo Finansów udostępniło szczegółową dokumentację techniczną nowej wersji interfejsu API KSeF 2.0. To kluczowy krok w kierunku pełnej implementacji obowiązkowego Krajowego Systemu e-Faktur od lutego 2026 roku. Wersja 2.0 wnosi szereg zmian, które mają na celu uproszczenie integracji, poprawę bezpieczeństwa i zwiększenie elastyczności działania po stronie dostawców oprogramowania.
Nowa wersja API jest wynikiem analizy doświadczeń z wdrożenia API 1.0. Przynosi:
API 2.0 oddziela proces uwierzytelniania od sesji. Użycie tokenów JWT zapewnia:
Bez względu na tryb pracy (interaktywny czy wsadowy), proces otwierania sesji przebiega w ten sam sposób. Klient przekazuje:
Od teraz każda faktura – bez względu na tryb wysyłki – musi być szyfrowana lokalnie przez klienta. To oznacza:
API 2.0 zyskało spójność, m.in. poprzez:
KSeF 2.0 umożliwia:
W przeciwieństwie do API 1.0, wersja 2.0 pozwala:
Zamiast automatycznego dziedziczenia, API 2.0 wprowadza model nadawania uprawnień z możliwością delegowania. Pozwala to:
API KSeF 2.0 wprowadza zróżnicowane limity per:
Środowisko testowe zyskało narzędzie umożliwiające szybkie tworzenie:
Dostępne są:
KSeF API 2.0 to nie tylko aktualizacja, ale istotne usprawnienie całego procesu integracji. Dla zespołów programistycznych oznacza większą przewidywalność, bezpieczeństwo oraz zgodność z nowoczesnymi praktykami rynkowymi. Migracja na nową wersję API powinna być zaplanowana z odpowiednim wyprzedzeniem – oficjalne wsparcie i dostępność narzędzi już dziś pozwalają rozpocząć przygotowania do obowiązkowego KSeF od lutego 2026 roku.
Dlaczego warto przejść na API KSeF 2.0?
Nowa wersja API jest wynikiem analizy doświadczeń z wdrożenia API 1.0. Przynosi:
- nowy model uwierzytelniania oparty na tokenach JWT,
- obowiązkowe szyfrowanie wszystkich faktur,
- ujednolicone endpointy REST,
- elastyczny model uprawnień i nowe możliwości logowania (m.in. dla samofakturowania),
- dedykowane mechanizmy rate limiting,
- oraz oficjalną bibliotekę kliencką w C# i Javie.
Nowy model uwierzytelniania z wykorzystaniem JWT
API 2.0 oddziela proces uwierzytelniania od sesji. Użycie tokenów JWT zapewnia:
- większą elastyczność integracji,
- możliwość wielokrotnego wykorzystania tokena,
- zgodność z powszechnymi standardami bezpieczeństwa.
Ujednolicony proces otwierania sesji
Bez względu na tryb pracy (interaktywny czy wsadowy), proces otwierania sesji przebiega w ten sam sposób. Klient przekazuje:
- formCode – kod formularza,
- encryptionKey – zaszyfrowany klucz AES.
Obowiązkowe szyfrowanie faktur
Od teraz każda faktura – bez względu na tryb wysyłki – musi być szyfrowana lokalnie przez klienta. To oznacza:
- zwiększone bezpieczeństwo danych,
- wymóg stosowania szyfrowania AES (z kluczem generowanym na sesję),
- wsparcie szyfrowania asymetrycznego (RSA 4096 z OAEP i SHA-256).
Nowa struktura i nazewnictwo REST API
API 2.0 zyskało spójność, m.in. poprzez:
- REST-owe, intuicyjne endpointy (auth/token, sessions/online, permissions/entities/grants),
- uproszczone modele danych (np. jawne typy identyfikatorów jako enum),
- jednolite konwencje nazw operacji i parametrów.
Nowy moduł certyfikatów wewnętrznych KSeF
KSeF 2.0 umożliwia:
- występowanie o certyfikaty wewnętrzne KSeF,
- pobieranie certyfikatów i sprawdzanie ich statusu,
- określanie limitów i pobieranie metadanych.
Ulepszony tryb wysyłki wsadowej
W przeciwieństwie do API 1.0, wersja 2.0 pozwala:
- niezależnie przetwarzać każdą fakturę w paczce,
- identyfikować błędne dokumenty bez odrzucania całej paczki,
- pobierać szczegółowy status każdej nieprzetworzonej pozycji.
Zmiany w module uprawnień
Zamiast automatycznego dziedziczenia, API 2.0 wprowadza model nadawania uprawnień z możliwością delegowania. Pozwala to:
- oddzielić uprawnienia do faktur własnych i klientów,
- zdefiniować role dla pracowników i obsługę wielu klientów,
- obsłużyć fakturowanie w kontekście podmiotu unijnego (VAT UE).
Precyzyjne limity wywołań (rate limiting)
API KSeF 2.0 wprowadza zróżnicowane limity per:
- token JWT (dla operacji chronionych),
- adres IP (dla operacji otwartych).
Pomocnicze API do generowania danych testowych
Środowisko testowe zyskało narzędzie umożliwiające szybkie tworzenie:
- testowych podmiotów gospodarczych,
- jednostek JST i grup VAT,
- struktur uprawnień i kontekstów integracyjnych.
Oficjalne narzędzia wspierające integrację
Dostępne są:
- Interaktywna dokumentacja OpenAPI – z opisem metod, parametrów i modeli danych,
- Plik specyfikacji JSON OpenAPI – do automatycznego generowania kodu,
- Biblioteka KSeF 2.0 Client (C#, Java) – open source, dostępna w repozytoriach NuGet i Maven,
- Przewodnik integracyjny – z przykładami kodu i instrukcjami krok po kroku.
Podsumowanie
KSeF API 2.0 to nie tylko aktualizacja, ale istotne usprawnienie całego procesu integracji. Dla zespołów programistycznych oznacza większą przewidywalność, bezpieczeństwo oraz zgodność z nowoczesnymi praktykami rynkowymi. Migracja na nową wersję API powinna być zaplanowana z odpowiednim wyprzedzeniem – oficjalne wsparcie i dostępność narzędzi już dziś pozwalają rozpocząć przygotowania do obowiązkowego KSeF od lutego 2026 roku.