Diagnozowanie i rozwiązywanie problemów z KSeF

1. Wprowadzenie

Niniejszy dokument jest praktycznym przewodnikiem dla użytkowników systemu HermesSQL, którego celem jest szybkie diagnozowanie i skuteczne rozwiązywanie najczęściej występujących problemów i błędów związanych z obsługą Krajowego Systemu e-Faktur (KSeF). Zrozumienie prezentowanych tu rozwiązań i procedur jest kluczowe dla zapewnienia płynnej, wydajnej i zgodnej z przepisami pracy z fakturami ustrukturyzowanymi.

2. Kluczowe etapy i statusy dokumentów w procesie KSeF

Zrozumienie cyklu życia dokumentu w procesie komunikacji z Krajowym Systemem e-Faktur jest konieczne dla prawidłowej diagnozy i rozwiązywania problemów. Każdy status przypisany do dokumentu w systemie HermesSQL jest sygnałem o jego aktualnym stanie. Informuje on użytkownika, na jakim etapie przetwarzania znajduje się faktura i determinuje, jakie operacje można w danym momencie wykonać. Prawidłowa interpretacja tych statusów to pierwszy i najważniejszy krok w efektywnym zarządzaniu e-Fakturami.

Na listach dokumentów przeznaczonych do wysyłki do KSeF znajduje się dedykowana kolumna Etap KSeF, która informuje o bieżącym stanie dokumentu. Poniżej znajduje się wyjaśnienie poszczególnych statusów:

• Nie dotyczy – Status ten jest automatycznie nadawany dokumentom, które nie są przeznaczone do wysyłki do KSeF, takim jak paragony czy dokumenty wewnętrzne. Wynika to z ustawienia Dokument ma trafiać do KSeF na NIE w definicji danego typu dokumentu.
• W przygotowaniu – Jest to początkowy status każdego dokumentu, który ma trafić do KSeF. Oznacza, że plik XML nie został jeszcze wygenerowany ani zwalidowany.
• Zaakceptowany – Dokument został formalnie zaakceptowany do wysyłki. Z tym statusem dokument jest przenoszony do obszaru Eksport do KSeF i nie podlega już dalszej edycji.
• Wygenerowany XML – System wygenerował plik XML dla dokumentu, ale nie został on jeszcze pomyślnie zwalidowany. Taka sytuacja może wystąpić, na przykład, w przypadku braku połączenia z Internetem, które jest niezbędne do przeprowadzenia walidacji.
• Walidacja poprawna – Plik XML dokumentu został pomyślnie wygenerowany i zwalidowany pod kątem zgodności ze schematem KSeF. Dokument jest gotowy do wysyłki.
• Walidacja niepoprawna – Wygenerowany plik XML zawiera błędy i nie przeszedł walidacji. Dokument wymaga korekty danych przed ponowną próbą generowania pliku.
• Przetwarzanie – Dokument został wysłany do KSeF, ale oczekuje na weryfikację i przetworzenie po stronie serwerów Ministerstwa Finansów. Nie otrzymał jeszcze Urzędowego Poświadczenia Odbioru (UPO).
• Przyjęty w KSeF – Dokument został pomyślnie wysłany, zweryfikowany i przyjęty przez KSeF. Otrzymał UPO oraz numer identyfikacyjny KSeF.
• Odrzucony – Dokument został wysłany, lecz system KSeF go odrzucił z powodu błędów. Szczegółowe informacje o przyczynie odrzucenia są dostępne w module KSeF.

 

UWAGA!!!

W celu szybkiej identyfikacji wizualnej, status Przyjęty w KSeF jest oznaczony w systemie kolorem zielonym, natomiast Walidacja niepoprawna kolorem czerwonym.

 

Znajomość powyższych statusów jest kluczowa, ponieważ stanowi podstawę do zrozumienia komunikatów systemowych i błędów omawianych w kolejnych sekcjach.

3.Katalog najczęstszych komunikatów operacyjnych KSeF

Komunikaty operacyjne w systemie pojawiają się najczęściej w wyniku próby wykonania akcji w niewłaściwej kolejności lub na dokumencie o nieodpowiednim statusie. Są to błędy proceduralne, które wynikają z logiki procesu obsługi KSeF. Zrozumienie tych komunikatów jest kluczem do unikania prostych pomyłek i zapewnienia płynnego przepływu pracy z e-Fakturami.

1. a) Błąd wysyłki: Brak wygenerowanego pliku XML

• Opis problemu: Komunikat pojawia się podczas próby wysłania dokumentu, dla którego nie wygenerowano i nie zwalidowano pliku XML.
• Sposób postępowania:
  1. Zaznacz dokument na liście.
  2. Skorzystaj z opcji KSeF → Generuj/ Waliduj XML.
  3. Po pomyślnej walidacji ponownie wyślij dokument.

1. b) Błąd generowania XML: Dokument niezaakceptowany

