Integracja programu z KSeF — API i wymiana danych

API KSeF 2.0 łączy zewnętrzny program z Krajowym Systemem e-Faktur. Dzięki tej integracji można w programie wystawiać, przesyłać i odbierać faktury ustrukturyzowane, zapisane w określonym formacie danych.¹
W artykule omawiamy wymianę danych, uwierzytelnianie, obsługę błędów i testowanie połączenia. Obowiązek wystawiania faktur w KSeF wprowadzono 1 lutego 2026 r. dla największych podatników, 1 kwietnia dla pozostałych, a 1 stycznia 2027 r. dla najmniejszych².

Czym jest API KSeF 2.0 i na jakich zasadach działa?

API KSeF 2.0 umożliwia wymianę danych między zewnętrznym systemem a Krajowym Systemem e-Faktur. Integrator przygotowuje wywołania zgodne ze specyfikacją, odczytuje odpowiedzi i sprawdza wynik każdej operacji.
Rządowe API nie jest tym samym co komercyjna usługa ułatwiająca połączenie. Kontrakt API KSeF 2.0 opublikowano w formacie OpenAPI 3.0.4³.

Gdzie znaleźć dokumentację API KSeF 2.0?

Ministerstwo Finansów przedstawiło dokumentację API KSeF 2.0 30 czerwca 2025 r.³
Znalazły się w niej specyfikacja, interaktywny opis wywołań i przewodnik dla integratorów. Opublikowano też przegląd zmian względem API KSeF 1.0.¹

Poniższa tabela pokazuje, co zawierają materiały integracyjne i do czego służą.

Dane w tabeli: 1,3,4

KSeFan pomaga w sprawach dokumentacji integracyjnej. KSeF API to z kolei odrębna firma, która oferuje komercyjny interfejs REST, biblioteki PHP,.NET i Java oraz przykładowe wdrożenia. Licencjonuje swoje rozwiązanie i deklaruje jego utrzymanie, wsparcie oraz aktualizacje; jej zespół rozwija interfejsy API od ponad 20 lat.⁵

Jak korzystać ze środowiska testowego i produkcyjnego API KSeF?

Środowisko testowe API KSeF pozwala sprawdzić wywołania, zanim ruch trafi na produkcję. Integrator rozdziela konfigurację połączeń i testuje żądania według specyfikacji. Po ocenie odpowiedzi może przełączyć obieg na środowisko produkcyjne.
Osobna konfiguracja zmniejsza ryzyko wysłania żądania do niewłaściwego środowiska⁶.

Jak sprawdzić poprawność integracji z API KSeF?

Poprawność integracji z API KSeF oceniaj, porównując wysłane dane i otrzymane odpowiedzi z kontraktem API. Najpierw sprawdź strukturę żądania. Potem przeanalizuj kod i treść odpowiedzi, a wynik operacji powiąż z fakturą w systemie firmy.
W ten sposób odróżnisz błąd w danych od błędu w obsłudze odpowiedzi³.

Jak dostosować limity API KSeF 2.0 do potrzeb firmy?

Limity API KSeF 2.0 wpływają na harmonogram wysyłania i pobierania danych. Według ksbot.pl zależą od środowiska oraz rodzaju operacji. Przy masowym pobieraniu serwis zaleca ponawianie prób z opóźnieniem i rozłożenie żądań w czasie.⁷
Firma może wnioskować o zwiększenie limitów w środowisku Demo lub produkcyjnym, jeśli uzasadni potrzebę operacyjną.^3,8

Integracja z KSeF wymaga zgodności z kontraktem API. Trzeba też kontrolować odpowiedzi i natężenie wywołań. Domyślny limit pobierania statusu faktury z sesji wynosi 120 żądań na minutę⁹.

Uwierzytelnianie w API KSeF: wysyłka faktur, odbiór i obsługa błędów

API KSeF 2.0 wymaga uwierzytelnienia podmiotu i uzyskania tokenu dostępu. Przy przesyłaniu lub odbieraniu faktury trzeba również kontrolować wynik operacji. Uwierzytelnianie jest oddzielone od sesji; podmiot może użyć podpisu elektronicznego XAdES albo tokenu KSeF.¹⁰
Nadanie uprawnienia nie zapewnia dostępu od razu, bo system musi je przetworzyć.¹⁰ Ważność accessToken określa pole exp tokenu JWT; dokumentacja podaje jako przykład kilkanaście minut¹¹.

Jak przesłać i odebrać fakturę przez API KSeF?

