Awaria KSeF: jak rozpoznać tryb i policzyć termin dosłania
Awarię KSeF ogłasza Ministerstwo — błąd w Twoim programie nią nie jest. Jak rozpoznać tryb, policzyć termin dosłania i ustawić kolejkę ponowień.
Awaria KSeF to stan ogłaszany przez Ministerstwo Finansów w BIP MF i w oprogramowaniu interfejsowym. Dopiero takie ogłoszenie uruchamia tryb awaryjny i termin 7 dni roboczych.
Sam błąd połączenia w Twoim programie nie jest awarią KSeF. To rozróżnienie decyduje o tym, do kiedy musisz dosłać każdą fakturę.
Ten poradnik prowadzi od pierwszego błędu do rozstrzygnięcia każdego dokumentu: diagnoza, wybór trybu, termin, kolejka ponowień i monitoring.
Nie sprawdzamy tu bieżącego stanu KSeF i nie twierdzimy, że system działa albo nie działa. Aktualny status znajdziesz wyłącznie u źródła — link jest w pierwszej sekcji.
Czy KSeF nie działa? Sprawdź to u źródła
Otwórz komunikaty techniczne Ministerstwa Finansów i znajdź wpis z dzisiejszą datą. To jedyne miejsce, które rozstrzyga sprawę oficjalnie.
W konkretnym wpisie zweryfikuj trzy rzeczy, zanim wyciągniesz wnioski.
- Środowisko — utrudnienia na TEST albo DEMO nie oznaczają awarii produkcji.
- Usługę — problem z jedną usługą może mieć inny zakres niż przerwa w przyjmowaniu faktur przez API.
- Rodzaj zdarzenia — niedostępność, awaria i awaria całkowita mają różne skutki i różne terminy.
Zachowaj treść komunikatu oraz oficjalny czas zakończenia zdarzenia. Od tego czasu, a nie od momentu, w którym pracownik zauważył błąd, liczy się większość terminów.
Ogłoszona awaria KSeF jest jedynym zdarzeniem, które daje 7 dni roboczych. Bez wpisu w tym miejscu nie masz do niego podstawy.
Gdy Ministerstwo nic nie ogłosiło
Sprawdź połączenie, program do faktur i uprawnienia. Przy jednym odrzuceniu zacznij od komunikatu walidacji, bo to zwykle problem konkretnego dokumentu.
Gdy wiele wysyłek naraz traci połączenie, zbadaj wspólny element integracji. Powody odrzucenia pojedynczej faktury omawiamy osobno, w tekście o fakturze ustrukturyzowanej.
Brak ogłoszenia nie odbiera Ci możliwości wystawiania faktur. Zostaje tryb offline24, z którego można skorzystać także wtedy, gdy KSeF działa.
Awaria KSeF, niedostępność i offline24 — trzy różne stany
Potoczne „KSeF nie działa” może oznaczać kilka różnych sytuacji. Zanim policzysz termin, przypisz dokument do właściwej procedury.
Podstawy prawne wskazuje Ministerstwo: offline24 opisuje art. 106nda, niedostępność art. 106nh, a tryb awaryjny art. 106nf ustawy o VAT.
Tryb offline24: co oznacza „24”
Nazwa nie oznacza ruchomego okna dwudziestu czterech godzin. Obowiązuje następny dzień roboczy po dniu wystawienia, przy czym dokument trzeba przesłać niezwłocznie.
Faktura z piątku ma więc standardowo termin w poniedziałek. Gdy połączenie wróci jeszcze w piątek, wyślij ją wtedy — „niezwłocznie” jest częścią reguły.
Z trybu może skorzystać każdy podatnik i nie wymaga on ogłoszonej awarii. Zasady opisuje strona Ministerstwa o trybie offline24.
Niedostępność i awaria: liczy się czas zakończenia
Przy ogłoszonej niedostępności, na przykład przy pracach serwisowych, punktem odniesienia jest koniec tej niedostępności. Nie licz terminu od chwili, w której ktoś zauważył błąd.
Przy awarii zachowaj komunikaty o jej początku i końcu. Jeżeli w terminie na dosłanie pojawi się kolejna ogłoszona awaria, siedem dni liczy się od zakończenia tej kolejnej.
Szczegóły są na stronach Ministerstwa o niedostępności i o trybie awaryjnym.
Awaria całkowita ma osobną procedurę
To szczególny stan, ogłaszany w środkach społecznego przekazu, gdy nie da się opublikować komunikatów standardowymi kanałami. Faktur wystawionych w jego trakcie nie dosyła się później do KSeF.
Awaria KSeF i awaria całkowita to więc dwa różne stany, z dwoma różnymi skutkami. Pierwsza przesuwa termin, druga znosi obowiązek.
Zdarzenie późniejsze może też zmienić zasady dokumentowi, który już czeka w kolejce. Ogłoszona awaria przesuwa termin, a awaria całkowita znosi obowiązek dosłania — opisuje to strona o awarii całkowitej.
Dlatego kolejka nie może raz policzyć daty i o dokumencie zapomnieć. Musi zachować historię zdarzeń i podstawę, z której wynika aktualny termin.
Co zrobić z fakturami, które już powstały
Kolejność ma znaczenie, bo każdy krok zmienia to, co robisz w następnym. Najgorszy scenariusz to ponowna wysyłka przed ustaleniem, co stało się z pierwszą.
Dla każdej faktury zachowaj datę wystawienia z pola P_1, czas każdej próby, identyfikatory sesji i wysyłki oraz przydzielony numer KSeF, gdy dokument zostanie przyjęty.
Przechowuj zdarzenia z jednoznaczną strefą czasową, a zespołowi pokazuj czas polski. Terminy licz z polskim kalendarzem dni roboczych.
Ustal wynik poprzedniej próby
Rozdziel dokumenty na trzy grupy: przyjęte z numerem KSeF, jednoznacznie odrzucone i te o nieznanym wyniku. Trzecia grupa jest tą, która kosztuje.
Przykład: aplikacja przesłała dokument, ale połączenie urwało się przed odebraniem odpowiedzi. Faktura mogła dotrzeć — więc najpierw odczytaj stan wcześniejszej operacji.
Weryfikacja w KSeF jest asynchroniczna, czyli następuje już po odebraniu żądania. Potwierdzenie, że plik poszedł, nie kończy procesu.
Nie uruchamiaj ponownie wystawiania faktury tylko dlatego, że poprzednia próba nie zwróciła odpowiedzi. Ponowienie dotyczy wysyłki tej samej faktury.
Ponawiaj zależnie od przyczyny
Automatyczna kolejka potrzebuje reguł, które rozróżniają błąd połączenia, limit zapytań i problem z samym dokumentem.
Przy odpowiedzi 429 KSeF podaje czas blokady w nagłówku Retry-After. Kolejne przekroczenia mogą ją wydłużać.
Ograniczenia dotyczą również odpytywania o wynik. Intensywne sprawdzanie, czy już działa, potrafi więc pogorszyć sytuację zamiast ją poprawić.
Jaki odstęp między próbami
Jeżeli dla przejściowego błędu nie ma wskazanego czasu oczekiwania, rozsądnym punktem startowym jest narastający odstęp: 30 sekund, 2 minuty, 5 minut, 15 minut.
Dodaj niewielkie losowe przesunięcie, żeby wszystkie dokumenty nie ruszały jednocześnie. To przykładowa polityka integracji, a nie harmonogram wymagany przez Ministerstwo.
Po serii błędów wstrzymaj masowe próby i sprawdzaj dostępność pojedynczymi operacjami. Gdy usługa wróci, zwiększaj tempo stopniowo.
Kolejka ponowień: co musi w niej być
Kolejka to zapis dokumentów, ich stanu i następnej czynności. Powinna przetrwać restart aplikacji i zamknięcie przeglądarki.
W sklepie wielokanałowym jej podstawowym elementem jest konkretny dokument, nie zamówienie. Jedno zamówienie może mieć fakturę pierwotną i korektę, a te mają różne stany.
Zależność między nimi też trzeba zapisać. Korekta faktury wystawionej offline powstaje dopiero po nadaniu numeru KSeF fakturze pierwotnej — więcej w tekście o korekcie faktury w KSeF.
Co przekazać klientowi w trybach offline
Sposób przekazania dokumentu zależy od trybu i od nabywcy. Ma to znaczenie, gdy automatyzacja dołącza PDF do e-maila albo zamówienia na marketplace.
Faktura przekazywana poza KSeF przed przesłaniem wymaga dwóch kodów QR: z oznaczeniem OFFLINE oraz z oznaczeniem CERTYFIKAT.
Do drugiego kodu potrzebny jest certyfikat KSeF typu 2. Certyfikat typu 1 służy do uwierzytelnienia i go nie zastąpi — piszemy o tym w tekście o certyfikacie KSeF.
Po przesłaniu i nadaniu numeru wizualizacja używana poza systemem ma już jeden kod, z numerem KSeF pod nim. Zasady opisuje materiał Ministerstwa o trybie offline i kodach QR.
Potwierdzenie transakcji, gdy numeru jeszcze nie ma
Gdy faktura offline nie ma jeszcze numeru KSeF, a nabywcą jest podatnik krajowy z NIP, można wydać mu potwierdzenie transakcji.
To osobny dokument, z własnym układem danych — nie jest fakturą i jej nie zastępuje. Zasady i wzór opisuje strona Ministerstwa o potwierdzeniu transakcji.
W automatyzacji rozdziel trzy etapy: przygotowanie XML, wysyłkę do KSeF i przekazanie dokumentu klientowi. Każdy powinien mieć własny warunek zakończenia.
Monitoring: które faktury potrzebują reakcji
Panel powinien pokazywać ryzyko dla konkretnych dokumentów. Sama liczba ponowień mówi niewiele — jedna faktura z bliskim terminem bywa pilniejsza niż sto świeżo dodanych.
Pięć wskaźników, od których warto zacząć
- Liczba dokumentów bez końcowego wyniku, z podziałem na oczekiwanie, nieznany wynik i odrzucenie.
- Najbliższy termin dosłania, wraz z numerami faktur, których dotyczy.
- Wiek najstarszej nierozstrzygniętej pozycji, także zatrzymanej do ręcznej obsługi.
- Czas od ostatniego przyjęcia, zestawiony z tym, czy trwa wysyłka nowych faktur.
- Tempo przyjmowania i przyrost kolejki — kolejka powinna maleć mimo napływu bieżących dokumentów.
Ustal moment, w którym sprawę przejmuje człowiek. Jeśli kolejna automatyczna próba wypadłaby po wewnętrznym terminie bezpieczeństwa, wywołaj alert.
Zatrzymany dokument zostaje w rejestrze i w monitoringu. Wyczerpanie prób nie może usuwać go z listy spraw do załatwienia.
Co widać w naszych danych
Powyżej opisaliśmy procedurę. Poniżej jedna liczba z naszego systemu, która pokazuje, dlaczego status trzeba czytać uważnie.
Nasza integracja sprawdza wynik wysyłki maksymalnie pięć razy. Po piątej próbie bez końcowej odpowiedzi dokument dostaje status Wysłanie nie powiodło się.
Ten status nie znaczy więc, że KSeF odrzucił fakturę. Znaczy, że przestaliśmy pytać — a wynik może być wciąż nieustalony.
Dlatego 1 373 nieudanych wysyłek to nie współczynnik odrzuceń KSeF. To suma prawdziwych odrzuceń i dokumentów, dla których wynik nigdy nie został rozstrzygnięty.
Zakres naszej obsługi KSeF opisuje strona integracji, a szerszy kontekst — przewodnik po fakturach ustrukturyzowanych.
Checklista przed zamknięciem incydentu
Sprawdź każdy punkt, zanim uznasz sprawę za zakończoną
- Każda faktura wymagająca dosłania ma zapisany tryb i termin oraz podstawę tego terminu.
- Wyniki przerwanych wysyłek zostały wyjaśnione, a nie założone.
- Dokumenty przyjęte mają numer KSeF i są wyłączone z ponownej wysyłki.
- Faktury odrzucone mają właściciela, opis przyczyny i następne działanie.
- Kolejka uwzględnia zależność korekt od dokumentów pierwotnych.
- Dokumenty przekazane klientom mają oznaczenia właściwe dla trybu i rodzaju nabywcy.
Przygotuj tę procedurę, zanim pojawi się pierwszy timeout. Zacznij od prześledzenia jednej faktury od zamówienia do numeru KSeF i sprawdź, gdzie zespół znajdzie jej historię.
Czy dany obowiązek dotyczy Twojej sprzedaży, ustal ze swoją księgowością. My opisujemy, co robi walidacja i co zapisuje system.
