KSeF 2026: awarie i błędy walidacji w praktyce (czego nie przewidziały poradniki sprzed startu)

Problem nie zaczyna się w dniu startu, zaczyna się tydzień później

Najwięcej paniki wokół KSeF widzieliśmy nie 1 lutego i nie 1 kwietnia 2026, tylko kilka dni po, kiedy firmy zaczęły wysyłać realny wolumen faktur, a nie testowe partie po kilka sztuk. System, który w środowisku demo działał bez zarzutu, pod obciążeniem zaczyna zwracać timeouty, wydłużać czas odpowiedzi API albo kolejkować żądania tak, że UPO przychodzi po kilku minutach zamiast po kilku sekundach. To jest moment, w którym widać, czy ktoś projektował integrację pod „działa na testach”, czy pod „działa, kiedy coś pójdzie nie tak”.

Podejście, które promujemy, jest trochę inne niż większość poradników sprzed startu obowiązku. Nie skupiamy się na tym, jak podłączyć KSeF, bo to zrobi każdy integrator w dzień, dwa. Skupiamy się na tym, co się dzieje, gdy KSeF odpowiada wolno, odrzuca fakturę z kodem błędu, którego nikt się nie spodziewał, albo wchodzi w tryb awaryjny w środku miesiąca ze szczytem sprzedaży.

Harmonogram, który trzeba znać, żeby zrozumieć skalę ruchu

Obowiązkowy KSeF wszedł etapami. Od 1 lutego 2026 obejmuje podatników, których wartość sprzedaży (wraz z kwotą podatku) przekroczyła 200 mln zł w 2024 roku, czyli największych graczy, generujących największy wolumen faktur. Od 1 kwietnia 2026 obowiązek rozszerzył się na pozostałych podatników VAT. To oznacza, że pierwszy miesiąc po starcie dla największych firm był de facto testem obciążeniowym systemu na żywym organizmie, a dopiero od kwietnia do infrastruktury dołączyła reszta rynku, co samo w sobie zwiększyło ruch na API o kolejny rząd wielkości.

Ministerstwo Finansów po starcie komunikowało zwiększone obciążenie systemu i wydłużone kolejki w godzinach szczytu, zwłaszcza w dniach typowych dla masowej fakturowania (koniec miesiąca, dni rozliczeniowe). To nie jest teoria, to realny wzorzec ruchu, który trzeba uwzględnić w projekcie integracji, a nie dowiadywać się o nim dopiero wtedy, gdy kolejka faktur do wysłania rośnie szybciej, niż system jest w stanie je przyjąć.

Tryb offline24 i tryb awaryjny: kiedy naprawdę ratują, a kiedy tylko odsuwają problem

KSeF przewiduje dwa mechanizmy na wypadek niedostępności systemu: tryb offline24 i tryb awaryjny. W trybie offline24 podatnik może wystawić fakturę bez połączenia z KSeF i przesłać ją do systemu w ciągu 24 godzin od wystawienia. Tryb awaryjny z kolei dotyczy sytuacji, gdy sam KSeF ogłasza niedostępność i wyznacza zasady działania na ten czas, zwykle z wydłużonym terminem na przesłanie faktur po przywróceniu systemu.

Problem w praktyce jest taki, że te tryby rozwiązują kwestię formalną (fakturę i tak można wystawić), ale nie rozwiązują kwestii operacyjnej: co ma zrobić automatyzacja, która normalnie wysyła fakturę do KSeF i czeka na numer KSeF oraz UPO, zanim uruchomi kolejne kroki, na przykład wysyłkę towaru albo aktualizację statusu zamówienia w sklepie. Jeśli ten łańcuch jest zbudowany sztywno, jedno zdarzenie: timeout, kolejka, komunikat o niedostępności, zatrzymuje cały proces, mimo że formalnie prawo dało podatnikowi 24 godziny luzu.

Najczęstsze błędy walidacji, które zgłaszają księgowi w pierwszych tygodniach

Z rozmów z biurami rachunkowymi i działami księgowości, które wdrażały integrację w pierwszych miesiącach obowiązku, powtarza się kilka kategorii problemów, zupełnie niezależnie od branży:

• Niezgodność ze schematem FA(3): pola wypełnione poprawnie merytorycznie, ale w złym formacie albo kolejności wymaganej przez strukturę XML, co kończy się odrzuceniem na etapie walidacji, zanim faktura w ogóle trafi do kolejki przetwarzania.
• Błędne lub nieaktualne dane kontrahenta: literówka w NIP, brak aktualizacji po zmianie formy prawnej kontrahenta, dane pobrane z systemu ERP, które od miesięcy nikt nie weryfikował.
• Duplikaty numeru faktury: szczególnie częste tam, gdzie ten sam dokument trafiał do KSeF z dwóch różnych integracji równolegle, na przykład z modułu fakturowania i z osobnego systemu korekt, bez centralnego punktu kontroli, co już zostało wysłane.
• Niezgodność sum i stawek VAT: zaokrąglenia, które na papierze nikomu nie przeszkadzały, a w rygorystycznej walidacji XML powodują odrzucenie całego dokumentu.
• Timeout przy odbiorze UPO: faktura trafia do KSeF poprawnie, ale system nie zdąża zwrócić potwierdzenia w oczekiwanym oknie czasowym, co automatyzacja często błędnie interpretuje jako błąd i próbuje wysłać fakturę ponownie, tworząc właśnie wspomniany duplikat.

Co ciekawe, większość tych błędów nie wynika z nieznajomości przepisów, tylko z tego, że dane w systemie źródłowym (ERP, CRM, sklep) nigdy nie były czyszczone pod kątem rygoru, jakiego wymaga walidacja KSeF. Papierowa czy mailowa faktura tolerowała literówkę w NIP. Automat w KSeF jej nie wybaczy.

