KSeF API 2.0 – dokumentacja i integracja
Co zawiera API KSeF 2.0
API KSeF 2.0 to oficjalny interfejs umożliwiający integrację oprogramowania z Krajowym Systemem e-Faktur. Działa w oparciu o REST oraz komunikację SOAP (w specyficznych przypadkach).
Nowa wersja 2.0 wprowadza usprawnione endpointy, nowy model uwierzytelniania oparty o JWT oraz ujednolicony proces inicjalizacji dla sesji wsadowej i interaktywnej.
Każdy dokument wysłany przez API musi spełniać wymogi XSD FA(2) (do 31 stycznia 2026) lub FA(3) (od 1 lutego 2026).
W wersji 2.0 wprowadzono obowiązkowe szyfrowanie wszystkich faktur algorytmem AES-256-CBC, a klucz symetryczny szyfrowany jest algorytmem RSAES-OAEP (SHA-256/MGF1).
API 2.0 oferuje ujednolicone nazewnictwo endpointów zgodne z konwencją REST, co czyni integrację bardziej przejrzystą i intuicyjną.
Dostępne są oficjalne biblioteki integracyjne w językach C# i Java, które zapewniają pełne wsparcie funkcjonalności API KSeF 2.0.
Instrukcja krok po kroku
1. Uzyskaj auth challenge
Rozpocznij proces uwierzytelniania od pobrania auth challenge za pomocą POST /api/v2/auth/challenge. Challenge jest ważny przez 10 minut.
2. Przygotuj i podpisz dokument AuthTokenRequest
Przygotuj dokument XML zgodny ze schematem AuthTokenRequest zawierający challenge, ContextIdentifier (NIP, InternalId lub NipVatUe) oraz SubjectIdentifierType. Podpisz dokument kwalifikowanym podpisem elektronicznym w formacie XAdES lub użyj tokena KSeF.
3. Wyślij podpisany dokument i sprawdź status
Wyślij podpisany dokument do POST /api/v2/auth/xades-signature (dla podpisu XAdES) lub POST /api/v2/auth/ksef-token (dla tokena KSeF). Otrzymasz authenticationToken i referenceNumber. Sprawdź status operacji uwierzytelniania za pomocą GET /api/v2/auth/{referenceNumber}.
4. Uzyskaj token dostępowy (accessToken)
Po pomyślnym uwierzytelnieniu wywołaj POST /api/v2/auth/token/redeem, aby uzyskać parę tokenów: accessToken (JWT do autoryzacji operacji) i refreshToken (do odświeżania accessToken bez ponownego uwierzytelniania).
5. Otwórz sesję interaktywną lub wsadową
Wygeneruj klucz symetryczny AES-256 i zaszyfruj go kluczem publicznym KSeF. Otwórz sesję za pomocą POST /api/v2/sessions/online (interaktywna) lub POST /api/v2/sessions/batch (wsadowa), podając formCode (schemat FA(2) lub FA(3)) oraz zaszyfrowany klucz.
6. Przygotuj i zaszyfruj fakturę
Przygotuj fakturę w formacie XML zgodną z XSD. Zaszyfruj ją algorytmem AES-256-CBC z dopełnieniem PKCS#7. Oblicz skróty SHA faktury przed i po szyfrowaniu wraz z rozmiarami plików.
7. Wyślij fakturę do KSeF
Wyślij zaszyfrowaną fakturę do POST /api/v2/sessions/online/{referenceNumber}/invoices/ wraz z metadanymi (skróty i rozmiary). Po przesłaniu otrzymasz referenceNumber dokumentu.
8. Zamknij sesję i pobierz UPO
Po wysłaniu wszystkich faktur zamknij sesję za pomocą POST /api/v2/sessions/online/{referenceNumber}/close. Sprawdź status sesji i pobierz zbiorcze UPO (Urzędowe Poświadczenie Odbioru).
Najczęstsze problemy i rozwiązania
Błąd 403 podczas użycia API
Nieprawidłowe tokeny lub brak uprawnień. Sprawdź, czy accessToken jest ważny (nie wygasł) i czy posiadasz odpowiednie uprawnienia do wykonania operacji. Możesz odświeżyć token za pomocą refreshToken wywołując POST /api/v2/auth/token/refresh.
API zwraca błąd walidacji
Dokument niezgodny z XSD. Sprawdź, czy używasz właściwej wersji schematu (FA(2) do 31 stycznia 2026, FA(3) od 1 lutego 2026), czy wszystkie pola obowiązkowe są wypełnione i czy struktura XML jest poprawna. Upewnij się, że plik jest kodowany w UTF-8 bez znaku BOM.
Błąd 440 - Duplikat faktury
KSeF wykrywa duplikaty na podstawie kombinacji: NIP sprzedawcy (Podmiot1:NIP), RodzajFaktury i numer faktury (P_2). Unikalność faktury utrzymywana jest przez 10 pełnych lat. Upewnij się, że nie wysyłasz tej samej faktury ponownie.
Błąd podczas uwierzytelniania - status ‘Uwierzytelnianie w toku’
Na środowiskach przedprodukcyjnym i produkcyjnym system sprawdza aktualny status certyfikatu u jego wystawcy (OCSP/CRL). To normalne, że weryfikacja trwa - odpytywaj status do skutku. Aby uniknąć oczekiwania, zaleca się użycie certyfikatu KSeF, którego weryfikacja odbywa się wewnątrz systemu.
Błąd szyfrowania - faktura nie może być odszyfrowana
Upewnij się, że używasz algorytmu AES-256-CBC z dopełnieniem PKCS#7. Klucz symetryczny musi być zaszyfrowany algorytmem RSAES-OAEP (SHA-256/MGF1) przy użyciu aktualnego klucza publicznego KSeF, który można pobrać z GET /api/v2/security/public-key-certificates.
Przekroczony limit rozmiaru faktury
Maksymalny rozmiar faktury bez załączników to 1 MB (1 000 000 bajtów), z załącznikami - 3 MB (3 000 000 bajtów). W jednej sesji można przesłać maksymalnie 10 000 faktur.
Błąd podczas otwierania sesji - nieprawidłowy formCode
Sprawdź, czy podajesz poprawny kod formularza zgodny z aktualną wersją schematu. Dla FA(2) użyj odpowiedniego systemCode, schemaVersion i value. Od 1 lutego 2026 obowiązuje wyłącznie FA(3).
Limit wywołań API został przekroczony
API 2.0 stosuje precyzyjne limity na sekundę, minutę i godzinę – inne dla środowisk testowych, demo i produkcji. Odczytuj nagłówki limitów, wdrażaj retry z backoffem i rozkładaj wysyłkę wsadową, aby nie blokować integracji.
Kluczowe zmiany w API 2.0
API 2.0 wprowadza odseparowane uwierzytelnianie z tokenami JWT (access/refresh), możliwość wielokrotnego użycia tokena przy otwieraniu sesji online i batch, obowiązkowe szyfrowanie AES-256-CBC każdej faktury oraz nowy algorytm wykrywania duplikatów (NIP sprzedawcy + rodzaj + numer P_2). Usprawniono też tryb wsadowy – błędy nie blokują całej paczki, a dedykowany endpoint zwraca listę odrzuconych faktur.
Oficjalne narzędzia wspierające integrację
MF publikuje interaktywną dokumentację OpenAPI (https://ksef-test.mf.gov.pl/docs/v2/index.html), surowy plik JSON oraz oficjalne biblioteki ksef-client-csharp i ksef-client-java rozwijane open source i dystrybuowane w NuGet/Maven. Do tego dochodzą przewodniki krok po kroku oraz aplikacje demo, które powielają wszystkie kluczowe scenariusze uwierzytelnienia, sesji i nadawania uprawnień.
Weryfikacja faktur w API 2.0
Każdy dokument przechodzi walidację XSD (FA(2) do 31.01.2026, FA(3) od 01.02.2026), kontrolę duplikatów (NIP + RodzajFaktury + P_2), limity rozmiarów (1 MB bez załączników, 3 MB z załącznikami), weryfikację szyfrowania (AES-256-CBC + RSA-OAEP) oraz spójność metadanych sesji. System zwraca szczegółowe statusy także dla pojedynczych pozycji wsadu.
Moduł certyfikatów i API testowych danych
Nowy moduł certyfikatów pozwala składać wnioski, pobierać statusy i listy certyfikatów KSeF – bez nich nie wystawisz dokumentów offline ani nie zalogujesz się certyfikatem wewnętrznym. W środowisku testowym dostępne jest też API /v2/testdata/*, które umożliwia generowanie podmiotów (np. JDG, komornik, grupa VAT), nadawanie im uprawnień i włączanie obsługi załączników, co znacznie przyspiesza przygotowanie scenariuszy integracyjnych.
FAQ
Czy API 2.0 wymaga podpisu?
Uwierzytelnianie w API 2.0 może odbywać się na dwa sposoby: z wykorzystaniem kwalifikowanego podpisu elektronicznego w formacie XAdES (podpisanie dokumentu AuthTokenRequest) lub za pomocą tokena KSeF (zaszyfrowanego ciągu token|timestamp). Faktury same w sobie nie wymagają podpisu - są autoryzowane przez system po pomyślnej weryfikacji.
Jakie są główne zmiany w API 2.0 względem wersji 1.0?
Kluczowe zmiany to: wydzielenie uwierzytelniania jako osobnego procesu niezależnego od sesji, wprowadzenie standardowych tokenów JWT, obowiązkowe szyfrowanie wszystkich faktur, ujednolicony proces inicjalizacji dla sesji wsadowej i interaktywnej, ulepszone przetwarzanie sesji wsadowych (błędy dotyczą tylko konkretnych faktur, nie całej paczki), oraz nowy moduł zarządzania certyfikatami KSeF.
Jak długo ważny jest accessToken?
accessToken ma ograniczony czas ważności (kilkanaście minut, określony w polu exp tokena JWT). refreshToken ma znacznie dłuższy okres ważności (do 7 dni) i może być używany wielokrotnie do odświeżania accessToken bez ponownego uwierzytelniania.
Czy mogę używać API 2.0 w środowisku testowym?
Tak, środowisko testowe KSeF API 2.0 jest dostępne pod adresem https://ksef-test.mf.gov.pl/docs/v2/. W środowisku testowym dopuszcza się użycie samodzielnie wygenerowanych certyfikatów będących odpowiednikiem certyfikatów kwalifikowanych, co umożliwia wygodne testowanie.
Jakie są limity wywołań API?
W wersji 2.0 wprowadzono precyzyjny mechanizm rate limiting. Każdy endpoint objęty jest limitem liczby żądań w zadanych przedziałach czasowych: na sekundę, minutę, godzinę. Limity są publicznie udostępniane, zróżnicowane w zależności od środowiska i dostosowane do charakteru operacji.
Czy API 2.0 obsługuje wysyłkę wsadową?
Tak, API 2.0 oferuje ulepszoną wysyłkę wsadową. W przeciwieństwie do wersji 1.0, gdzie błąd jednej faktury odrzucał całą paczkę, w wersji 2.0 każda faktura przetwarzana jest niezależnie. Ewentualne błędy wpływają wyłącznie na konkretne faktury, a dostępny jest dedykowany endpoint do pobrania szczegółowego statusu błędnie przetworzonych faktur.
Czy mogę generować dane testowe bez formalności?
Tak. Środowisko testowe posiada pomocnicze endpointy /v2/testdata/*, które umożliwiają tworzenie podmiotów (np. JDG, komornik, grupa VAT), nadawanie im uprawnień i włączanie obsługi załączników. To pozwala ćwiczyć scenariusze integracyjne bez składania ZAW-FA.
Gdzie znajdę dokumentację OpenAPI dla API 2.0?
Dokumentacja interaktywna dostępna jest pod adresem https://ksef-test.mf.gov.pl/docs/v2/index.html (środowisko testowe). Specyfikacja OpenAPI w formacie JSON dostępna jest pod adresem https://ksef-test.mf.gov.pl/docs/v2/openapi.json.
Czy są dostępne oficjalne biblioteki do integracji?
Tak, Ministerstwo Finansów udostępnia oficjalne biblioteki open source: ksef-client-csharp (C#) dostępna na GitHub oraz ksef-client-java (Java). Biblioteki będą również dostępne w oficjalnych repozytoriach pakietów (NuGet dla .NET, Maven Central dla Java).