Baza wiedzy
Baza błędów KSeF i FA(3)
Krótkie wyjaśnienia częstych odpowiedzi KSeF i problemów walidacji FA(3). Zacznij od komunikatu, zrozum prawdopodobne źródło, popraw dane albo system źródłowy i wykonaj sprawdzenie ponownie.
01
Najczęstsze problemy po wysyłce do KSeF
Status dokumentu, numer KSeF, UPO, duplikaty i rozjazd między KSeF a ERP.
Przewodnik · KSeF API / status
Faktura wysłana do KSeF, ale brak numeru KSeF albo UPO
Dokument został przekazany do KSeF, ale numer KSeF albo UPO nie są jeszcze dostępne.
Przewodnik · KSeF API / status
Faktura w trakcie przetwarzania w KSeF — co to znaczy
Status przetwarzania nie musi oznaczać błędu, ale wymaga świadomej kontroli i dalszej diagnostyki.
Przewodnik · KSeF API / status
Brak UPO w KSeF — jak diagnozować problem
Sam brak UPO nie przesądza jeszcze, czy problem dotyczy wysyłki, pobrania potwierdzenia czy synchronizacji statusu.
Przewodnik · ERP / synchronizacja statusu
Faktura jest w KSeF, ale nie widać jej w ERP
Taki objaw zwykle wskazuje na problem integracyjny po stronie systemu lokalnego, a nie na błąd samego XML.
Przewodnik · KSeF API / status
Ponowna wysyłka faktury do KSeF kończy się duplikatem
Kolejna wysyłka nie rozwiązuje problemu, jeżeli poprzednia próba została już przyjęta albo utknęła bez prawidłowego odtworzenia statusu.
440 · KSeF API / deduplikacja
Duplikat faktury: kod 440
KSeF odrzucił dokument jako duplikat, a system nie przyjął ponownej próby wysyłki.
02
Autoryzacja, tokeny i środowiska
Błędy dostępu, pomylone środowiska, certyfikaty i zakres uprawnień.
Przewodnik · Autoryzacja KSeF
Token, certyfikat i środowisko — błąd autoryzacji KSeF
Błąd autoryzacji nie musi oznaczać problemu z samą fakturą. Często wynika z konfiguracji tokenu, certyfikatu albo uprawnień.
Przewodnik · Autoryzacja KSeF
Token z demo, testu lub produkcji — pomylone środowisko KSeF
Jeżeli środowiska są pomylone, poprawny dokument i poprawny token nie będą działały razem.
Przewodnik · Autoryzacja KSeF
Błąd 403 w KSeF — brak uprawnień do operacji
Kod 403 zwykle oznacza problem z dostępem, a nie z treścią faktury.
03
XML, XSD i techniczna diagnostyka
Kodowanie, prolog XML, rozjazd lokalnej walidacji i zachowania API KSeF.
Przewodnik · Walidacja XML / kodowanie
XML: błąd kodowania, prologu UTF-8 i białych znaków
Tego typu problemy są częste i podstępne: komunikat wygląda na merytoryczny, a źródło błędu okazuje się czysto techniczne.
Przewodnik · Walidacja FA(3)
Przechodzi lokalną XSD, a KSeF nadal odrzuca — jak szukać rozjazdu
XSD to baza, ale nie pełny obraz. KSeF wykonuje dodatkowe walidacje semantyczne i biznesowe, które potrafią zatrzymać poprawnie wyglądający lokalnie XML.
Przewodnik · Walidacja XML / kodowanie
FA(3): lokalna walidacja przechodzi, ale API KSeF nadal odrzuca XML
To techniczny wariant rozjazdu między lokalną walidacją i zachowaniem API KSeF.
04
Korekty po przyjęciu faktury
Jak postępować, gdy dokument został już przyjęty do KSeF, ale wymaga naprawy.
Przewodnik · KSeF / cykl życia dokumentu
Faktura została przyjęta do KSeF — jak poprawić błąd bez edycji dokumentu
Po przyjęciu dokumentu przez KSeF jego treść nie podlega już zmianie. Dalsze działania prowadzi się przez właściwy dokument korygujący.
Przewodnik · KSeF / cykl życia dokumentu
Błędny NIP nabywcy w KSeF po przyjęciu faktury
To jeden z najbardziej wrażliwych błędów biznesowych po przyjęciu faktury przez KSeF.
05
Kody i reguły walidacyjne
Konkretne kody i reguły FA(3), XSD oraz kontroli merytorycznych wykrywanych przez GoKSeF.
450 · KSeF API / semantyka
KSeF błąd 450: błąd weryfikacji semantyki faktury
Kod 450 jest ogólnym komunikatem odrzucenia semantycznego po stronie KSeF. Nie wskazuje jednej stałej przyczyny, dlatego diagnozę trzeba zacząć od danych, które najczęściej psują semantykę faktury.
P_7 · XSD
P_7 jest za długie: nazwa towaru lub usługi
Ten błąd oznacza, że wartość w polu P_7 przekracza limit schematu FA(3). P_7 powinno zawierać krótką nazwę albo rodzaj towaru lub usługi, a nie długi opis techniczny.
SEM-024 · Semantyka FA(3)
Numer VAT-UE zawiera zdublowany prefiks kraju
W FA(3) prefiks kraju i numer VAT-UE są rozdzielone. Jeżeli KodUE=DE, to NrVatUE nie powinno zaczynać się od DE.
SEM-020 · Semantyka FA(3)
Brakuje daty sprzedaży P_6 albo ma zły format
Pole P_6 opisuje datę dokonania lub zakończenia dostawy towarów albo wykonania usługi. Walidator oczekuje formatu RRRR-MM-DD.
BUS-018 · Sprawdzenie merytoryczne
Suma pozycji nie zgadza się z podsumowaniem VAT
Dokument może być poprawnym XML-em, ale wewnętrznie niespójnym: pozycje mówią jedno, a podsumowanie VAT pokazuje inną sumę.
BUS-012 · Sprawdzenie merytoryczne
Stawka VAT z pozycji nie ma odpowiedniego pola w podsumowaniu
Pozycje faktury i podsumowanie VAT muszą opisywać te same stawki. Jeżeli w wierszach występuje stawka, suma dla tej stawki powinna trafić do właściwego pola podsumowania.
BUS-013 · Sprawdzenie merytoryczne
Faktura w walucie obcej bez kursu wymiany
Jeżeli faktura jest w walucie innej niż PLN i zawiera sprzedaż opodatkowaną VAT, system źródłowy powinien prawidłowo przekazać kurs waluty.
Sprawdź własny XML
Jeżeli masz plik z podobnym komunikatem po sprawdzeniu XML, zweryfikuj go w GoKSeF i odczytaj w raporcie linię, pole oraz podpowiedź naprawy.