Integracja programu z KSeF — API i wymiana danych

API KSeF 2.0 określa zasady wymiany danych między KSeF a zewnętrznymi systemami finansowo-księgowymi¹. W poradniku omawiamy obieg faktur, uwierzytelnianie, testowanie połączenia i korzystanie z dokumentacji API.
Od 1 lutego 2026 r. obowiązek wystawiania faktur w KSeF objął podatników, których sprzedaż wraz z VAT przekroczyła w 2024 r. 200 mln zł².

Czym jest integracja programu z API KSeF i jak działa obieg faktur?

Integracja programu z API KSeF 2.0 łączy obieg faktur w programie z operacjami wykonywanymi w KSeF. Każdą fakturę trzeba zaszyfrować, niezależnie od sposobu jej przesłania¹.
Dotyczy to wysyłki pojedynczej i wsadowej. Dane faktur szyfruje się kluczem symetrycznym o długości 256 bitów³.

Wysyłka wsadowa nie daje jednego wyniku dla całej paczki. API KSeF 2.0 przetwarza każdą fakturę osobno i zgłasza błąd przy dokumencie, w którym go wykryło¹. Trzeba więc śledzić los poszczególnych faktur, nie tylko status paczki.
Łączny rozmiar paczki ZIP w sesji wsadowej nie może przekroczyć 5 GB, a każda przesyłana część może mieć najwyżej 100 MB⁴.

Jak wysyłać faktury do KSeF i pobierać dokumenty przez API?

Wysyłanie faktur do KSeF przez API wymaga obsługi sesji. Przy pobieraniu program musi z kolei wskazać dokument, który ma odczytać. SDK intermedia/ksef-api-v2 pozwala otwierać i zamykać sesję interaktywną oraz zamykać sesję wsadową⁵.
Otwarta sesja interaktywna pozostaje ważna przez 12 godzin od utworzenia³.

SDK intermedia/ksef-api-v2 umożliwia pobranie faktury po numerze KSeF i sprawdzenie statusu eksportu paczki faktur⁵. To odrębne czynności: program może odczytać konkretny dokument albo skontrolować eksport paczki.
Numer KSeF podawany przy pobieraniu faktury ma 35 lub 36 znaków⁶.

Jak sprawdzić status faktury i potwierdzenie jej przyjęcia w KSeF?

Status faktury w KSeF sprawdza się dla dokumentu w sesji. Potwierdzeniem przyjęcia jest UPO, czyli urzędowe poświadczenie odbioru. SDK intermedia/ksef-api-v2 pozwala sprawdzić status faktury, pobrać listę niepoprawnie przetworzonych dokumentów i uzyskać UPO po numerze KSeF lub numerze referencyjnym faktury⁵.
Wynik wysyłki i UPO przypisz do właściwej faktury. Kod statusu faktury 200 oznacza skuteczne przetworzenie dokumentu; po udostępnieniu UPO można pobrać potwierdzenie⁶.

Kiedy wybrać bezpośrednie połączenie z API, a kiedy gotową integrację w programie?

Sposób połączenia zależy od tego, kto wdraża i obsługuje obieg faktur oraz jakich operacji potrzebuje firma⁷. Tabela pokazuje podział odpowiedzialności między rozwiązaniami.

SDK intermedia/ksef-api-v2 pozwala złożyć wniosek certyfikacyjny, sprawdzić jego status i pobrać certyfikaty⁵. Umożliwia też sprawdzenie statusu zgody na wystawianie faktur z załącznikiem⁵. Weź te operacje pod uwagę, jeśli są częścią obiegu faktur w firmie.
Certyfikat KSeF jest ważny nie dłużej niż dwa lata od daty wytworzenia lub wskazanej daty początkowej⁸.

Uwierzytelnianie, testy i błędy połączenia z KSeF

Dokumentacja wskazuje różnicę między wersjami: API KSeF 2.0 oddziela uwierzytelnianie od sesji, a API 1.0 wymagało rozpoczęcia sesji¹. Tabela zestawia oba sposoby działania.

Użytkownik najpierw się uwierzytelnia, a potem otrzymuje token dostępu, którym autoryzuje operacje na chronionych zasobach¹.
Token zachowuje ważność do daty zapisanej w polu exp; dokumentacja podaje jako przykład kilkanaście minut⁹.

Uwierzytelnianie w API KSeF korzysta z tokenów JWT i podpisów elektronicznych XAdES¹. W trakcie procesu wskazuje się podmiot, w którego imieniu będą wykonywane operacje, oraz podmiot dokonujący uwierzytelnienia¹. Ten drugi można wskazać podpisem XAdES albo tokenem KSeF¹.
Wyzwanie uwierzytelniające używane przy podpisie XAdES jest ważne przez 10 minut⁹.

