Błędy KSeF XML — Jak Ich Unikać i Co Zrobić, Gdy Faktura Zostaje Odrzucona

Tablixa Blog · 2026-05-08

Błędy KSeF XML — Jak Ich Unikać i Co Zrobić, Gdy Faktura Zostaje Odrzucona

Wyślij fakturę do Krajowego Systemu e-Faktur (KSeF) i zamiast numeru KSeF otrzymasz komunikat o błędzie. Co teraz? Gdzie szukać problemu? Jak szybko go naprawić i wysłać fakturę ponownie?

Błędy walidacji KSeF to rzeczywistość, z którą zmierzy się każda firma wdrażająca e-fakturowanie. Dobra wiadomość: większość błędów jest powtarzalna, dobrze udokumentowana i stosunkowo łatwa do naprawienia — pod warunkiem że wiesz, czego szukać.

Jak KSeF Waliduje Plik FA3 XML?

Gdy wysyłasz plik FA3 XML do KSeF, system przeprowadza walidację dwuetapową:

Etap 1 — Walidacja schematu XSD: System sprawdza, czy struktura Twojego pliku XML jest zgodna ze schematem FA3. Weryfikuje kolejność elementów, typy danych, wymagane pola i dopuszczalne wartości. Błąd na tym etapie kończy się natychmiastowym odrzuceniem.

Etap 2 — Walidacja biznesowa: Jeśli plik przejdzie walidację schematu, KSeF sprawdza reguły biznesowe: spójność kwot (czy suma pozycji zgadza się z podsumowaniem), poprawność NIP (suma kontrolna), logikę dat (data sprzedaży nie może być późniejsza niż data wystawienia o więcej niż ustalony limit), itp.

Błąd na którymkolwiek etapie = brak numeru KSeF = faktura nie ma mocy prawnej.

Błąd 1: Nieprawidłowy NIP — Najczęstszy Problem

Objaw: Faktura odrzucona z komunikatem o nieprawidłowym formacie NIP lub niezgodnej sumie kontrolnej.

Przyczyna: NIP musi spełniać dwa warunki — być ciągiem dokładnie 10 cyfr (bez myślników, spacji, przedrostka "PL") oraz przejść algorytm sumy kontrolnej. Fikcyjny NIP, NIP z literówką lub NIP zagranicznego kontrahenta bez polskiego numeru zostanie odrzucony.

Jak naprawić:

<!-- Niepoprawnie -->
<NIP>123-456-78-90</NIP>
<NIP>PL1234567890</NIP>

<!-- Poprawnie -->
<NIP>1234567890</NIP>

Zweryfikuj NIP kontrahenta przez Wykaz Podatników VAT (białą listę) Ministerstwa Finansów — masz pewność, że numer jest aktywny i poprawny.

Błąd 2: Format Daty Niezgodny z ISO 8601

Objaw: cvc-datatype-valid: '07.05.2026' is not a valid value for 'date'

Przyczyna: Schema XML wymaga formatu daty RRRR-MM-DD. Polski zwyczaj zapisywania dat jako DD.MM.RRRR jest tu zupełnie niedopuszczalny.

Jak naprawić:

<!-- Niepoprawnie -->
<P_1>07.05.2026</P_1>
<P_1>7/5/2026</P_1>

<!-- Poprawnie -->
<P_1>2026-05-07</P_1>

Dotyczy wszystkich pól daty: P_1 (data wystawienia), P_6 (data sprzedaży), TerminPlatnosci (termin płatności).

Błąd 3: Niezgodność Kwot — Subtelna Pułapka

Objaw: Faktura odrzucona z komunikatem o niezgodności kwot — pomimo że wizualnie wszystko wygląda poprawnie.

Przyczyna: KSeF sprawdza matematyczną spójność kwot wewnątrz faktury. Suma wartości VAT ze wszystkich pozycji musi być identyczna (co do grosza) z polem podsumowania P_14_x. To samo dotyczy kwot netto i brutto.

Błąd pojawia się najczęściej gdy:

• obliczasz VAT jako sumę niepozaokrąglonych wartości z wielu pozycji
• zaokrąglasz kwoty "od oka" zamiast matematycznie
• wartości mają więcej niż 2 miejsca po przecinku

Jak naprawić: Obliczaj VAT dla każdej pozycji i zaokrąglaj do 2 miejsc po przecinku. Następnie sumuj już zaokrąglone wartości:

Pozycja 1: 1000,00 netto × 23% = 230,00 VAT
Pozycja 2: 333,33 netto × 23% = 76,6659 → zaokr. 76,67 VAT
Suma VAT: 230,00 + 76,67 = 306,67
P_14_1 musi wynosić: 306,67

Błąd 4: Brakujące Obowiązkowe Elementy

Objaw: cvc-complex-type.2.4.a: Invalid content was found starting with element 'X'

Przyczyna: Schemat FA3 definiuje szereg obowiązkowych elementów, które muszą być obecne. Pominięcie choćby jednego skutkuje błędem walidacji struktury.

Najczęściej pomijane pola:

• — kod waluty faktury (np. PLN)
• — numer faktury
• — suma brutto faktury
• — numer wiersza w każdej pozycji
• — sekcja podsumowania kwot

Jak naprawić: Waliduj plik względem schematu XSD przed wysyłką. Walidator wskaże dokładnie, którego elementu brakuje i na którym poziomie hierarchii.

Błąd 5: Niepoprawna Przestrzeń Nazw (Namespace)

Objaw: The prefix 'fa' is not bound lub Validation against '/Faktura' failed

Przyczyna: Element korzeniowy musi zawierać dokładną deklarację namespace FA3. Zmiana adresu URI lub użycie namespace ze starszej wersji schematu (FA lub FA(2)) skutkuje odrzuceniem.

Poprawna deklaracja:

<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">

Skopiuj ten nagłówek dosłownie — żadne modyfikacje adresów URI nie są dozwolone.

Błąd 6: Kodowanie Znaków — Polskie Litery

Objaw: An invalid XML character (Unicode: 0xXX) was found in the element content

Przyczyna: Plik XML musi być w kodowaniu UTF-8. Polskie znaki (ą, ę, ó, ś, ć, ń, ź, ż, ł) zapisane w starszych kodowaniach Windows (cp1250) lub Latin-2 są traktowane jako nieprawidłowe znaki.

Dodatkowy problem: BOM (Byte Order Mark) — niektóre edytory dodają na początku pliku UTF-8 trzybajtowy ciąg EF BB BF. KSeF interpretuje go jako nieprawidłowy znak przed .