Walidacja faktury KSeF – XML i schemat XSD
Co musisz wiedzieć
Walidacja faktury w kontekście KSeF to sprawdzenie, czy dokument XML jest zgodny ze strukturą logiczną (schematem XSD) oraz z regułami biznesowymi systemu. Każda faktura przesłana do KSeF jest walidowana przez system; niezgodność ze schematem lub regułami powoduje odrzucenie z komunikatem błędu.
Walidacja względem schematu XSD odbywa się obowiązkowo po stronie KSeF. Dodatkowo zaleca się walidację lokalną przed wysłaniem – pozwala wcześniej wykryć błędy struktury, brakujące pola i nieprawidłowe formaty. Jeśli chcesz szybko sprawdzić gotowy plik bez wdrażania własnego walidatora, pomocna może być bezpłatna weryfikacja faktury XML KSeF. Lokalna walidacja nie zastępuje walidacji KSeF, która obejmuje także m.in. duplikaty, limity rozmiarów i szyfrowanie.
Schemat XSD określa: strukturę XML, przestrzenie nazw, pola obowiązkowe i opcjonalne, typy danych (np. daty, NIP, kwoty) oraz dozwolone wartości. Nie sprawdza natomiast reguł biznesowych KSeF (np. unikalności faktury, limitów), szyfrowania sesji ani poprawności kryptograficznej podpisu.
Najczęstsze problemy i rozwiązania
Faktura odrzucona mimo lokalnej walidacji XSD. Dlaczego?
Lokalna walidacja XSD sprawdza tylko zgodność ze schematem. KSeF wykonuje dodatkowe walidacje: reguły biznesowe (np. duplikaty numerów faktur), limity rozmiaru pliku, poprawność szyfrowania sesji, uwierzytelnienie. Sprawdź komunikat błędu z API i zobacz artykuł o błędach walidacji oraz o lokalnej walidacji przed wysyłką.
Który schemat kiedy
Do 31 stycznia 2026 r. obowiązywała struktura logiczna FA(2). Od 1 lutego 2026 r. wszystkie nowe faktury muszą być zgodne ze strukturą FA(3). Faktury korygujące wystawiane od 1 lutego 2026 r. muszą być w FA(3), nawet jeśli faktura pierwotna była w FA(2) lub FA(1). Oficjalna strona Ministerstwa Finansów: https://ksef.podatki.gov.pl/informacje-ogolne-ksef-20/struktura-logiczna-fa-3/
Co sprawdza schemat XSD
Walidacja względem XSD sprawdza: poprawność struktury XML (zagnieżdżenie i kolejność elementów), przestrzenie nazw (namespace), obecność pól obowiązkowych, typy danych (np. data w formacie zgodnym z XSD, NIP, kwoty), dozwolone wartości (np. stawek VAT), ograniczenia długości i formatów. Narzędzie walidacji XSD zwraca szczegółowe komunikaty z lokalizacją błędu.
Co sprawdza KSeF oprócz XSD
KSeF po przyjęciu dokumentu wykonuje dodatkowe walidacje: reguły biznesowe (np. unikalność numeru faktury w kontekście wystawcy, spójność sum), limity rozmiaru pliku (1 MB bez załączników, 3 MB z załącznikami w FA(3)), poprawność szyfrowania sesji (API KSeF 2.0 wymaga szyfrowania AES), uwierzytelnienie i uprawnienia. Niezgodność w którymkolwiek z tych obszarów skutkuje odrzuceniem z odpowiednim kodem błędu.
Źródła schematów i dalsze kroki
Schematy XSD FA(2) i FA(3) oraz dokumentacja są dostępne na stronie Ministerstwa Finansów (ksef.podatki.gov.pl, sekcja struktura logiczna FA(3) i pliki do pobrania KSeF 2.0) oraz w repozytorium CIRFMF/ksef-docs na GitHub (dla integratorów). Aby zwalidować fakturę lokalnie przed wysyłką, skorzystaj z instrukcji w artykule KSeF API walidacja XML – lokalna walidacja przed wysyłką albo z narzędzia takiego jak darmowy walidator XML KSeF do szybkiej kontroli pojedynczego pliku. Szczegóły struktury FA(3) znajdziesz w artykule KSeF API XSD FA3.
FAQ
Czy walidacja XSD jest obowiązkowa?
Tak. KSeF przyjmuje tylko faktury w formacie XML zgodnym z obowiązującym schematem (FA(2) lub FA(3)). Każda przesłana faktura jest walidowana przez system; niezgodność ze schematem powoduje odrzucenie. W praktyce warto dodatkowo walidować lokalnie przed wysłaniem.
Czy lokalna walidacja zastępuje walidację KSeF?
Nie. Lokalna walidacja XSD pozwala wcześniej wykryć błędy struktury i formatów, ale KSeF wykonuje dodatkowe sprawdzenia (reguły biznesowe, duplikaty, limity, szyfrowanie). Zawsze trzeba spełnić wymagania KSeF; lokalna walidacja tylko zmniejsza liczbę odrzuceń. Do szybkiego sprawdzenia technicznej zgodności pliku możesz wykorzystać walidację XML KSeF online.
Gdzie pobrać schematy XSD?
Oficjalne źródła: strona Ministerstwa Finansów (ksef.podatki.gov.pl – struktura logiczna FA(3), pliki do pobrania KSeF 2.0) oraz repozytorium CIRFMF/ksef-docs na GitHub. Używaj aktualnej wersji schematu; FA(3) obowiązuje od 1 lutego 2026 r.
Która wersja schematu obowiązuje?
Do 31 stycznia 2026 r. – FA(2). Od 1 lutego 2026 r. – wyłącznie FA(3) dla wszystkich nowych faktur. Faktury korygujące od 1 lutego 2026 r. muszą być w FA(3), niezależnie od wersji faktury pierwotnej.
Powiązane tematy
Przydatne serwisy
Status i komunikaty
API i narzędzia
Pierwsza grupa – status systemu KSeF i komunikaty techniczne Ministerstwa Finansów, druga – narzędzia do integracji z KSeF i walidacji faktur.