Program pokazuje, że sesja w Krajowym Systemie e-Faktur (KSeF) skończyła się kodem 445 i komunikatem „Błąd weryfikacji, brak poprawnych faktur”. Żadna faktura z tej sesji nie dostała numeru KSeF. Sam komunikat nie mówi jednak, co było nie tak.
Ten tekst pokazuje, gdzie szukać prawdziwej przyczyny i jak czytać dwa poziomy statusów w KSeF: status sesji i status faktury. To ich mylenie najczęściej utrudnia diagnozę. Kody o innych numerach znajdziesz na pełnej liście kodów błędów KSeF.
Co oznacza kod 445
445 to status sesji, nie faktury. Występuje w obu rodzajach sesji: wsadowej i interaktywnej. Opis MF jest w obu ten sam: „Błąd weryfikacji, brak poprawnych faktur”.
Dokumentacja MF podaje tylko opis, bez dalszych wyjaśnień, więc czytamy go dosłownie. Sesja doszła do weryfikacji faktur, ale żadna faktura jej nie przeszła. Kod 445 jest więc podsumowaniem, a nie przyczyną. Przyczynę KSeF zapisuje przy każdej fakturze osobno.
W tabelach statusów faktur i statusów logowania kodu 445 nie ma. Jeżeli go widzisz, zawsze chodzi o sesję. Dlatego ta strona, inaczej niż strony o kodach 440 czy 450, nie opisuje drugiego znaczenia.
Dwa poziomy statusów: sesja i faktura
KSeF prowadzi dwa osobne statusy. Status sesji mówi, co stało się z całą wysyłką. Status faktury mówi, co stało się z jednym dokumentem. Część numerów występuje na obu poziomach i znaczy na nich co innego:
| Kod | Jako status sesji | Jako status faktury |
|---|---|---|
| 405 | „Błąd weryfikacji poprawności dostarczonych elementów paczki” (sesja wsadowa) | „Przetwarzanie anulowane z powodu błędu sesji” |
| 415 | „Błąd odszyfrowania dostarczonego klucza” | „Brak możliwości wysyłania faktury z załącznikiem” |
| 430 | „Błąd dekompresji pierwotnego archiwum” (sesja wsadowa) | „Błąd weryfikacji pliku faktury” |
| 435 | „Błąd odszyfrowania zaszyfrowanych części archiwum” (sesja wsadowa) | „Błąd odszyfrowania pliku” |
| 440 | „Sesja anulowana” | „Duplikat faktury” |
| 445 | „Błąd weryfikacji, brak poprawnych faktur” | nie występuje |
Kody sesji 405, 415, 430 i 435 mówią o problemie z paczką albo z kluczem szyfrującym, czyli z samą wysyłką. Kod 445 mówi co innego: wysyłka dotarła, a odrzucone zostały faktury.
Jedna ważna uwaga. Kod 445 pojawia się tylko wtedy, gdy nie przeszła żadna faktura. Jeżeli przeszła choć jedna, sesja nie dostaje 445. Odrzucone faktury trzeba wtedy wyłapać po ich własnych statusach, bo status sesji o nich nie powie.
Najczęstsze przyczyny
Dokumentacja MF nie wymienia przyczyn kodu 445. Z jego opisu wynika, że przyczyny trzeba szukać przy fakturach. Poniższa lista to nasze odczytanie statusów faktur, które mogą za nim stać:
- Sesja z jedną fakturą. Jeżeli w sesji była jedna faktura i KSeF ją odrzucił, cała sesja dostaje 445. Kod sesji jest wtedy tylko skutkiem statusu tej faktury, na przykład 450 „Błąd weryfikacji semantyki dokumentu faktury”. Pola FA(3), które go wywołują, opisujemy w tekście o błędzie 450 w KSeF.
- Ten sam błąd w każdej fakturze paczki. Generator albo szablon w programie popełnia jeden błąd we wszystkich plikach. Rozpoznasz to po tym, że wszystkie faktury mają ten sam kod i podobne szczegóły. Może to być 450 albo 430 „Błąd weryfikacji pliku faktury”, opisany w tekście o błędzie 430 w KSeF.
- Paczka wysłana drugi raz. Paczka przeszła za pierwszym razem, ale program albo człowiek wysłał ją ponownie. Każda faktura dostaje wtedy 440 „Duplikat faktury”, a sesja 445. To jedyny przypadek, w którym faktur nie wysyłasz jeszcze raz, bo już są w KSeF. Szczegóły w tekście o błędzie 440 w KSeF.
- Błąd szyfrowania w programie. Faktury mają 435 „Błąd odszyfrowania pliku”. Faktury szyfruje program wysyłający, więc problem zwykle leży w nim, a nie w treści faktur.
- Uprawnienia lub załącznik. Faktury mają 410 „Nieprawidłowy zakres uprawnień” albo 415 „Brak możliwości wysyłania faktury z załącznikiem”. Poprawianie kwot tu nie pomoże. Te kody wskazują na uprawnienia albo na załącznik w fakturze.
- Błąd po stronie KSeF. Faktury mają 500 „Nieznany błąd” albo 550 „Operacja została anulowana przez system”. Dla 550 MF podaje w szczegółach wprost: „Spróbuj ponownie”.
Co zrobić krok po kroku
- Zapisz numer referencyjny sesji. Przyda się w programie, w rozmowie z dostawcą programu i ewentualnie w zgłoszeniu do MF.
- Otwórz listę faktur tej sesji. W programie jest to zwykle historia wysyłek albo log wysyłki. Jeżeli program pokazuje tylko status sesji, poproś jego dostawcę o statusy poszczególnych faktur.
- Przeczytaj kod i szczegóły przy każdej fakturze. Opis to krótkie zdanie, a konkret bywa dopiero w szczegółach.
- Pogrupuj faktury po kodach. Jeżeli wszystkie mają ten sam kod, szukasz jednego błędu w programie lub szablonie, a nie kilkudziesięciu błędów w fakturach.
- Odłóż faktury z kodem 440. Zwykle są już w KSeF, ale numer mógł też zająć inny dokument. Sprawdź to według tekstu o błędzie 440 w KSeF. Ponowna wysyłka nic nie da, a zmiana numeru przed sprawdzeniem oryginału mogłaby utworzyć drugą fakturę.
- Popraw pozostałe według ich kodów. 450 i 430 to treść lub plik faktury. 435 to zwykle program wysyłający. 500 i 550 to strona KSeF.
- Wyślij poprawione faktury w nowej sesji. KSeF nie przyjmuje faktur do sesji, której status na to nie pozwala. Odpowiada wtedy błędem 21180 „Status sesji nie pozwala na wykonanie operacji”.
- Przy dużej paczce zacznij od jednej faktury. Wyślij jedną poprawioną fakturę i sprawdź, czy przechodzi. Dopiero potem wyślij resztę.
Kiedy pisać do MF? Jeżeli faktury dostają 500 „Nieznany błąd” także w kolejnych, nowych sesjach, zgłoś sprawę przez formularz MF albo na adres jpk.helpdesk@mf.gov.pl. Podaj numery referencyjne sesji i godziny wysyłki. Kody 450, 430, 435 i 440 wskazują na fakturę albo na program, więc zgłoszenie do MF zwykle tu nie pomoże.
Dla programistów. Status sesji pobierzesz zapytaniem GET /sessions/{referenceNumber}. Status pojedynczej faktury pobierzesz zapytaniem GET /sessions/{referenceNumber}/invoices/{invoiceReferenceNumber}. Odpowiedź ma pola code, description, details i extensions. Nie pokazuj kodu 445 przy fakturach jako komunikatu błędu. Użytkownik potrzebuje kodu każdej faktury. Nie ponawiaj sesji automatycznie po 445, bo te same pliki dadzą ten sam wynik. Wyjątkiem są faktury z kodami 500 i 550. Faktur z kodem 440 nie ponawiaj nigdy.
Jak temu zapobiec
- Sprawdzaj faktury przed wysyłką. Część błędów treści da się wychwycić, zanim plik trafi do KSeF, na przykład walidując go ze schematem FA(3).
- Nowy szablon testuj na jednej fakturze, najlepiej najpierw w środowisku testowym KSeF.
- Patrz na statusy faktur, nie tylko sesji. Sam status sesji nie powie Ci, która faktura i dlaczego nie przeszła.
- Nie powtarzaj paczki po przerwie bez sprawdzenia. Najpierw sprawdź status poprzedniej sesji i listę przyjętych w niej faktur. Inaczej dostaniesz sesję 445 pełną duplikatów.
FakturaFlow sprawdza każdą fakturę pod kątem reguł FA(3) przed wysyłką: długości pól, niedozwolone znaki, datę wystawienia z przyszłości, format NIP i numeru VAT UE oraz zgodność netto, VAT i brutto. Wiele odrzuceń w ogóle nie dochodzi więc do KSeF. Każdy błąd KSeF pokazuje po polsku przy konkretnej fakturze, z informacją, co poprawić. Wysyła pojedyncze faktury i duże paczki, a UPO (Urzędowe Poświadczenie Odbioru) pobiera sam. Załóż konto.
Podsumowanie
Kod 445 to status sesji: KSeF nie przyjął z niej żadnej faktury. Przyczyna nie stoi przy sesji, tylko przy każdej fakturze osobno, więc zacznij od listy faktur sesji i ich kodów. Popraw faktury według tych kodów i wyślij je w nowej sesji, z wyjątkiem faktur z kodem 440, które zwykle już są w KSeF. Pozostałe kody opisuje pełna lista kodów błędów KSeF.
Stan na październik 2026 r. Opis na podstawie dokumentacji API KSeF 2.0 (wersja 2.8). Kody i komunikaty mogą się zmienić wraz z nowymi wersjami API.