Błąd KSeF w sklepie: diagnoza i ponowienie faktury

Wstrzymaj automatyczne ponawianie problematycznej pozycji, ale nie usuwaj całej kolejki. Zapisz identyfikator zamówienia, numer dokumentu w systemie wystawiającym, czas próby wraz ze strefą czasową oraz referencję sesji lub wysyłki, jeśli została nadana. Zachowaj wynik operacji i wersję danych przesłanych do KSeF. Bez tego po poprawce trudno rozstrzygnąć, który dokument został przyjęty.

Rozdziel objawy: faktura nie została przygotowana, nie wyszła z integracji, została odrzucona albo otrzymała potwierdzenie, którego sklep nie zapisał. Brak numeru KSeF w panelu sklepu sam w sobie nie przesądza o odrzuceniu. Sprawdź system faktycznie odpowiedzialny za wystawianie, zwłaszcza gdy zamówienie przechodzi przez ERP, a WooCommerce pokazuje tylko kopię jego statusu.

Ustal też, czy dany dokument podlega obowiązkowi KSeF. Według MF o zakresie obowiązku etap od 1 lutego 2026 r. dotyczy podatników ze sprzedażą brutto powyżej 200 mln zł w 2024 r.; zasadniczy kolejny etap rozpoczął się 1 kwietnia. Faktury konsumenckie nie są objęte obowiązkowym wystawianiem w KSeF. Szczególne wyłączenia i przejściowe ułatwienia oceń z księgowością, zamiast wyłączać integrację dla wszystkich zamówień.

Przygotuj jedną kartę incydentu z właścicielem następnego kroku. Obsługa klienta potrzebuje informacji o stanie sprawy, księgowość o dokumencie, a wykonawca o operacji technicznej. To ogranicza równoległe próby naprawy tej samej faktury przez kilka osób.

Błąd danych naprawiaj w miejscu, z którego integracja je pobiera. Ręczna zmiana wygenerowanego XML może zniknąć przy kolejnej próbie, jeśli ERP ponownie zbuduje dokument z niepoprawnego zamówienia. Porównaj wartości z koszyka, dokumentu księgowego i wysyłanego pliku. Szukaj konkretnego pola wskazanego w odpowiedzi, a nie wszystkich możliwych błędów naraz.

Sprawdź typ nabywcy, identyfikatory podatkowe właściwe dla transakcji, walutę, daty, stawki i kwoty. Nie wymagaj polskiego NIP od każdego kupującego tylko po to, żeby przejść walidację. Dla klientów zagranicznych i konsumentów znaczenie ma poprawny model danych oraz właściwy sposób udokumentowania sprzedaży. Decyzję podatkową uzgodnij z osobą prowadzącą rozliczenia, a dopiero potem odwzoruj ją w formularzu i integracji.

FA(3) nie jest dowolnym zestawem etykiet. Moduł musi wygenerować dokument zgodny ze strukturą i obsługiwanymi regułami. Sprawdź jego wersję oraz datę ostatniej aktualizacji. Przy kwotach prześledź rabat, koszt dostawy, zaokrąglenia i sposób liczenia podatku. Zgodność sumy zamówienia nie gwarantuje poprawności wszystkich pozycji dokumentu.

W izolowanym środowisku odtwórz problem na syntetycznych danych. Zablokuj wysyłkę do produkcyjnego KSeF, pocztę, płatności i pomiar konwersji. Najpierw sprawdź samo przygotowanie oraz walidację pliku. Procedurę zbierania danych w sklepie rozwija konfiguracja faktur w WooCommerce. Ten etap kończysz dopiero wtedy, gdy potrafisz wskazać przyczynę, poprawione pole i wynik powtórnej walidacji.

Przy problemie z dostępem zapisz nazwę środowiska oraz kontekst podatnika, bez ujawniania sekretów. Sprawdź, czy integracja łączy się z właściwym adresem API i używa poświadczeń przeznaczonych dla tego środowiska. Poprawne dane testowe nie zapewniają dostępu do produkcji. Po migracji serwera skontroluj także zegar, odczyt plików kluczy i konfigurację procesu wykonującego zadania w tle.