• Opis problemu: System wyświetla ten komunikat, gdy użytkownik próbuje wygenerować plik XML dla dokumentu, który nie ma statusu Zaakceptowany.
• Sposób postępowania:
  1. Zaakceptuj dokument do wysyłki do KSeF.
  2. Ponownie uruchom proces generowania pliku XML.

1. c) Błąd wysyłki: Brak akceptacji i brak pliku XML

• Opis problemu: Ten komunikat jest wyświetlany przy próbie wysyłki dokumentu, który nie został zaakceptowany i jednocześnie nie posiada wygenerowanego pliku XML.
• Sposób postępowania:
  1. Zaakceptuj dokument do KSeF.
  2. Wygeneruj i zwaliduj plik XML.
  3. Ponownie wyślij dokument.

1. d) Błąd podglądu XML: Plik nie został wygenerowany

• Opis problemu: Komunikat pojawia się, gdy użytkownik próbuje podejrzeć plik XML, który jeszcze nie został utworzony.
• Sposób postępowania:
  1. Aby uzyskać podgląd, najpierw wygeneruj plik za pomocą opcji KSeF → Generuj/ Waliduj XML.

1. e) Błąd podglądu UPO: Urzędowe Poświadczenie Odbioru nie zostało pobrane

• Opis problemu: Komunikat pojawia się przy próbie podglądu UPO dla dokumentu, dla którego poświadczenie nie zostało jeszcze pobrane (kolumna UPO ma wartość NIE).
• Sposób postępowania:
  1. Upewnij się, że dokument ma status Przyjęty w KSeF.
  2. Jeśli nie, wyślij go i pobierz status.
  3. Gdy dokument zostanie przyjęty, użyj opcji KSeF → Pobierz UPO.

1. f) Błąd pobierania UPO: Dokument nie został wysłany

• Opis problemu: System informuje, że nie można pobrać UPO, ponieważ dokument nie został jeszcze wysłany do KSeF.
• Sposób postępowania:
  1. Wyślij dokument do KSeF.
  2. Pobierz jego aktualny status.
  3. Gdy status zmieni się na Przyjęty w KSeF, pobierz UPO.

1. g) Błąd pobierania statusu: Dokument nie został wysłany

• Opis problemu: Komunikat pojawia się, gdy użytkownik próbuje pobrać status KSeF dla dokumentu, który fizycznie nie opuścił jeszcze systemu.
• Sposób postępowania:
  1. Najpierw wyślij dokument do KSeF.
  2. Dopiero po wysłaniu pobierz jego status.

1. h) Błąd podglądu konfiguracji: Plik XML nie został wygenerowany

• Opis problemu: Komunikat pojawia się przy próbie podglądu konfiguracji schematu dla dokumentu, który nie ma jeszcze wygenerowanego pliku XML.
• Sposób postępowania:
  1. Przed uruchomieniem podglądu konfiguracji, wygeneruj plik XML za pomocą opcji KSeF → Generuj/ Waliduj XML.

1. i) Błąd generowania XML: Dokument już wysłany do KSeF

• Opis problemu: System blokuje próbę ponownego wygenerowania pliku XML dla dokumentu, który został już wcześniej wysłany do KSeF.
• Przyczyna: Dokument znajduje się już w bazie KSeF, dlatego nie można go modyfikować ani ponownie generować pliku XML.
• Sposób postępowania:
  1. W przypadku konieczności wprowadzenia zmian w dokumencie należy wystawić fakturę korygującą. Oryginalny dokument nie podlega edycji po wysłaniu.

1. j) Błąd wysyłki: Dokument już przyjęty w KSeF

• Opis problemu: Komunikat pojawia się przy próbie ponownej wysyłki dokumentu, który ma status Przetwarzanie.
• Przyczyna: Dokument został już wysłany i oczekuje na przetworzenie przez KSeF. System blokuje ponowną wysyłkę, aby uniknąć duplikatów i błędów komunikacji.
• Sposób postępowania:
  1. Nie wysyłaj dokumentu ponownie. Należy poczekać na zakończenie przetwarzania i zmianę statusu.

1. m) Błąd pobierania UPO: Dokument niezaakceptowany przez KSeF

• Opis problemu: System wyświetla błąd podczas próby pobrania UPO, gdy dokument wciąż jest przetwarzany przez KSeF.
• Przyczyna: Błąd wynika z faktu, że nie pobrano wcześniej aktualnego statusu lub dokument nadal jest w trakcie weryfikacji po stronie Ministerstwa Finansów.
• Sposób postępowania:
  1. Najpierw pobierz aktualny status dokumentu.
  2. Spróbuj ponownie pobrać UPO.
  3. Jeśli status wciąż wskazuje na przetwarzanie, należy odczekać na zakończenie tego procesu przez Ministerstwo Finansów.

 

O ile błędy operacyjne wynikają z nieprawidłowej kolejności działań, o tyle błędy walidacji, omówione w następnej sekcji, dotyczą poprawności samych danych na fakturze.

 

4.Katalog typowych błędów walidacji XML