Jak zaprojektować automatyzację, żeby awaria KSeF nie zatrzymywała sprzedaży

Tu jest sedno naszego podejścia i różnica względem standardowej integracji księgowo-informatycznej. Nie wystarczy podłączyć API KSeF do systemu fakturowania. Trzeba zaprojektować cały proces tak, jakby awaria była nie wyjątkiem, tylko regularnym elementem działania systemu, bo po pierwszych miesiącach obowiązku dokładnie tak to wygląda.

Bufor lokalny przed wysyłką

Faktura powstaje i jest zatwierdzana w systemie źródłowym natychmiast, niezależnie od tego, czy KSeF w tej sekundzie odpowiada. Wysyłka do KSeF trafia do osobnej kolejki zadań, obsługiwanej asynchronicznie. Sprzedaż, magazyn i wysyłka towaru nie czekają na numer KSeF, bo formalnie (szczególnie w trybie offline24) i tak mają na to okno czasowe. To jest różnica między „system KSeF stoi, więc nic nie działa” a „system KSeF stoi, a my i tak pracujemy, dosyłając dokumenty, gdy wróci”.

Retry z rosnącym odstępem, nie z pętlą na sztywno

Prosty mechanizm „spróbuj ponownie za 5 sekund” przy dużym wolumenie faktur i realnej kolejce po stronie KSeF tylko pogarsza sytuację, bo zalewa system kolejnymi próbami w najgorszym możliwym momencie. Lepiej sprawdza się retry z rosnącym odstępem (np. 30 sekund, potem 2 minuty, potem 10 minut) i jasnym limitem prób, po którym sprawa trafia do człowieka, a nie znika w logach. W n8n czy Make da się to zbudować bez wielkiej filozofii: węzeł obsługujący błąd, licznik prób, warunek eskalacji.

Kolejkowanie i kontrola duplikatów

Przy większym wolumenie (setki faktur dziennie) race condition jest realnym ryzykiem: dwa procesy próbują wysłać ten sam dokument niemal jednocześnie, bo jeden czeka na timeout, a drugi dostał polecenie ponowienia. Rozwiązaniem jest jedna kolejka z blokadą na poziomie numeru faktury, a nie równoległe wywołania z różnych miejsc systemu. To wymaga trochę dyscypliny architektonicznej, ale eliminuje większość zgłaszanych duplikatów.

Dobrze zaprojektowany proces monitoruje też status UPO osobno od samej wysyłki. Brak UPO w oczekiwanym czasie to sygnał do sprawdzenia, nie powód do automatycznego powtórzenia wysyłki. Takie rozróżnienie oszczędza naprawdę sporo nerwów w pierwszym kwartale po wdrożeniu.

Warto podkreślić jedno ograniczenie, bo łatwo je pominąć w entuzjazmie wokół automatyzacji: żadna automatyzacja nie zdejmie z firmy obowiązku posiadania kogoś, kto reaguje na eskalację. Automat obsłuży 80-90% przypadków: chwilowy timeout, krótką niedostępność, pojedynczy błąd walidacji z jasną przyczyną. Ale decyzję, co zrobić z fakturą, która po trzeciej próbie wciąż wraca z tym samym błędem, powinien podjąć człowiek, najlepiej księgowy albo osoba znająca kontekst transakcji, a nie kolejna reguła „spróbuj jeszcze raz”. Dobra automatyzacja faktur nie eliminuje potrzeby nadzoru, tylko znacząco zmniejsza liczbę spraw, które w ogóle do tego nadzoru trafiają. Więcej o tym, jak to wygląda praktycznie w procesach zakupowych i sprzedażowych, opisujemy na stronie automatyzacja faktur.

Co to oznacza dla biur rachunkowych obsługujących wielu klientów

Biuro rachunkowe, które obsługuje kilkudziesięciu klientów, ma zupełnie inny problem skali niż pojedyncza firma. Awaria KSeF albo seria błędów walidacji u jednego klienta to drobny incydent. U trzydziestu klientów naraz, w tym samym oknie czasowym (bo wszyscy fakturują na koniec miesiąca), to już realne ryzyko zatoru w pracy całego zespołu, jeśli każdy przypadek trzeba obsłużyć ręcznie, sprawdzając w kółko, który dokument poszedł, który czeka, a który wrócił z błędem.

Tu sprawdza się scentralizowane podejście: jedna kolejka zadań obsługująca wysyłki dla wszystkich klientów biura, z priorytetyzacją (duzi klienci i duże wolumeny najpierw) i czytelnym dashboardem pokazującym, co utknęło i dlaczego. To jest dokładnie ten typ procesu, który opisujemy szerzej w kontekście automatyzacji biura rachunkowego, bo skala problemu rośnie tam nieliniowo wraz z liczbą obsługiwanych podmiotów.

Czego nie robić

Nie polecamy budowania integracji z KSeF jako pojedynczego, synchronicznego kroku w procesie sprzedaży, w którym brak odpowiedzi z API oznacza zatrzymanie zamówienia. To rozwiązanie wygląda prosto na etapie demo i katastrofalnie w pierwszym tygodniu zwiększonego ruchu. Nie polecamy też ślepego, nieograniczonego retry, bo przy realnych kolejkach po stronie systemu rządowego taki mechanizm sam sobie szkodzi, generując więcej żądań w najgorszym możliwym momencie. I nie polecamy całkowitego automatycznego odrzucania faktur z błędem walidacji bez logu i powiadomienia, bo to tylko przenosi problem o miesiąc, na czas zamknięcia okresu rozliczeniowego, kiedy jest już dużo trudniej go naprawić.