Obsługa KSeF — statusy faktur, błędy i jak rozwiązać najczęstsze problemy

Co oznaczają statusy dokumentu w KSeF

Po wysłaniu faktury do KSeF dokument przechodzi przez kilka stanów, zanim uzyska numer KSeF:

• Oczekuje na przetworzenie — dokument dotarł do systemu, ale nie został jeszcze zweryfikowany. Zwykle trwa to kilka sekund do kilku minut.
• Dokument oczekuje na zatwierdzenie przez KSeF — trwa walidacja struktury i danych. Jeśli ten status utrzymuje się długo (ponad kilkanaście minut), zwykle oznacza to duże obciążenie systemu MF, nie błąd po Twojej stronie. Nie wysyłaj faktury ponownie — poczekaj i sprawdź status później, żeby uniknąć duplikatu.
• Przyjęty / nadany numer KSeF — dokument przeszedł walidację, ma nadany numer KSeF i jest uznawany za wystawiony.
• Odrzucony — dokument nie przeszedł walidacji. System podaje kod błędu i opis — najczęściej dotyczy to niezgodności NIP, błędnej sumy kontrolnej lub nieprawidłowego formatu pola.

Najczęstsze problemy i jak je rozwiązać

Faktura nie trafia do KSeF mimo wysyłki

Sprawdź najpierw status połączenia firmy z KSeF w ustawieniach — token mógł wygasnąć albo zostać unieważniony w portalu KSeF. Wygasły token trzeba wygenerować ponownie i podmienić w aplikacji.

Dokument odrzucony — błąd walidacji

Kod błędu w komunikacie wskazuje konkretne pole. Najczęstsze przyczyny: NIP nabywcy niezgodny z formatem, brak wymaganego elementu faktury (np. daty sprzedaży), błędna waluta lub duplikat numeru faktury już wysłanego wcześniej.

Token przestał działać

Tokeny KSeF mają termin ważności i mogą zostać cofnięte ręcznie w portalu. Jeśli aplikacja zgłasza błąd autoryzacji, wygeneruj nowy token zgodnie z instrukcją podłączenia firmy i zaktualizuj go w ustawieniach.

Faktura wysłana dwa razy (duplikat)

Jeśli ponowiłeś wysyłkę w trakcie długiego statusu "oczekuje na zatwierdzenie", KSeF może odrzucić drugą próbę jako duplikat numeru — to prawidłowe zachowanie, nie błąd. Sprawdź numer KSeF pierwszej wysyłki zamiast wysyłać fakturę po raz trzeci.

Środowisko testowe vs produkcyjne

KSeF ma osobne środowisko testowe (dla próbnych wysyłek) i produkcyjne. Token z jednego środowiska nie działa w drugim — to najczęstsza przyczyna komunikatu "nieprawidłowy token" przy pierwszym podłączeniu.

Gdzie szukać pomocy poza aplikacją

• Infolinia Krajowej Informacji Skarbowej — pytania o przepisy i obowiązki związane z KSeF.
• Portal podatki.gov.pl / KSeF — status techniczny systemu, komunikaty o awariach i planowanych przerwach.
• Wsparcie KsięgaI — jeśli problem dotyczy samej integracji (token, wysyłka, statusy w aplikacji), napisz do wsparcia z numerem faktury i zrzutem ekranu błędu.

Kiedy problem nie leży po Twojej stronie

W okresach szczytowego obciążenia (np. koniec miesiąca) KSeF bywa wolniejszy niż zwykle, a status "oczekuje na zatwierdzenie" może utrzymywać się dłużej niż normalnie. To ograniczenie systemu MF — sprawdzaj komunikaty o dostępności na portalu KSeF zamiast zakładać błąd po stronie własnej faktury.