Błędy walidacji pojawiają się w momencie, gdy dane wprowadzone w systemie nie spełniają formalnych wymogów struktury logicznej FA (3), która jest narzucona przez Ministerstwo Finansów. Oznacza to, że informacje na fakturze (np. format NIP, brak adresu) są niezgodne z oficjalnym schematem, co uniemożliwia poprawne wygenerowanie pliku XML i w konsekwencji wysłanie go do KSeF.

1. a) Błąd walidacji: Nieprawidłowy numer NIP

• Komunikat błędu:

• Analiza problemu: System wykrył, że numer NIP w dokumencie (w tym przypadku ‘125830067’) jest niezgodny z wymaganym formatem. Zgodnie ze schemą KSeF, numer NIP musi składać się dokładnie z 10 cyfr. Nie może zawierać spacji, liter ani innych znaków specjalnych. W podanym przykładzie numer ma tylko 9 cyfr, co narusza regułę walidacji.
• Sugerowane rozwiązanie:
  1. Sprawdź poprawność numeru NIP zarówno w danych sprzedawcy, jak i nabywcy na dokumencie.
  2. Upewnij się, że numer zawiera dokładnie 10 cyfr i jest zgodny z rzeczywistym NIP podmiotu.
  3. Wycofaj akceptację dla dokumentu.
  4. Popraw błędne dane w kartotece kontrahenta lub w danych firmy.
  5. Ponownie zaakceptuj dokument, wygeneruj plik XML i spróbuj wysłać go do KSeF.

1. b) Błąd walidacji: Brak wartości w polu adresu (AdresL1)

• Komunikat błędu:

• Analiza problemu: Komunikat informuje, że pole AdresL1 (pierwsza linia adresu) jest puste. Zgodnie ze schematem KSeF, to pole jest obowiązkowe i musi zawierać co najmniej 1 znak. Błąd najczęściej wynika z braku uzupełnionego adresu w danych kontrahenta (nabywcy, odbiorcy) lub w danych podatkowych firmy (sprzedawcy).
• Sugerowane rozwiązanie:
  1. Zidentyfikuj, którego podmiotu (sprzedawcy czy nabywcy) dotyczy błąd i sprawdź jego dane w systemie.
  2. Upewnij się, że wszystkie wymagane pola adresowe są prawidłowo uzupełnione.
  3. Wprowadź brakujące dane, a następnie wycofaj akceptację dokumentu do KSeF.
  4. Ponownie zaakceptuj dokument i wygeneruj plik XML.

Najlepszym sposobem radzenia sobie z błędami jest zapobieganie im, co można osiągnąć poprzez staranną i kompletną konfigurację systemu, omówioną w ostatniej sekcji.

 

 

5.Dobre praktyki konfiguracyjne zapobiegające błędom

Większość błędów walidacyjnych i operacyjnych ma swoje źródło w niekompletnej lub nieprawidłowej konfiguracji danych w systemie. Dbałość o poprawność ustawień jest podstawą bezproblemowej komunikacji z KSeF. Poniższa sekcja przedstawia kluczowe obszary konfiguracyjne, na które należy zwrócić szczególną uwagę, aby zminimalizować ryzyko wystąpienia błędów.

 

Konfiguracja definicji dokumentów

Kluczowym parametrem jest tu opcja Dokument ma trafiać do KSeF. Musi być ona ustawiona na TAK dla wszystkich rejestrów faktur i korekt sprzedaży, które podlegają obowiązkowi wysyłki.

Nieprawidłowe ustawienie tego parametru jest bezpośrednią przyczyną błędu opisanego w punkcie 2.k – Rejestr nieobsługiwany w KSeF.

 

Uzupełnianie danych kontrahenta

Dane kontrahenta są źródłem informacji dla sekcji Podmiot2 (nabywca) i Podmiot3 (inne podmioty) w pliku XML.

• Adres: Należy bezwzględnie dopilnować, aby pola adresowe (AdresL1 i AdresL2) w kartotece kontrahenta były kompletnie wypełnione. Puste pole adresu jest przyczyną błędu walidacji opisanego w punkcie 3.b. – Brak wartości w polu adresu (AdresL1)
• Numer NIP: Poprawność numeru NIP (dokładnie 10 cyfr) jest krytyczna. Błędny format NIP prowadzi bezpośrednio do błędu walidacji z punktu 3.a. – Nieprawidłowy numer NIP

Mapowanie form płatności

Każda forma płatności używana w systemie musi być poprawnie zmapowana na jeden z rodzajów wymaganych przez schemat KSeF. Po aktualizacji systemu, fabryczne formy płatności zostaną przypisane automatycznie:

• G – gotówka
• P – przelew
• K – karta

Wszystkie inne, niefabryczne formy płatności należy zmapować ręcznie w konfiguracji.

 

Ustawienia globalne

W menu Konfiguracja → Ustawienia globalne znajduje się kluczowy parametr Obsługa KSeF od. Należy w nim wskazać datę, od której system ma aktywować funkcjonalności związane z KSeF. Pozostawienie tego pola pustego (Nie wybrano) spowoduje, że mechanizmy akceptacji i wysyłki dokumentów do KSeF nie będą dostępne.