Rozwiązywanie problemów

Link to English Version

Gdzie szukać szczegółów błędów, typowe problemy i ich rozwiązania, oraz gdzie uzyskać pomoc.

Gdzie szukać błędów

Zakładka KSeF na poszczególnych fakturach - każda wysłana faktura ma zakładkę KSeF z pełną historią wysyłek - każda próba ze znacznikiem czasu, statusem, kodem błędu i opisem. Jeśli wysyłka się nie powiodła lub została odrzucona, to pierwsze miejsce do sprawdzenia. Szczegóły błędu dotyczą konkretnie tej faktury. Powiedzą Ci dokładnie, co poszło nie tak - problem z walidacją XML, błąd uwierzytelniania, zduplikowany numer itd.

Strona statusu - strona statusu (dostępna z menu KSeF) pokazuje wysyłki ze wszystkich faktur. Jest szczególnie przydatna do wychwytywania wzorców - sekcja "częste błędy" agreguje najczęstsze kody błędów z ostatnich 30 dni. Jeśli ten sam błąd pojawia się na wielu fakturach, to prawie na pewno problem konfiguracyjny. Napraw konfigurację, a błędy znikną. Więcej o stronie statusu w Automatyzacja i dodatkowe funkcje.

Logi Dolibarr i logi PHP - do głębszego debugowania logi systemowe Dolibarr lub logi PHP mogą zawierać dodatkowe szczegóły - szczególnie dla problemów na poziomie połączenia, niepowodzeń migracji lub nieoczekiwanych błędów PHP. Sprawdź katalog logów Dolibarr lub pobierz je z modułu Debug Logs, jeśli jest włączony.

Strona "O module" - sprawdzanie wymagań systemowych - strona "O module" (w zakładkach konfiguracji KSeF) zawiera tabelę diagnostyczną, która sprawdza każdą zależność i pokazuje zielony/czerwony status: wersję PHP, OpenSSL, cURL, DOM, mbstring, JSON i Zip, bibliotekę phpseclib, TCPDF z obsługą kodów 2D, moduły Kody kreskowe i Wielowalutowość, konfigurację NIP, status uwierzytelniania (z datami wygaśnięcia certyfikatów, jeśli dotyczy), status certyfikatu offline, aktualne środowisko i ochronę CSRF. Jeśli coś nie działa, ta strona pomoże potwierdzić, że przynajmniej podstawy są poprawne.

Typowe problemy

Nieudane uwierzytelnianie

Objawy: błędy HTTP 403, komunikaty "uwierzytelnianie nie powiodło się", wysyłki natychmiast odrzucane.

Najprawdopodobniejsza przyczyna: brakujące uprawnienia. To najczęstszy problem. Twój token lub certyfikat może być całkowicie prawidłowy do logowania w portalu KSeF, ale to nie oznacza, że ma uprawnienia do wysyłania lub odbierania faktur.

Rozwiązanie: zaloguj się do portalu KSeF dla swojego środowiska, przejdź do "Uprawnienia" i zweryfikuj, że Twoje poświadczenia mają jawne uprawnienia do wysyłania i pobierania faktur. To musi być skonfigurowane oddzielnie od uwierzytelniania - nie jest automatyczne.

Inne przyczyny:
Token lub certyfikat wygasł - sprawdź datę ważności na stronie "O module"
Złe środowisko - poświadczenia testowe wobec API demo lub produkcyjnego, lub odwrotnie

Zduplikowany numer faktury (Błąd 440)

Objawy: wysyłka odrzucona z kodem błędu 440, komunikat o zduplikowanym numerze faktury.

Przyczyna: faktura o tym numerze już istnieje w KSeF dla Twojego NIP. Zdarza się to często w środowiskach Test i Demo, ponieważ dane utrzymują się między sesjami - jeśli wczoraj wysłałeś "FV/2026/001", nie możesz wysłać tego samego numeru dzisiaj.