Obieg faktury przez API KSeF zaczyna się od przygotowania XML. Następnie system wysyła dokument, sprawdza jego status oraz pobiera fakturę lub Urzędowe Potwierdzenie Otrzymania (UPO). Dokumentacja komercyjnego REST API ksef24.com opisuje 4 procesy: generowanie faktury, wysyłkę z pobraniem UPO, wyszukiwanie i pobieranie faktur oraz pobranie pojedynczej faktury.¹²
Przed pobraniem UPO sprawdź status dokumentu: kod 200 w polu status.code oznacza jego pomyślne przetworzenie¹³.

• Przygotowanie XML w interfejsie ksef24.com wykonuje operacja ksefInvoiceGenerate na podstawie żądania KsefInvoiceGenerateRequest. Jeśli faktura powstała poza tym interfejsem, dokumentacja zaleca zweryfikowanie jej operacją ksefInvoiceValidate przed wysyłką.¹²
• Szyfrowanie faktury jest wymagane w API KSeF 2.0 bez względu na tryb przesyłania.¹⁰ W interfejsie ksef24.com metoda ksefPublicKey pobiera klucz publiczny do szyfrowania XML wysyłanego w szyfrowanej sesji.¹²
• Wysyłkę interaktywną w procesie ksef24.com rozpoczyna ksefSessionOpenOnline. Otrzymany SessionId identyfikuje sesję w kolejnych operacjach, a ksefInvoiceSend zwraca techniczny identyfikator InvoiceId potrzebny do sprawdzenia statusu faktury.¹²
• UPO sesji w procesie ksef24.com można pobrać przez ksefSessionUpo po poprawnym zamknięciu sesji operacją ksefSessionClose. W sesji musi zostać poprawnie wystawiona co najmniej 1 faktura.¹²
• Odbiór faktur według ksbot.pl wymaga ważnego tokenu dostępu JWT i uprawnienia InvoiceRead.⁷ W opisanych tam wywołaniach POST /invoices/query/metadata wyszukuje faktury, GET /invoices/ksef/{ksefNumber} pobiera pojedynczy dokument, a POST /invoices/exports eksportuje paczki. Faktury pozostają dostępne do pobrania przez API przez minimum 10 lat.⁷
• Pobieranie w interfejsie ksef24.com obejmuje asynchroniczne wyszukiwanie i rozpakowywanie znalezionych paczek ZIP. ksefInvoiceGet pobiera XML według numeru KSeF, natomiast ksefInvoiceVisualize może przygotować wizualizację PDF lub HTML.¹²

Jak ustalić przyczynę błędu lub braku odpowiedzi z API KSeF?

Diagnostykę API KSeF zacznij od sprawdzenia uprawnień, identyfikatora operacji i statusu dokumentu. Gdy nie ma odpowiedzi, sprawdź również dostępność używanego interfejsu. Przekroczenie limitu żądań API sygnalizuje odpowiedź HTTP 429 Too Many Requests⁹.

• Status faktury w procesie ksef24.com sprawdza się z użyciem otrzymanego identyfikatora technicznego. Kod 200 oznacza poprawne zapisanie faktury w KSeF; odpowiedź pozwala zachować jej numer KSeF i datę zapisu.¹²
• Wysyłka wsadowa w API KSeF 2.0 polega na indywidualnym przetwarzaniu faktur. System przypisuje błąd do dokumentu, w którym go wykrył, więc trzeba sprawdzić wynik każdej faktury w paczce.¹⁰
• Dostępność komercyjnego interfejsu to osobna kwestia niż odpowiedź KSeF. Firma KSeF API zapowiedziała przerwę w dostępie do swoich stron i interfejsu od 21 lutego 2026 r., godz. 22:00, do 22 lutego 2026 r., godz. 02:00.^5,14

Kontrola obiegu faktur polega na powiązaniu każdej odpowiedzi API z operacją i dokumentem. Numer KSeF ma 35 znaków. Można go użyć do powiązania odpowiedzi systemu z przyjętą fakturą¹⁵.

Środowiska KSeF 2.0: integracja i testy przed uruchomieniem

KSeF 2.0 udostępnia środowiska do przygotowania integracji oraz środowisko produkcyjne do rzeczywistego obiegu faktur. Od wybranego środowiska zależą rodzaj używanych danych i skutki wystawienia dokumentu.
Udostępnienie środowiska testowego API KSeF 2.0 zapowiedziano na 30 września 2025 r.^1,16

Tabela porównuje środowiska API KSeF 2.0 pod względem używanych danych i skutków wystawienia faktury. API KSeF 2.0 ma trzy środowiska: integracyjne, przedprodukcyjne Demo i produkcyjne. Skutki prawne wywołują wyłącznie faktury wystawione w produkcji³.

