KSeF przyjął fakturę, ale jej nie przetworzył. Jak obsłużyć statusy, retry i duplikaty

HTTP 202 nie oznacza, że faktura ma już numer KSeF

W sesji interaktywnej endpoint wysyłki faktury przyjmuje zaszyfrowany dokument i rozpoczyna jego przetwarzanie.

Poprawna odpowiedź na samo żądanie wysyłki ma kod HTTP 202 Accepted i zawiera numer referencyjny dokumentu. Nie jest to jeszcze numer KSeF ani informacja o pomyślnym zakończeniu weryfikacji.

Aktualna specyfikacja API rozróżnia między innymi następujące statusy faktury:

Dla statusu 550 dokumentacja wskazuje, że przetwarzanie przerwano z przyczyn wewnętrznych systemu i operację należy spróbować ponownie. Statusy 100 i 150 oznaczają natomiast, że przetwarzanie nadal trwa.

Faktura, która otrzymała numer referencyjny, ale nadal ma status 100 lub 150, nie zakończyła jeszcze przetwarzania. Sam brak numeru KSeF nie jest w takim przypadku sygnałem do ponownej wysyłki.

KSeF może przyjmować dokumenty, mimo że jeszcze ich nie przetwarza

To nie jest wyłącznie hipotetyczny scenariusz.

22 kwietnia 2026 r. Ministerstwo Finansów przeprowadziło na środowisku testowym symulację braku przetwarzania faktur. API pozostawało dostępne. Można było przesyłać faktury oraz paczki, ale przyjęte dokumenty nie były w tym czasie przetwarzane.

Nie otrzymywały numerów KSeF ani UPO. Po zakończeniu symulacji wcześniejsze dokumenty zostały obsłużone.

Podobny mechanizm pojawił się podczas prac serwisowych na środowisku integracyjnym i przedprodukcyjnym w styczniu 2026 r. Ministerstwo Finansów poinformowało wtedy, żeby nie przesyłać ponownie tych samych dokumentów i oczekiwać na dalsze statusy przetwarzania. Po zakończeniu prac dokumenty miały zostać przeprocesowane.

Nie oznacza to, że każdą sytuację produkcyjną należy obsługiwać identycznie. Pokazuje jednak, dlaczego mechaniczne ponawianie wysyłki tylko dlatego, że dokument nie otrzymał jeszcze numeru KSeF, jest błędnym modelem integracji.

Retry powinno zależeć od odpowiedzi systemu

Najprostszy mechanizm może wyglądać tak:

1. wyślij fakturę,

2. poczekaj określony czas,

3. jeśli nie ma końcowego wyniku, wyślij ją ponownie.

Taki model nie uwzględnia asynchronicznego charakteru KSeF.

Po wysłaniu dokumentu integracja otrzymuje jego numer referencyjny. API udostępnia osobny mechanizm sprawdzania statusu faktury w ramach sesji.

Jeżeli dokument ma status 100 albo 150, system powinien dalej śledzić jego stan zamiast traktować oczekiwanie jako błąd wysyłki.

Ponowienie operacji powinno wynikać z konkretnej odpowiedzi API lub kontrolowanego scenariusza awaryjnego, a nie wyłącznie z tego, że numer KSeF nie pojawił się od razu.

HTTP 429 ma własny mechanizm oczekiwania

KSeF ogranicza liczbę żądań wykonywanych do API.

Po przekroczeniu limitu system zwraca HTTP 429 Too Many Requests. Odpowiedź zawiera nagłówek Retry-After, który określa w sekundach, jak długo należy poczekać przed kolejną próbą.

Czas blokady jest dynamiczny, a wielokrotne przekroczenia mogą go wydłużać.

Przykładowa odpowiedź udokumentowana przez MF zawiera:

Retry-After: 30

Integracja nie powinna więc ignorować informacji zwracanej przez serwer i stosować własnego, sztywnego interwału ponowień.

Dokumentacja MF zwraca też uwagę na architekturę integracji przy większej liczbie dokumentów. Jeżeli proces regularnie zbliża się do limitów API, należy ograniczyć liczbę pojedynczych wywołań i korzystać z mechanizmów przeznaczonych do większych wolumenów, w tym eksportów paczek przy pobieraniu danych.

Status 440 oznacza, że dokument już istnieje w KSeF

KSeF wykrywa duplikaty na podstawie kombinacji trzech wartości:

1. NIP-u sprzedawcy,

2. rodzaju faktury,

3. numeru faktury.

Jeżeli dokument zostanie rozpoznany jako duplikat, zwracany jest status 440.

Aktualne API może w takim przypadku zwrócić również numer wcześniejszej sesji oraz oryginalny numer KSeF dokumentu, który został już prawidłowo przesłany.

To istotne dla procesu odzyskiwania spójności.

Status 440 nie powinien być obsługiwany tak samo jak błąd składni XML albo nieprawidłowa semantyka faktury. System dostał informację, że odpowiadający dokument już znajduje się w KSeF.

Integracja może wtedy powiązać lokalny rekord z istniejącym dokumentem zamiast uruchamiać kolejne niekontrolowane próby wysłania tej samej faktury.

Najtrudniejszy przypadek: timeout bez odpowiedzi

Nie każda awaria kończy się czytelnym kodem 429, 440 albo 550.

Możliwy jest typowy dla integracji HTTP scenariusz, w którym aplikacja wysłała żądanie, ale połączenie zostało przerwane przed odebraniem odpowiedzi.

Na podstawie samego timeoutu klient nie może rozstrzygnąć, czy żądanie:

• nie dotarło do serwera,

• zostało przyjęte, ale odpowiedź nie dotarła do aplikacji.