Uwierzytelnienie potwierdza tożsamość, lecz nie zastępuje uprawnienia do wymaganej czynności. Zweryfikuj, w czyim kontekście działa integracja oraz czy nadal ma prawo wystawiać lub odczytywać faktury. Zmiana pracownika, biura rachunkowego albo sposobu reprezentacji firmy może wymagać uporządkowania dostępów. Nie rozwiązuj takiego problemu przez przekazanie wykonawcy wszystkich uprawnień administracyjnych.

Dokumentacja uwierzytelniania API KSeF rozróżnia metody rozpoczęcia uwierzytelniania oraz tokeny dostępu używane w dalszej komunikacji. Wygaśnięcie access tokenu nie oznacza automatycznie, że trzeba tworzyć nowy długotrwały token KSeF. Integrator powinien ustalić, na którym etapie proces się zatrzymuje i czy działa odświeżanie dostępu.

Aktualizacja źródeł ma tu znaczenie. Na stronie MF o certyfikatach KSeF, odczytanej 14 września 2026 r., resort informuje o decyzji utrzymania tokenów bezterminowo i zapowiada zmianę rozporządzenia. Nie traktuj dawnej daty końca 2026 r. jako pewnej daty wyłączenia tokenów ani zapowiedzi nowelizacji jako dowodu, że już weszła w życie. Zaplanuj przegląd aktualnego komunikatu przed zmianą sposobu logowania.

Kod HTTP opisuje konkretną wymianę z API. Wynik biznesowy mówi, co stało się z dokumentem. Zapisane połączenie i odebrana odpowiedź nie muszą oznaczać przyjęcia faktury. Integracja powinna umieć odczytać dalszy status, zapisać numer KSeF po jego nadaniu i udostępnić potwierdzenie właściwe dla zakończonego procesu.

Zbuduj oś zdarzeń: przygotowanie pliku, rozpoczęcie sesji, wysyłka, przyjęcie do przetwarzania, wynik oraz zapis tego wyniku w systemie lokalnym. Nazwy stanów zależą od modułu. Ważne, aby nie sprowadzać ich wszystkich do jednego pola wysłano. Dla każdego etapu ustal, jaki identyfikator pozwala wrócić do tej samej operacji.

Timeout może wystąpić po odebraniu żądania przez drugą stronę. Dlatego po utracie odpowiedzi najpierw odczytaj stan poprzedniej próby, wykorzystując dostępne referencje. Nie zakładaj ani sukcesu, ani porażki. Jeśli integracja nie zachowała identyfikatora, potrzebna jest kontrola rejestrów i uzgodnienie dokumentu, a nie seria kolejnych kliknięć.

Oddziel również problem KSeF od awarii synchronizacji ERP ze sklepem. Faktura może być poprawnie obsłużona w systemie księgowym, podczas gdy panel zamówienia pokazuje stary stan. Przy takim układzie pomocna jest diagnostyka synchronizacji Subiekta nexo. Naprawa powinna odtworzyć brakujące powiązanie, bez wystawiania drugiego dokumentu tylko dla odświeżenia widoku.

Brak internetu w magazynie, wygasłe poświadczenie i oficjalnie ogłoszona awaria KSeF to różne zdarzenia. Najpierw sprawdź komunikat MF i czas jego obowiązywania. Zachowaj źródło informacji w karcie incydentu. Sam czerwony komunikat we wtyczce nie jest podstawą do przyjęcia zasad dotyczących awarii systemu państwowego.

MF opisuje offline24 jako odrębny tryb, z którego może korzystać podatnik także poza ogłoszoną awarią. Co do zasady fakturę należy przesłać najpóźniej w następnym dniu roboczym po jej wystawieniu. Wystawienie dokumentu w tym trybie nie oznacza więc bezterminowego odłożenia kolejki. Ustal datę wystawienia, termin dosłania i osobę nadzorującą jego dochowanie.

Dla niedostępności KSeF i ogłoszonej awarii obowiązują odrębne zasady. Nie przenoś automatycznie terminu z offline24 na każdą przerwę. Jeśli sytuacja zmieniła się między wystawieniem a wysłaniem, sprawdź regułę właściwą dla tej sekwencji zdarzeń w komunikacie MF i z księgowością.