Rozwiązanie: zmień numer faktury w Dolibarr i spróbuj ponownie. Na produkcji zdarza się to rzadko, ponieważ sekwencja numeracji naturalnie generuje unikalne numery, ale może się zdarzyć przy resetowaniu numeracji lub przywracaniu z kopii zapasowej.

Brak kursu NBP

Objawy: przycisk wysyłki KSeF jest wyłączony lub wyszarzony na fakturze walutowej. Pojawia się komunikat o brakującym kursie wymiany.

Przyczyna: faktury walutowe wymagają kursu NBP przed wysyłką, a nie został on jeszcze pobrany.

Rozwiązanie: kliknij przycisk na stronie faktury, aby pobrać kurs NBP. Moduł odpytuje API NBP o kurs z ostatniego dnia roboczego przed datą faktury. Po pobraniu przycisk wysyłki staje się aktywny. Jeśli API NBP jest tymczasowo niedostępne, spróbuj później - tabele kursów są zwykle publikowane do wczesnego popołudnia w dni robocze. Więcej o obsłudze walut obcych w Wysyłanie faktur.

Timeout połączenia

Objawy: wysyłka wydaje się zawieszać, a następnie kończy się błędem timeout.

Przyczyna: API KSeF nie odpowiedziało na czas. Może się to zdarzyć w okresach dużego ruchu lub podczas okien konserwacyjnych. Sprawdź baner statusu KSeF na stronie indeksowej lub stronie faktury - jeśli pokazuje awarię lub zaplanowaną konserwację, to jest odpowiedź.

Błędy walidacji XML

Objawy: wysyłka odrzucona z błędem walidacji, ale KSeF nie mówi, które pole zawiodło.

Przyczyna: wygenerowany XML FA(3) nie jest zgodny ze schematem KSeF. Może się to zdarzyć przy nietypowych konfiguracjach faktur, brakujących wymaganych polach lub przypadkach brzegowych, których generator FA(3) jeszcze nie obsługuje.

Kroki debugowania:
1. Pobierz wysłany XML z zakładki KSeF na fakturze
2. Pobierz schemat FA(3) (schemat_FA(3)_v1-0E.xsd) z dokumentacji KSeF na GitHubie
3. Zwaliduj XML względem schematu narzędziem xmllint - w terminalu uruchom komendę xmllint --schema "schemat_FA(3)_v1-0E.xsd" twoja_faktura.xml
4. Narzędzie wskaże dokładnie, który element lub atrybut zawiódł

Najczęstszy problem to brakujący lub nieprawidłowy NIP nabywcy lub nieprawidłowe kody GTIN (opcja GTIN włączona, ale kody kreskowe nie są prawidłowymi kodami GTIN/EAN).

Synchronizacja przychodzących zwraca HTTP 403

Objawy: kliknięcie "Synchronizuj z KSeF" kończy się błędem HTTP 403.

Przyczyna: tak samo jak błędy uwierzytelniania przy wysyłaniu - Twoje poświadczenia nie mają uprawnień do pobierania.

Rozwiązanie: sprawdź "Uprawnienia" w portalu KSeF i upewnij się, że uprawnienia do pobierania/odbierania są skonfigurowane. To był pierwszy problem zgłoszony przez użytkownika ze społeczności i rozwiązanie jest zawsze takie samo.

Nie można zaimportować faktury korygującej

Objawy: próba importu faktury korygującej pokazuje błąd blokujący dotyczący oryginalnej faktury.

Przyczyna: moduł wymaga najpierw zaimportowania oryginalnej faktury, aby korekta mogła być z nią powiązana w Dolibarr.

Rozwiązanie: zaimportuj najpierw oryginalną fakturę, a potem korektę. Komunikat blokujący mówi, która faktura jest potrzebna. Jeśli korekta odwołuje się do własnego numeru KSeF zamiast numeru oryginału (częsty błąd danych u niektórych dostawców), moduł ostrzega. W takim przypadku korekta nie może być automatycznie powiązana - może być konieczne ręczne obsłużenie powiązania. Więcej o imporcie korekt w Odbieranie i import faktur.