To rozróżnienie ma znaczenie przy ponowieniu operacji.

Taki przypadek warto przechowywać jako osobny stan wymagający uzgodnienia z KSeF przed kolejnym działaniem. Jeżeli dokument faktycznie trafił już do systemu, ponowna wysyłka może zostać później rozpoznana jako duplikat.

Nie jest to oficjalny status KSeF. To decyzja architektoniczna po stronie systemu integrującego, wynikająca z konieczności obsługi niejednoznacznego wyniku komunikacji.

Lokalny system potrzebuje własnej maszyny stanów

Statusu faktury w ERP albo innym systemie finansowym nie warto redukować do jednego pola wysłano: tak/nie.

Przykładowa lokalna reprezentacja może wyglądać tak:

To nie są oficjalne nazwy stanów KSeF. Jest to przykład warstwy, którą system firmy może zbudować na podstawie odpowiedzi zwracanych przez API.

Taki model pozwala odróżnić oczekiwanie na przetwarzanie od rzeczywistego błędu, duplikatu albo problemu komunikacyjnego.

KSeF nie powinien być bazą danych dla każdego ekranu użytkownika

Dokumentacja Ministerstwa Finansów wskazuje, że niewłaściwym modelem integracji jest obsługiwanie działań użytkownika końcowego, takich jak wyświetlanie pełnej treści faktury czy pobieranie XML, przez bezpośrednie wywołanie API KSeF za każdym razem.

MF rekomenduje korzystanie z lokalnej bazy danych, wcześniej zsynchronizowanej z KSeF. Przy większym wolumenie pojedyncze pobieranie faktur również jest niezalecane.

Panel księgowy albo ERP nie powinien więc przy każdym otwarciu dokumentu ponownie pobierać jego treści lub całej listy faktur z KSeF.

Lokalna baza może obsługiwać wyszukiwanie, filtrowanie, raportowanie i wyświetlanie danych. Osobny proces synchronizacyjny odpowiada wtedy za utrzymywanie zgodności z centralnym repozytorium i aktualizowanie stanów dokumentów oczekujących na przetworzenie.

Błąd techniczny nie oznacza automatycznie „awarii KSeF”

W integracji trzeba rozdzielić błędy pojedynczych żądań od oficjalnych trybów przewidzianych przez przepisy.

Offline24

Tryb offline24 może być stosowany dobrowolnie. Fakturę należy przesłać do KSeF niezwłocznie, najpóźniej w następnym dniu roboczym po dniu jej wystawienia.

Niedostępność KSeF

Przy oficjalnie ogłoszonej niedostępności fakturę należy przesłać najpóźniej w następnym dniu roboczym po zakończeniu okresu niedostępności.

Awaria KSeF

Tryb awaryjny obowiązuje wtedy, gdy awaria została ogłoszona komunikatem w BIP Ministerstwa Finansów i w oprogramowaniu interfejsowym.

Fakturę wystawioną podczas takiej awarii należy przesłać do KSeF nie później niż w ciągu 7 dni roboczych od dnia zakończenia awarii.

Awaria całkowita

Przepisy przewidują również sytuację awarii całkowitej. W takim przypadku faktur wystawionych podczas awarii nie przesyła się później do KSeF.

Pojedynczy timeout, 429 albo status 550 nie oznaczają więc automatycznie oficjalnej awarii KSeF.

System powinien rozróżniać problem konkretnego żądania od komunikatu o niedostępności albo awarii całego systemu.

Co przetestować przed uruchomieniem integracji

Test integracji z KSeF nie powinien kończyć się na scenariuszu, w którym poprawna faktura otrzymuje numer KSeF.

Trzeba sprawdzić również:

• dokument pozostający przez pewien czas w statusie 100 lub 150,

• przekroczenie limitu i odpowiedź 429,

• respektowanie Retry-After,

• ponowne wysłanie tej samej faktury i status 440,

• status 550,

• odrzucenie dokumentu podczas walidacji,

• timeout przed odebraniem odpowiedzi,

• przerwanie procesu między zapisem lokalnym a komunikacją z KSeF,

• ponowne uruchomienie aplikacji z dokumentami oczekującymi,

• przejście na odpowiedni tryb offline i późniejsze przesłanie dokumentów w wymaganym terminie.

W każdym przypadku trzeba sprawdzić nie tylko odpowiedź API. Istotne są również stan lokalnej bazy, komunikat widoczny dla użytkownika oraz możliwość bezpiecznego wznowienia procesu.

Dobra integracja nie zakłada natychmiastowej odpowiedzi

Błędnym uproszczeniem jest potraktowanie KSeF jak synchronicznej funkcji:

wyślij fakturę → odbierz numer KSeF → zakończ

Produkcyjne API zwraca po wysyłce HTTP 202 i numer referencyjny, a właściwe przetwarzanie odbywa się dalej. Ministerstwo Finansów testowało również scenariusz, w którym dokumenty były przyjmowane przez dostępne API, ale przez pewien czas nie otrzymywały numerów KSeF ani UPO.

System firmy powinien dlatego przechowywać własny stan dokumentu, zapisywać identyfikatory zwracane przez KSeF, kontrolować ponowienia i potrafić wznowić proces po problemie bez generowania kolejnych niekontrolowanych wysyłek.

Ma to również znaczenie operacyjne. Ministerstwo Finansów wskazuje, że od 1 stycznia 2027 r. mają być stosowane kary między innymi za nieprzesłanie w wymaganym terminie faktury wystawionej w trybie offline24 albo podczas awarii lub niedostępności KSeF.

Stan dokumentacji: 24 września 2026 r. Produkcyjna specyfikacja KSeF API: 2.8.1.