Błędy walidacji w KSeF: najpierw XML/XSD, potem logika biznesowa

Dwie warstwy, które warto rozdzielić

Walidacja techniczna odpowiada na pytanie, czy dokument ma poprawną strukturę zgodną ze schematem XML (XSD) oraz podstawowymi regułami systemu KSeF. Walidacja biznesowa (czyli czy dane na fakturze są poprawne z punktu widzenia rozliczeń i rzeczywistej transakcji) pozostaje po stronie firmy i jej procesów.

W praktyce oznacza to, że poprawna technicznie faktura może nadal zawierać błędy merytoryczne, które KSeF nie wychwyci.

Kolejność, która upraszcza diagnozę

W pracy z błędami warto trzymać się prostej kolejności:

1. Sesja i uprawnienia – upewnij się, że problem nie dotyczy logowania, tokenu lub kontekstu (np. NIP), tylko samej faktury.
2. Zgodność z XSD – sprawdź strukturę dokumentu: obecność wymaganych pól, ich kolejność, typy danych (np. daty, liczby).
3. Reguły systemowe KSeF – weryfikacja zależności między polami i ograniczeń wynikających z logiki systemu.
4. Spójność merytoryczna – kontrola kwot, stawek VAT i zależności między wartościami (to już element kontroli wewnętrznej, nie samego KSeF).

Co daje walidacja lokalna względem XSD

Sprawdzenie pliku XML względem oficjalnego schematu XSD (np. FA(3)) pozwala wychwycić błędy jeszcze przed wysyłką do KSeF.

Najczęstsze problemy na tym etapie to:

• nieprawidłowa struktura dokumentu (np. zła kolejność elementów),
• brak wymaganych pól,
• wartości w niewłaściwym formacie (np. data, liczba),
• przekroczenie dopuszczalnej długości pola.

Dzięki temu część błędów można usunąć bez angażowania KSeF i bez oczekiwania na odpowiedź systemu.

Kiedy XSD „przechodzi”, a KSeF nadal odrzuca

Jeżeli dokument przechodzi walidację XSD, a mimo to jest odrzucany przez KSeF, przyczyna zwykle leży w:

• regułach systemowych KSeF (np. zależności między polami),
• niespójności danych,
• kontekście uprawnień lub sesji.

W takiej sytuacji warto sprawdzić szczegóły odpowiedzi z API lub komunikat w Aplikacji Podatnika – często zawiera wskazanie miejsca błędu w dokumencie.

Powiązany kąt: struktura FA(3) w API

Zmiany w schemacie i ograniczenia dotyczące plików (np. załączników) opisujemy osobno: KSeF API a struktura FA(3), XSD i załączniki