Uprawnienia w KSeF decydują o możliwości wystawiania faktur, przeglądania dokumentów i nadawania dalszych uprawnień¹. Samo poprawne uwierzytelnienie nie wystarczy do oceny połączenia. Trzeba też skontrolować zakres dostępu¹⁰.

Jak przetestować integrację przed uruchomieniem jej w środowisku produkcyjnym?

Integrację z KSeF przetestuj na danych odpowiadających podmiotom i strukturze organizacyjnej, które program będzie obsługiwał. Pomocnicze API do generowania danych testowych pozwala symulować założenie podmiotu gospodarczego i tworzenie struktur organizacyjnych powiązanych przedsiębiorstw¹. Po przygotowaniu danych przeprowadź próbę uwierzytelnienia i sprawdź, czy program przypisuje operacje właściwemu podmiotowi.
Utworzenie testowego podmiotu przez API wymaga NIP-u składającego się z 10 cyfr¹¹.

Jak rozpoznać i rozwiązać typowe błędy API KSeF?

Błędy API KSeF analizuj w powiązaniu z operacją, która się nie udała, i wymaganym do niej uprawnieniem. Tego samego uprawnienia nie można nadać dwukrotnie; nowo nadane zapewnia dostęp dopiero po przetworzeniu operacji przez system¹. Cofnięcie uprawnienia nie unieważnia wcześniejszych operacji, a dostęp pozostaje aktywny do jego odebrania¹.
Próba wykonania operacji bez wymaganego uprawnienia może zakończyć się odpowiedzią HTTP 403 Forbidden⁶.

Uprawnienie InvoiceRead pozwala odczytywać faktury, a odrębne InvoiceWrite służy do ich wystawiania¹². Tabela pokazuje, co kontrolować przy operacjach dotyczących uprawnień.

SDK intermedia/ksef-api-v2 udostępnia nadawanie, odbieranie i przeglądanie uprawnień do pracy w KSeF oraz obsługi faktur⁵. Taka kontrola pozwala ustalić, czy problem dotyczy dostępu, czy samego połączenia.

Co zrobić, gdy API KSeF jest niedostępne lub wysyłka faktury się nie powiedzie?

Nieudaną wysyłkę do API KSeF oznacz w programie jako nierozstrzygniętą. Nie łącz jej z dokumentami, których wynik został potwierdzony. Zachowaj identyfikator operacji i sprawdź jej wynik przed ponowną próbą; błąd połączenia nie potwierdza odrzucenia faktury. SDK intermedia/ksef-api-v2 pozwala pobierać limity dla bieżącego kontekstu, podmiotu i API^5,13.
Odpowiedź HTTP 202 Accepted potwierdza przyjęcie żądania wysyłki, ale nie końcowy wynik przetwarzania faktury⁶.

Jak sprawdzić połączenie programu z API KSeF i jego uwierzytelnienie?

Połączenie programu z API KSeF sprawdź, inicjując uwierzytelnianie, pobierając token dostępowy i wykonując operację wymagającą autoryzacji. SDK intermedia/ksef-api-v2 obsługuje inicjowanie uwierzytelniania, użycie podpisu XAdES lub tokenu KSeF oraz pobieranie i odświeżanie tokenów dostępowych⁵.
Odczytaj wynik każdej operacji osobno. Ustalisz wtedy, czy problem leży w połączeniu, uwierzytelnieniu czy zakresie dostępu. Token odświeżający może być ważny do siedmiu dni i służy do uzyskania nowego tokenu dostępowego⁹.

Dokumentacja API KSeF 2.0 – co warto wiedzieć przed integracją

Dokumentację API KSeF 2.0 Ministerstwo Finansów opublikowało 30 czerwca 2025 r.¹. Zespół IT i integrator mogą na jej podstawie opisać wymianę danych między programem a KSeF.
Dostawca oprogramowania może też wskazać, które operacje obsługuje jego produkt, a za które odpowiada firma wdrażająca połączenie¹⁴.

Najczęściej zadawane pytania

Czy błąd jednej faktury w paczce wsadowej oznacza błąd całej paczki?

Nie. API KSeF 2.0 przetwarza faktury osobno i wskazuje błąd przy dokumencie, którego dotyczy.

Czy SDK pozwala sprawdzić zgodę na wystawianie faktur z załącznikiem?

Tak. SDK intermedia/ksef-api-v2 umożliwia sprawdzenie statusu takiej zgody.

Którzy podatnicy zostali objęci obowiązkiem wystawiania faktur w KSeF od 1 lutego 2026 r.?

Podatnicy, których sprzedaż wraz z VAT przekroczyła w 2024 r. 200 mln zł.

Jaką długość musi mieć NIP testowego podmiotu tworzonego przez API?

NIP musi składać się z 10 cyfr.

Ceny i warunki sprawdzone u źródeł: październik 2026.

Stan prawny na: październik 2026.