Walidacja KSeF XML: 7 Najczęstszych Błędów i Jak Je Naprawić
Tablixa Blog · 2026-05-02
Walidacja KSeF XML: 7 Najczęstszych Błędów i Jak Je Naprawić
Wysyłka faktury do Krajowego Systemu e-Faktur (KSeF) to nie tylko kliknięcie "wyślij". System przeprowadza szczegółową walidację każdego pliku FA3 XML — i bez skrupułów odrzuca dokumenty zawierające błędy, nawet drobne. W praktyce oznacza to, że faktura nie zostanie przyjęta, a Ty musisz znaleźć problem i wysłać ją ponownie.
Na podstawie analizy tysięcy walidacji zebraliśmy 7 błędów, które pojawiają się najczęściej — z dokładnym wyjaśnieniem przyczyny i gotowym rozwiązaniem.
Błąd #1: Nieprawidłowy Format lub Suma Kontrolna NIP
Kod błędu: cvc-pattern-valid: Value 'XX...' is not facet-valid
Przyczyna: NIP musi być ciągiem 10 cyfr bez myślników, spacji ani liter. Co więcej, KSeF weryfikuje sumę kontrolną NIP algorytmem wag — fikcyjny lub błędnie przepisany NIP zostanie odrzucony.
Niepoprawnie:
<NIP>123-456-78-90</NIP>
<NIP>PL1234567890</NIP>
Poprawnie:
<NIP>1234567890</NIP>
Rozwiązanie: Usuń myślniki i przedrostki krajowe. Użyj kalkulatora sumy kontrolnej NIP, żeby zweryfikować poprawność 10-cyfrowego numeru przed umieszczeniem go w pliku.
Błąd #2: Niezgodność ze Schematem XSD (Brakujące Wymagane Elementy)
Kod błędu: cvc-complex-type.2.4.a: Invalid content was found starting with element
Przyczyna: Schemat FA3 XML ma ściśle określoną kolejność i zestaw wymaganych elementów. Brak choćby jednego obowiązkowego pola (np. DatWyst, NrFa, NrVAT) lub niepoprawna kolejność elementów skutkuje odrzuceniem.
Często brakuje:
Podmiot1→DaneIdentyfikacyjne→NIP(sprzedawca)Podmiot2→DaneIdentyfikacyjne→NIP(nabywca)Fa→FaWiersz(co najmniej jedna pozycja fakturowa)Fa→Rozliczenie(podsumowanie kwot)
Rozwiązanie: Waliduj plik lokalnie względem aktualnego schematu XSD przed wysyłką do KSeF. Schemat FA3 jest dostępny na stronie Ministerstwa Finansów. Nasz walidator KSeF XML sprawdza zgodność ze schematem automatycznie.
Błąd #3: Nieprawidłowy Format Daty
Kod błędu: cvc-datatype-valid.1.2.1: '15.03.2025' is not a valid value for 'date'
Przyczyna: XML Schema wymaga formatu daty zgodnego z ISO 8601: RRRR-MM-DD. Format polskim: 15.03.2025 nie jest akceptowany.
Niepoprawnie:
<DatWyst>15.03.2025</DatWyst>
<DatWyst>2025/03/15</DatWyst>
Poprawnie:
<DatWyst>2025-03-15</DatWyst>
Dotyczy wszystkich pól daty: daty wystawienia (DatWyst), daty sprzedaży (DatSprzed), terminu płatności (TerminPlatnosci).
Błąd #4: Nieprawidłowy Kod Stawki VAT
Kod błędu: cvc-enumeration-valid: Value 'VAT23' is not facet-valid
Przyczyna: KSeF używa ścisłego słownika dozwolonych wartości dla stawek VAT. Nie możesz wpisać "23%" ani "VAT23" — musisz użyć kodów ze specyfikacji.
Dopuszczalne wartości:
23— stawka podstawowa 23%8— stawka obniżona 8%5— stawka obniżona 5%0— stawka 0%ZW— zwolniony z VATNP— nie podlega VATOO— odwrotne obciążenie
Niepoprawnie:
<StawkaPodatku>VAT23</StawkaPodatku>
<StawkaPodatku>23%</StawkaPodatku>
Poprawnie:
<StawkaPodatku>23</StawkaPodatku>
Błąd #5: Problem z Kodowaniem Znaków (Polskie Litery)
Kod błędu: An invalid XML character (Unicode: 0xXX) was found
Przyczyna: Plik XML musi być zapisany w kodowaniu UTF-8. Polskie znaki diakrytyczne zapisane w Windows-1250 lub Latin-2 są interpretowane jako nieprawidłowe znaki Unicode.
Nagłówek XML musi zawierać:
<?xml version="1.0" encoding="UTF-8"?>
Rozwiązanie: Upewnij się, że plik jest zapisany jako UTF-8 (bez BOM — Byte Order Mark, który niektóre edytory dodają na początku pliku). Jeśli generujesz XML programowo, jawnie określ kodowanie UTF-8 przy tworzeniu strumienia wyjściowego.
Błąd #6: Niezgodność Kwot (Błędy Zaokrąglenia)
Kod błędu: Wartość pola SumaVAT niezgodna z sumą wartości podatku w wierszach
Przyczyna: KSeF sprawdza spójność kwot wewnątrz faktury. Suma wartości VAT ze wszystkich pozycji musi być równa polu SumaVAT, a suma brutto ze wszystkich pozycji musi być równa SumaBrutto. Błędy zaokrąglenia w obliczeniach na poziomie groszy powodują odrzucenie.
Przykład problemu:
- Pozycja 1: netto 100,00 × 23% VAT = 23,00, brutto 123,00
- Pozycja 2: netto 33,33 × 23% VAT = 7,6659 → zaokrąglone do 7,67, brutto 41,00
- Suma VAT z pozycji: 23,00 + 7,67 = 30,67
- Pole SumaVAT: 30,67 — musi się zgadzać co do grosza
Rozwiązanie: Obliczaj VAT dla każdej pozycji z dokładnością do 2 miejsc po przecinku zgodnie z zasadami zaokrąglania matematycznego (0,5 wzwyż). Sumę wyliczaj z już zaokrąglonych wartości pozycji, nie z sumy niezaokrąglonej.
Błąd #7: Nieprawidłowa Deklaracja Przestrzeni Nazw (Namespace)
Kod błędu: The prefix 'fa' for element 'fa:Faktura' is not bound
Przyczyna: Plik FA3 XML musi zawierać poprawną deklarację przestrzeni nazw (namespace) zgodną z aktualną wersją schematu. Brak lub błędna deklaracja xmlns skutkuje odrzuceniem na poziomie parsowania.
Poprawna deklaracja namespace dla FA3:
<Faktura xmlns="http://crd.gov.pl/wzor/2023/06/29/12648/"
xmlns:etd="http://crd.gov.pl/xml/schematy/dziedzinowe/mf/2022/01/05/eD/DefinicjeTypy/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
Rozwiązanie: Skopiuj deklarację namespace bezpośrednio z oficjalnej dokumentacji KSeF. Nie modyfikuj adresów URI — muszą być identyczne z tymi w schemacie. Sprawdź też, czy używasz aktualnej wersji schematu (FA3, nie starszego FA lub FA(2)).
Jak Szybko Sprawdzić Plik Przed Wysyłką?
Najskuteczniejsza metoda to walidacja pliku przed wysyłką do KSeF — zamiast wysyłać i czekać na komunikat o błędzie z systemu.
Tablixa oferuje walidator KSeF XML online — wgraj plik FA3 XML i w kilka sekund dowiesz się, czy jest poprawny, a jeśli nie — który element zawiera błąd i jak go naprawić.
Możesz też skorzystać z powiązanych narzędzi:
- Konwersja PDF do KSeF — automatycznie generuje poprawny plik FA3 XML z faktury PDF
- Konwersja XML KSeF do PDF — sprawdź wizualnie, jak faktura wygląda po stronie odbiorcy
- Eksport danych do Excel — wyodrębnij dane z wielu faktur do arkusza kalkulacyjnego
---
Błędy walidacji KSeF są irytujące, ale każdy z nich ma konkretną przyczynę i konkretne rozwiązanie. Znajomość tych 7 pułapek pozwoli Ci uniknąć większości odrzuceń i wysyłać faktury do KSeF bez zbędnego stresu.