Walidator faktur FA(3)

Najczęstsze błędy walidacji FA(3) i co oznaczają

Komunikaty przychodzą prosto z parsera schematu — po angielsku i z pełnymi nazwami przestrzeni nazw, więc wyglądają groźniej, niż są. Numer linii przy każdym błędzie prowadzi do miejsca w pliku.

This element is not expected. Expected is ( … )

Brakuje wymaganego pola albo pola stoją w złej kolejności — FA(3) ma ją sztywno ustaloną. Walidator wskazuje pierwsze pole, które wypadło z kolejki, więc brakującego szukaj tuż nad nim. Nawias po Expected is wymienia nazwy, których schemat spodziewał się w tym miejscu.

No matching global declaration available for the validation root.

Plik nie jest fakturą FA(3): w elemencie <Faktura> brakuje deklaracji xmlns albo wskazuje ona starszy wzór, na przykład FA(2). Poprawny adres to crd.gov.pl/wzor/2025/06/25/13775/.

[facet 'pattern'] The value '521-300-00-01' is not accepted by the pattern …

Wartość ma zły kształt. Najczęściej chodzi o NIP z myślnikami, spacjami albo skrócony do dziewięciu cyfr — w FA(3) to dziesięć cyfr pod rząd, bez separatorów.

'01.04.2026' is not a valid value of the atomic type … TDataT

Data zapisana po polsku zamiast w formacie ISO. FA(3) wymaga zapisu 2026-04-01. Ten sam komunikat dostaniesz, wpisując datę razem z godziną do pola, które przyjmuje samą datę.

'1230,00' is not a valid value of the atomic type … TKwotowy

Kwota z przecinkiem, spacją między tysiącami albo symbolem waluty. W pliku kwoty zapisuje się z kropką i bez żadnych separatorów: 1230.00.

[facet 'enumeration'] The value 'POL' is not an element of the set { … }

Wartość spoza zamkniętej listy. Kod kraju ma dwie litery (PL, nie POL), a stawka VAT to samo 23, bez znaku procenta. Klamra w komunikacie wypisuje wszystkie dozwolone wartości.

[facet 'minLength'] The value has a length of '0'

Pole zostało w pliku, ale jest puste. Nieobowiązkowe pola usuwa się w całości, zamiast zostawiać po nich pusty znacznik.

attribute 'wersjaSchemy': The value '2-0E' does not match the fixed value constraint '1-0E'

Nagłówek deklaruje inną wersję wzoru niż ta, którą walidator obsługuje. Bliźniaczy błąd na polu WariantFormularza oznacza to samo: plik jest w innej strukturze niż FA(3).

Błąd parsowania XML: Premature end of data in tag Faktura

Plik jest ucięty albo któryś znacznik został niedomknięty, więc walidator nie doszedł nawet do porównania ze schematem. Zwykle wina niepełnego pobrania lub ręcznej edycji.

Błąd parsowania XML: Unsupported encoding windows-1250

Plik zapisano w kodowaniu, którego walidator nie czyta. Zapisz go ponownie jako UTF-8 — tego kodowania wymaga też KSeF.

Jeden komunikat przychodzi z samego KSeF, nie z tego walidatora: „Schemat główny struktury logicznej FA(3) nie zawiera elementu…" i nazwa pola. Znaczy tyle, że w pliku znalazło się pole, którego wzór FA(3) w ogóle nie zna: literówka w nazwie, pole ze starszej struktury albo coś, co dopisał program wystawiający fakturę. Ten sam plik nie przejdzie też walidacji wyżej, tylko z innym komunikatem — This element is not expected.

Pełny opis narzędzia — zakładki z danymi faktury, obsługiwane typy dokumentów i limity — znajdziesz w dokumentacji: Walidator XML.

Czym różni się walidacja XSD od reguł biznesowych KSeF