Faktura utknęła w stanie Oczekująca

Objawy: faktura została wysłana, ale status nigdy nie zmienia się z Oczekująca.

Przyczyna: sprawdzanie statusu jeszcze nie nastąpiło lub odpowiedź z KSeF została utracona.

Rozwiązanie: jeśli zaplanowane zadanie "Sprawdź status wysyłki" jest skonfigurowane, obsłuży to automatycznie. W przeciwnym razie sprawdź portal KSeF bezpośrednio, używając numeru referencyjnego z zakładki KSeF. Jeśli portal pokazuje fakturę jako zaakceptowaną, moduł potrzebuje tylko odświeżenia statusu - zadanie cron lub ręczne sprawdzenie powinno to rozwiązać.

Synchronizacja przychodzących się zawiesiła

Objawy: "Synchronizuj z KSeF" pokazuje spinner, który nigdy się nie kończy, lub zawsze wyświetla "już w trakcie", mimo że synchronizacja nie uruchamiała się ostatnio.

Przyczyna: poprzednia synchronizacja została przerwana (restart serwera, timeout PHP, awaria sieci) i stan synchronizacji utknął.

Rozwiązanie: na liście faktur przychodzących, gdy synchronizacja się nie powiedzie, pojawia się specjalny przycisk "Reset" do wyczyszczenia zablokowanego stanu pobierania. Jeśli to nie pomoże, jest akcja "Resetuj stan synchronizacji" tylko dla administratorów, która całkowicie resetuje znacznik synchronizacji. Powoduje to ponowne sprawdzenie pełnego zakresu dat przy następnej synchronizacji, ale nie tworzy duplikatów, ponieważ moduł pomija już pobrane faktury.

Limitowanie zapytań (HTTP 429)

Objawy: synchronizacja lub wysyłka kończy się błędem limitowania zapytań, lub synchronizacja znacząco zwalnia.

Przyczyna: API KSeF ogranicza liczbę zapytań w danym oknie czasowym. Najczęściej podczas dużych synchronizacji przychodzących, szczególnie pierwszej, gdy pobierane są miesiące historii.

Rozwiązanie: moduł obsługuje to automatycznie - śledzi okres ochładzania i wznawia przy następnym zaplanowanym uruchomieniu. Jeśli uruchamiasz synchronizację ręcznie, poczekaj kilka minut i spróbuj ponownie. Podział na okna 60-dniowe jest specjalnie zaprojektowany, aby zmniejszyć ryzyko przekroczenia limitów.

Uzyskiwanie pomocy

Strona "O module" - przy zgłaszaniu problemów strona "O module" to Twój najlepszy przyjaciel. Pokazuje wersję modułu, wszystkie wymagania systemowe z ich statusem i aktualny stan konfiguracji.

GitHub Issues - dla błędów, nieoczekiwanego zachowania lub propozycji funkcji, otwórz zgłoszenie w repozytorium GitHub. Dołącz:
Wersję Dolibarr i modułu KSeF (obie na stronie "O module")
Środowisko, którego używasz (Test/Demo/Produkcja)
Kod błędu i komunikat z zakładki KSeF
Kroki do odtworzenia problemu

Forum Dolibarr - moduł ma wątek dyskusyjny na forum społeczności Dolibarr. Dobre miejsce na ogólne pytania, dyskusje o użytkowaniu i kontakt z innymi użytkownikami.

CIRFMF ksef-docs - dla pytań na poziomie API lub problemów z samym systemem KSeF (w przeciwieństwie do modułu Dolibarr), repozytorium CIRFMF ksef-docs na GitHubie to techniczna referencyjna dokumentacja utrzymywana przez zespół techniczny Ministerstwa Finansów.