Dane w tabeli: 3

Do czego służy środowisko integracyjne KSeF 2.0?

Środowisko integracyjne API KSeF 2.0 pozwala sprawdzić, czy system firmy poprawnie przygotowuje żądania i odczytuje odpowiedzi. Integrator powinien powiązać wynik każdej próby z dokumentem w systemie finansowo-księgowym. Musi też sprawdzić, jak system obsługuje odrzucone żądanie.
Takie testy nie zastępują uruchomienia rzeczywistego obiegu³.

Jak korzystać ze środowiska przedprodukcyjnego Demo KSeF 2.0?

Środowisko przedprodukcyjne Demo API KSeF 2.0 służy do przećwiczenia obiegu faktury przed przejściem na produkcję. Skonfiguruj połączenie z Demo i wykonaj próbny obieg. Porównaj zapis dokumentu z jego statusem w używanym systemie, a po teście oddziel konfigurację Demo od produkcyjnej.
Demo i środowisko produkcyjne korzystają z odrębnych adresów bazowych API¹⁷.

KSeF 2.0 w procesie wymiany danych

KSeF 2.0 pośredniczy w wymianie danych między systemem wystawiającym fakturę a systemem, który ją odbiera. System finansowo-księgowy powinien powiązać wysłany dokument z odpowiedzią KSeF. Pobrana faktura musi z kolei trafić do właściwego zapisu w obiegu firmy.
Kontrola tych powiązań pokazuje, czy dokument tylko przygotowano, czy przeszedł dalszą obsługę. Zapis księgowy można powiązać z fakturą przez jej numer KSeF, który ma 35 znaków¹⁵.

Jak zaplanować integrację pod obieg faktur w firmie?

Integrację systemu ERP z KSeF zaplanuj według drogi faktury od wystawienia do zaksięgowania. Ustal, który system tworzy dokument, który zapisuje odpowiedź KSeF i kto zajmuje się odrzuceniem. Pobieranie faktur zakupowych przypisz do odpowiedniego procesu w systemie finansowo-księgowym, a cały obieg sprawdź przed uruchomieniem produkcyjnym.
W trybie online art. 106na ust. 1 ustawy o VAT wiąże dzień wystawienia faktury z dniem jej przesłania do KSeF¹⁸.

Rozdzielenie środowisk KSeF pozwala testować przepływ danych bez skutków prawnych właściwych produkcji. Do takich prób służą dwa środowiska nieprodukcyjne. Są to środowisko integracyjne i przedprodukcyjne Demo³.

KsefInvoiceVersion – rola wersji faktury w integracji z KSeF

KsefInvoiceVersion wskazuje wersję struktury faktury, którą integracja musi uwzględnić przy odczycie XML. Od 1 lutego 2026 r. struktura logiczna FA(3) zastępuje FA(2) w KSeF 2.0.¹
Wcześniej wystawione dokumenty nie zostaną jednak zwrócone w nowej wersji tylko z powodu tej zmiany¹⁹.

API KSeF zwraca fakturę jako XML w strukturze, w której ją wystawiono.⁷ Integracja odczytująca starsze faktury powinna więc rozpoznać wersję dokumentu przed przetworzeniem danych.
Przy fakturach historycznych może być potrzebna obsługa trzech wersji struktury: FA(1), FA(2) i FA(3)¹⁸.

Najczęściej zadawane pytania

Jak uzyskać token API do KSeF?

Najpierw uwierzytelnij podmiot — możesz użyć podpisu elektronicznego XAdES albo tokenu KSeF. Uwierzytelnianie jest oddzielone od sesji.

Czy API KSeF to to samo co komercyjny interfejs KSeF API?

Nie. Rządowe API KSeF jest odrębne od komercyjnych usług i interfejsów, które ułatwiają połączenie z systemem.

Czy UPO można pobrać przed zamknięciem sesji?

W opisanym procesie UPO sesji pobiera się po jej poprawnym zamknięciu. W sesji musi być poprawnie wystawiona co najmniej jedna faktura.

Czy błąd jednej faktury zatrzymuje całą wysyłkę wsadową?

Faktury są przetwarzane indywidualnie, a błąd przypisywany jest do dokumentu, w którym go wykryto. Sprawdź wynik każdej faktury z paczki.

Jak długo faktury są dostępne do pobrania przez API?

Według przywołanej dokumentacji faktury pozostają dostępne przez API przez minimum 10 lat.