Schemat XSD to gramatyka pliku. Określa, jakie pola mogą w nim wystąpić, w jakiej kolejności, jakiego typu są wartości i z jakiej listy pochodzą. Tyle sprawdza ten walidator.

Reguł biznesowych pilnuje dopiero KSeF, po odebraniu pliku. Schemat nie ma jak ich sprawdzić, bo opisuje budowę dokumentu, a nie jego treść:

• Arytmetyka. Faktura z jedną pozycją na 1000,00 zł netto i polem P_15 (należność ogółem) równym 9999,00 przechodzi walidację XSD bez ani jednego błędu. 9999.00 to poprawnie zapisana kwota, a schemat nie dodaje pozycji.
• Suma kontrolna NIP. Schemat pilnuje tylko wzorca dziesięciu cyfr. Czy taki NIP w ogóle istnieje, liczy dopiero KSeF na środowisku produkcyjnym.
• Powtórzony numer. KSeF wyłapuje duplikaty po NIP sprzedawcy, typie faktury i numerze, i pamięta je przez dziesięć lat.
• Daty. Data wystawienia nie może być późniejsza niż dzień przyjęcia dokumentu do KSeF. Dla schematu każda poprawnie zapisana data jest równie dobra.
• Kodowanie i rozmiar. KSeF wymaga UTF-8 bez BOM i przyjmuje pliki do 1 MB (3 MB z załącznikami). Walidator wyżej przepuści plik z BOM-em i akceptuje do 2 MB.

Stąd praktyczny wniosek: zielony wynik nie jest obietnicą, że KSeF przyjmie fakturę. Mówi tyle, że plik ma poprawną budowę i nie odbije się od pierwszej bramki. Powód odrzucenia zobaczysz dopiero w odpowiedzi KSeF — w KSeFce znajdziesz go w szczegółach faktury ze statusem Odrzucona.

Pytania i odpowiedzi

Czy mój plik wychodzi poza przeglądarkę?

Tak. Plik trafia na serwer KSeFki, który porównuje go ze schematem i usuwa z pamięci zaraz po odesłaniu wyniku. Nie zapisujemy go na dysku ani w bazie, a walidacja nie wymaga konta ani logowania.

Jakie wersje struktury obsługuje walidator?

Tylko FA(3) w wersji 1-0E, czyli wzór opublikowany przez Ministerstwo Finansów pod adresem crd.gov.pl/wzor/2025/06/25/13775. Plik w starszej strukturze, na przykład FA(2), dostanie komunikat o braku pasującej deklaracji dla elementu głównego — walidator nie znajdzie w schemacie elementu Faktura z tej przestrzeni nazw.

Czy walidator sprawdza, czy kwoty się zgadzają?

Nie. Schemat pilnuje formatu kwoty, ale nie sumuje pozycji. Faktura z jedną pozycją na 1000,00 zł netto i polem P_15 równym 9999,00 przechodzi walidację XSD bez ani jednego błędu.

Skąd wziąć plik XML faktury?

Pobierz go z portalu KSeF na podatki.gov.pl albo wyeksportuj z programu do fakturowania. W KSeFce kliknij fakturę prawym przyciskiem i wybierz Pobierz XML.

Co zrobić, kiedy walidacja przechodzi na zielono?

Struktura pliku jest poprawna, więc można go wysłać do KSeF. Zajrzyj jeszcze w zakładki Dane faktury i Opis pól XML — pokazują, co znalazło się w pliku, wraz z opisem ustawowym każdego pola. Zielony wynik nie jest obietnicą, że KSeF przyjmie dokument: reguł biznesowych, na przykład zgodności sum czy powtórzonego numeru, schemat nie sprawdza.

Jakie są limity walidatora?

Plik może mieć do 2 MB, a z jednego adresu IP przechodzą mniej więcej trzy sprawdzenia na minutę. Po przekroczeniu limitu zobaczysz komunikat o zbyt wielu zapytaniach — wystarczy odczekać minutę.