KSeF w praktyce: jak automatycznie pobierać faktury przez API

Kogo dotyczy KSeF w 2026 roku

Obowiązek otrzymywania faktur w KSeF istnieje od 1 lutego 2026 r. i dotyczy wszystkich podatników, także tych, którzy sami jeszcze nie wystawiają faktur w systemie. Wystawianie faktur w KSeF stało się obowiązkowe 1 lutego 2026 r. dla firm ze sprzedażą powyżej 200 mln zł w 2024 r. i 1 kwietnia 2026 r. dla pozostałych. Do końca 2026 r. obowiązują wyjątki, m.in. przy sprzedaży do 10 000 zł miesięcznie i dla faktur z kas rejestrujących.

Czy faktury z KSeF da się pobierać automatycznie?

Tak. W oficjalnych pytaniach i odpowiedziach o KSeF 2.0 ministerstwo pisze, że system pozwala na integrację, dzięki której faktury są automatycznie pobierane. Nikt nie musi logować się do Aplikacji Podatnika i ręcznie ściągać plików XML. Taką integrację ma wiele programów księgowych, ale można ją zbudować także pod własny proces, np. gdy faktury mają trafiać do arkusza kosztów, CRM-u albo systemu akceptacji.

Uwierzytelnienie: kontekst, token albo certyfikat

Każde wywołanie API KSeF 2.0 wymaga tokena dostępu (accessToken) w formacie JWT. Żeby go dostać, system przechodzi krótką procedurę opisaną w dokumentacji ministerstwa:

1. 01

   Wyzwanie

   System prosi o wyzwanie (POST /auth/challenge). Jest ważne 10 minut.

2. 02

   Uwierzytelnienie

   Odsyła wyzwanie razem z kontekstem, czyli identyfikatorem firmy (zwykle NIP), w jednej z dwóch form: dokument XML podpisany w formacie XAdES (np. certyfikatem KSeF, pieczęcią kwalifikowaną) albo zaszyfrowany token KSeF (POST /auth/xades-signature lub POST /auth/ksef-token).

3. 03

   Sprawdzenie statusu

   KSeF weryfikuje podpis i uprawnienia. System sprawdza wynik (GET /auth/{referenceNumber}).

4. 04

   Tokeny dostępu

   Po pozytywnej weryfikacji system odbiera accessToken (ważny kilka minut) i refreshToken (ważny do 7 dni), którym odświeża dostęp bez ponownego logowania (POST /auth/token/redeem, POST /auth/token/refresh).

W 2026 r. tokeny KSeF i certyfikaty KSeF działają równolegle. Certyfikat KSeF (typ 1 służy do uwierzytelniania) wydaje Ministerstwo Finansów i jest ważny maksymalnie 2 lata. Przy nowych integracjach warto od razu przewidzieć certyfikat, bo źródła branżowe wskazują tokeny jako rozwiązanie przejściowe.

Trzy sposoby pobierania faktur

Przy fakturach kosztowych interesuje Cię rola nabywcy, w API oznaczona jako Subject2 (Podmiot 2). Sprzedawca to Subject1, a Subject3 to inne podmioty występujące na fakturze.

Pobieranie przyrostowe: bez dziur i bez duplikatów

Najczęstszy błąd w integracjach to pobieranie „od ostatniej daty wystawienia”. Faktury trafiają do KSeF z opóźnieniem, więc tak zbudowany przepływ potrafi pominąć dokumenty. Dokumentacja ministerstwa opisuje bezpieczny sposób:

• Do pobierania przyrostowego używaj daty typu PermanentStorage, czyli momentu trwałego zapisu faktury w KSeF. Ministerstwo pisze, że jest to konieczne.
• Kolejne okna czasowe muszą do siebie przylegać, bez przerw i bez nakładania.
• Korzystaj z mechanizmu „high water mark” (PermanentStorageHwmDate) i opcji RestrictToPermanentStorageHwmDate, żeby następny eksport zaczął się dokładnie tam, gdzie skończył się poprzedni.
• Usuwaj duplikaty po numerze KSeF z pliku _metadata.json.

Ograniczenia częstotliwości są konkretne: maksymalnie 20 eksportów na godzinę dla wszystkich typów podmiotów łącznie, a przy ciągłej synchronizacji zalecane są 4 eksporty na godzinę dla jednego typu podmiotu, nie częściej niż co 15 minut. Po przekroczeniu limitu KSeF odpowiada kodem HTTP 429 z nagłówkiem Retry-After. Dlatego przepływ w moim przykładzie automatyzacji pobiera faktury co kwadrans.

Co dalej z pobraną fakturą

Faktura w KSeF to ustrukturyzowany plik XML, więc da się z niego odczytać sprzedawcę, pozycje, kwoty i stawki VAT bez przepisywania. Typowy przepływ, który buduję:

1. Pobranie nowych faktur kosztowych co 15 minut i zapis oryginałów XML w archiwum firmy.
2. Odczytanie danych: kontrahent, numer, daty, pozycje, netto, VAT, brutto.
3. Opcjonalnie: model językowy przypisuje kategorię kosztu albo projekt, a nietypowe pozycje oznacza do sprawdzenia.
4. Zapis do arkusza kosztów, CRM-u lub systemu księgowego.
5. Powiadomienie, gdy przychodzi faktura od nowego kontrahenta albo kwota odbiega od zwykłej.

Taki przepływ da się zbudować w n8n albo we własnym kodzie. O tym, które narzędzie wybrać, piszę w porównaniu n8n, Make czy Zapier.

Środowiska i testy

KSeF 2.0 działa w trzech środowiskach: testowym (TEST), przedprodukcyjnym (DEMO) i produkcyjnym (PROD), gdzie faktury mają pełną moc prawną. Integrację testuje się najpierw poza produkcją, na danych testowych, a dopiero potem włącza na prawdziwym koncie firmy. Ministerstwo udostępnia też oficjalne biblioteki klienckie (m.in. dla C# i Javy), które pokazują poprawne wywołania API.

Tryby offline i awarie

Jeśli wystawiasz faktury i KSeF jest niedostępny, przepisy przewidują tryby awaryjne. W trybie offline24 fakturę trzeba dosłać niezwłocznie, nie później niż w następnym dniu roboczym po jej wystawieniu. W trybie awarii systemu termin to 7 dni roboczych od zakończenia awarii. Dobra integracja przy wystawianiu pilnuje tych terminów sama i ponawia wysyłkę.

Jeśli chcesz, żeby faktury z KSeF trafiały tam, gdzie pracujesz, zobacz, jak buduję integracje z KSeF, albo napisz. Po krótkiej rozmowie dostaniesz wycenę na piśmie w 48 h.

Przygotowane z pomocą narzędzi AI, sprawdzone i uzupełnione przez autora. Liczby i przepisy mają podane źródła.