Najczęstsze problemy z KSeF i jak je rozwiązać

KSeF działa — ale nie zawsze tak, jak byś chciał. Faktura odrzucona bez jasnego komunikatu, token, który wygasł w najgorszym momencie, system, który nie odpowiada w piątek o 16:00. To problemy, z którymi mierzą się firmy korzystające z KSeF — zarówno te doświadczone, jak i te, które dopiero zaczynają. W tym artykule zebrałem najczęstsze problemy i konkretne rozwiązania — żebyś nie musiał szukać odpowiedzi metodą prób i błędów.

Problem 1: Faktura odrzucona przez KSeF

Najczęstszy problem, z którym spotykają się firmy. Wysyłasz fakturę do KSeF, a system zwraca błąd — faktura nie otrzymuje numeru, nie jest doręczona nabywcy, nie istnieje w obiegu. Przyczyn może być kilka.

Najczęstsze przyczyny odrzucenia

• Brakujące pole wymagane — schemat FA(2) wymaga określonych pól. Brak jednego z nich (np. kodu kraju, daty wystawienia) powoduje odrzucenie.
• Nieprawidłowy format danych — data w złym formacie (DD-MM-RRRR zamiast RRRR-MM-DD), NIP z myślnikami, kwota z niewłaściwym separatorem dziesiętnym.
• Niespójność sum — suma wartości netto pozycji nie zgadza się z łączną kwotą netto. Suma VAT per stawka nie zgadza się z łącznym VAT.
• Niedozwolone znaki — znaki specjalne (&, <, >) w nazwach towarów lub firm, które "łamią" strukturę XML.
• Nieaktualny schemat — program generuje XML w starszej wersji schematu, niekompatybilnej z aktualnym KSeF.

Jak rozwiązać

1. Przeczytaj komunikat błędu — KSeF zwraca informację, które pole jest nieprawidłowe. Komunikat może być techniczny (nazwa pola XML), ale wskazuje kierunek.
2. Sprawdź dane źródłowe — otwórz fakturę w programie księgowym i zweryfikuj pola wskazane w błędzie. Najczęściej problem tkwi w danych kontrahenta (NIP, adres) lub w pozycjach faktury (stawka VAT, kwoty).
3. Popraw i wyślij ponownie — po korekcie danych wyślij fakturę do KSeF jeszcze raz. Odrzucona faktura nie istnieje w systemie — możesz wysłać poprawioną wersję z tym samym numerem.
4. Przetestuj w środowisku demo — jeśli problem się powtarza, wyślij testową fakturę do środowiska demo KSeF i przeanalizuj odpowiedź systemu w spokoju.

Problem 2: Problemy z tokenem i uprawnieniami

Żeby wystawiać i odbierać faktury w KSeF, potrzebujesz autoryzacji — tokena, podpisu kwalifikowanego lub Profilu Zaufanego. Problemy z uprawnieniami to druga najczęstsza przyczyna blokad.

Typowe sytuacje

Problem 3: Awaria KSeF

KSeF to system informatyczny — a systemy informatyczne ulegają awariom. Platforma może być niedostępna z powodu aktualizacji, przeciążenia lub usterki technicznej. Jeśli w tym momencie musisz wystawić fakturę — masz problem.

Tryb awaryjny — co to jest i jak działa

Ministerstwo Finansów przewidziało tryb awaryjny na wypadek niedostępności KSeF. W trybie awaryjnym wystawiasz fakturę poza systemem (offline) i przesyłasz ją do KSeF po przywróceniu działania.

1. Sprawdź status KSeF — Ministerstwo informuje o planowanych i nieplanowanych przerwach. Sprawdź oficjalną stronę statusu systemu.
2. Wystawiasz fakturę offline — Twój program księgowy generuje fakturę w formacie XML, ale nie wysyła jej do KSeF. Faktura jest oznaczona jako "wystawiona w trybie awaryjnym".
3. Doręcz fakturę nabywcy alternatywnie — wyślij wizualizację PDF e-mailem lub innym kanałem. Poinformuj kontrahenta, że faktura zostanie przesłana do KSeF po przywróceniu systemu.
4. Prześlij do KSeF po przywróceniu — gdy KSeF wróci, wyślij fakturę do systemu. KSeF nada jej numer i oficjalnie ją zarejestruje.

Jak przygotować się na awarie

• Ustal w firmie procedurę awaryjną — kto decyduje o przejściu na tryb offline, kto pilnuje ponownego przesłania
• Upewnij się, że program księgowy obsługuje tryb awaryjny
• Przechowuj aktualny szablon wizualizacji PDF na wypadek konieczności wysłania faktury e-mailem
• Monitoruj oficjalną stronę statusu KSeF — planowane przerwy techniczne są z reguły ogłaszane z wyprzedzeniem

Problem 4: Rozbieżności między programem księgowym a KSeF

Zdarza się, że dane w programie księgowym nie zgadzają się z danymi w KSeF — inna kwota, inny numer, inna data. To sytuacja, która powoduje chaos w rozliczeniach i wymaga natychmiastowej reakcji.

Najczęstsze przyczyny rozbieżności