Certyfikat typu 1 służy do uwierzytelniania. Typ 2 ma inną rolę: pozwala potwierdzić wystawcę w mechanizmie weryfikacji faktur wystawianych poza bieżącym przesłaniem do KSeF. Nie jest uniwersalnym podpisem wymaganym dla każdego XML. Sposób udostępnienia dokumentu poza KSeF i oznaczenia kodami QR zależy od trybu oraz odbiorcy. Przed uruchomieniem takiej ścieżki sprawdź jej obsługę w module, zamiast samodzielnie dopisywać obrazek QR do zwykłego PDF.

Retry powinno wynikać z rozpoznanego stanu. Po jednoznacznym odrzuceniu z powodu danych popraw źródło i przygotuj kontrolowaną próbę. Przy przetwarzaniu w toku odczytuj wynik zgodnie z dokumentacją oraz limitami API. Przy nieznanym wyniku najpierw odtwórz poprzednią operację. Dokument już przyjęty wymaga innej ścieżki niż plik, którego KSeF nie zaakceptował.

Zapisuj trwałe powiązanie między zamówieniem, dokumentem lokalnym i identyfikatorem w KSeF. Blokada równoczesnego wykonania zadania ogranicza ryzyko, że harmonogram i pracownik uruchomią tę samą wysyłkę jednocześnie. Sam przycisk ponów nie wystarcza: integracja musi rozpoznawać istniejącą operację również po restarcie procesu lub serwera.

Jeżeli faktura została przyjęta, a jej treść wymaga zmiany, przekaż sprawę księgowości do właściwego postępowania z dokumentem, w tym korekty, gdy jest potrzebna. Nie usuwaj lokalnego wpisu, aby wystawić tę samą sprzedaż ponownie jak nową. Zachowanie historii pozwala wyjaśnić klientowi i obsłudze, co dokładnie poprawiono.

Przetestuj mechanizm na odizolowanej kopii: powtórne zadanie, przerwanie po wysłaniu żądania, restart przed zapisem wyniku i dwie równoległe próby. Użyj odpowiedzi symulowanych albo uzgodnionego środowiska testowego z syntetycznymi dokumentami. Zablokuj wszystkie produkcyjne połączenia i działania następcze. Wynikiem testu ma być spójny rejestr jednej operacji, nie nowa faktura produkcyjna.

Naprawę odbieraj na konkretnym scenariuszu, który wcześniej kończył się błędem. Sprawdź poprawiony dokument, rozpoznanie wyniku, zapis identyfikatorów i zachowanie po ponowieniu. Oddziel odbiór techniczny od oceny księgowej. Działające połączenie nie potwierdza poprawności dat, stawek czy sposobu dokumentowania sprzedaży.

Zgłoszenie do wykonawcy powinno zawierać wersje sklepu i modułu, środowisko, czas zdarzenia, ostatni znany stan oraz bezpiecznie przekazane referencje operacji. Opisz oczekiwany wynik i kroki odtworzenia na danych testowych. Usuń tokeny, klucze prywatne oraz zbędne dane osobowe z logów. Nie publikuj pełnych dokumentów klientów w publicznym zgłoszeniu błędu.

Po poprawce przejrzyj zatrzymaną kolejkę wspólnie z księgowością. Każda pozycja wymaga rozstrzygnięcia: zakończona, oczekująca na wynik, odrzucona albo wymagająca uzgodnienia. Wznawiaj ją partiami z kontrolą rezultatów, nie jednym poleceniem dla całej historii. Ustal też alarm na dokumenty pozostające zbyt długo w stanie pośrednim oraz osobę, która reaguje na taki alarm.

Jeśli problem wynika z podziału odpowiedzialności między kilka systemów, porównaj wtyczkę KSeF z integracją API. W ramach automatyzacji i obsługi sklepów internetowych można uporządkować przepływ danych, kolejkę i diagnostykę. Przez kontakt przekaż opis systemów oraz zanonimizowany komunikat. Pozwoli to określić zakres prac bez przesyłania sekretów i rzeczywistych faktur w pierwszej wiadomości.