• Faktura poprawiona w programie po wysłaniu do KSeF — zmieniłeś coś w programie, ale faktura w KSeF ma starą wersję. KSeF nie aktualizuje się sam — musisz wystawić korektę.
• Błąd synchronizacji — program nie pobrał numeru KSeF lub pobrał go dla niewłaściwej faktury. Sprawdź logi synchronizacji w programie.
• Korekta niezsynchronizowana — wystawiłeś korektę w KSeF, ale program księgowy jej nie pobrał. Lub odwrotnie — korekta w programie nie poszła do KSeF.

Jak rozwiązać

Zasada numer jeden: KSeF jest źródłem prawdy. Jeśli dane w KSeF różnią się od danych w programie — to program musi się dostosować, nie KSeF. Sprawdź stan faktury w KSeF (przez aplikację webową lub API), porównaj z programem i skoryguj rozbieżności.

Problem 5: Kontrahent twierdzi, że nie widzi faktury

Wystawiłeś fakturę w KSeF, masz numer potwierdzenia — a kontrahent dzwoni i mówi, że nie widzi faktury. To frustrujące, ale zwykle łatwe do rozwiązania.

Możliwe przyczyny

• Kontrahent nie zalogował się do KSeF — faktura jest w systemie, ale kontrahent nie sprawdził swojego konta. Rozwiązanie: poinformuj go o numerze KSeF i poproś, żeby się zalogował.
• Kontrahent nie ma skonfigurowanego automatycznego pobierania — jego program księgowy nie jest zintegrowany z KSeF. Rozwiązanie: wyślij mu wizualizację PDF jako "podgląd" i poinformuj, że oryginał jest w KSeF.
• Błędny NIP nabywcy — wpisałeś nieprawidłowy NIP, więc faktura trafiła do "niewłaściwego" konta. Rozwiązanie: sprawdź NIP na fakturze, wystaw korektę z prawidłowym NIP-em.
• Faktura została odrzucona — być może myślisz, że faktura jest w KSeF, ale tak naprawdę została odrzucona. Sprawdź status w programie księgowym — czy masz potwierdzenie z numerem KSeF?

Problem 6: Problemy z fakturami korygującymi

Korekty w KSeF generują więcej problemów niż faktury pierwotne — bo wymagają precyzyjnego powiązania z dokumentem oryginalnym.

Typowe problemy

Problem 7: Wolne działanie i opóźnienia

W okresach wzmożonego ruchu (koniec miesiąca, koniec kwartału) KSeF może działać wolniej. Wysyłanie faktur trwa dłużej, pobieranie faktur zakupowych się opóźnia, a UPO (urzędowe poświadczenie odbioru) przychodzi z kilkuminutowym lub kilkunastominutowym opóźnieniem.

Jak sobie radzić

• Nie wystawiaj wszystkich faktur w ostatnim dniu miesiąca — rozłóż fakturowanie na kilka dni. To zmniejsza obciążenie i Twoje, i KSeF.
• Korzystaj z wysyłki wsadowej (batch) — zamiast wysyłać faktury pojedynczo, wyślij paczkę. Większość programów to obsługuje i jest to bardziej efektywne.
• Nie panikuj przy opóźnieniu UPO — kilkuminutowe opóźnienie w nadaniu numeru KSeF nie oznacza awarii. System przetwarza fakturę — daj mu czas.
• Planuj bufor czasowy — jeśli faktura musi być wystawiona do konkretnej daty, nie zostawiaj tego na ostatnią godzinę. Wystawiaj z wyprzedzeniem.

Problem 8: Integracja z programem księgowym nie działa

Program księgowy "nie widzi" KSeF, nie wysyła faktur lub nie pobiera zakupowych. To problem po stronie oprogramowania, nie po stronie KSeF.

Typowe przyczyny i rozwiązania

• Nieaktualna wersja programu — schemat FA(2) się zmienia, program musi nadążać. Zaktualizuj do najnowszej wersji.
• Błędna konfiguracja API — sprawdź ustawienia połączenia z KSeF w programie: adres API, dane autoryzacyjne, certyfikat. Szczegóły konfiguracji znajdziesz w dokumentacji programu lub u dostawcy.
• Firewall lub proxy blokuje połączenie — jeśli korzystasz z firewalla firmowego lub proxy, upewnij się, że adresy API KSeF są odblokowane.
• Problem po stronie dostawcy programu — skontaktuj się z supportem dostawcy. Może to być znany bug lub problem z serwerem pośredniczącym.

Więcej o integracji — w artykule o integracji KSeF z programem księgowym.

Jak zapobiegać problemom — checklista prewencyjna

Większość problemów z KSeF da się uniknąć dzięki prostym, regularnym czynnościom.

• Testuj nowe typy faktur w środowisku demo zanim wystawisz je produkcyjnie
• Aktualizuj program księgowy na bieżąco — nie odkładaj aktualizacji
• Raz na kwartał weryfikuj bazę kontrahentów (NIP-y, adresy, kody krajów)
• Monitoruj ważność tokenów autoryzacyjnych — odnawiaj z wyprzedzeniem
• Nadaj uprawnienia co najmniej dwóm osobom w firmie
• Ustal procedurę awaryjną na wypadek niedostępności KSeF
• Raz w tygodniu porównaj liczbę faktur w programie z KSeF
• Śledź komunikaty Ministerstwa Finansów o aktualizacjach schematu i planowanych przerwach

FAQ — najczęściej zadawane pytania