KSeF – błędy walidacji (co znaczą i jak je naprawić)

Błędy walidacji w KSeF oznaczają, że przesłany dokument (np. faktura XML) nie spełnia wymagań technicznych lub biznesowych. Najczęściej problem dotyczy zgodności ze schematem XSD (FA(2)/FA(3)), brakujących pól obowiązkowych, złych formatów dat/kwot lub nieprawidłowych danych identyfikacyjnych.

Co musisz wiedzieć

Błędy walidacji w KSeF oznaczają, że przesłany dokument (np. faktura XML) nie spełnia wymagań technicznych lub biznesowych. Na tej stronie znajdziesz, jak je diagnozować i naprawiać.

Typowe sytuacje: dostałeś błąd z API KSeF i nie wiesz, co poprawić w XML; faktura nie przechodzi walidacji XSD (FA(2)/FA(3)); chcesz wiedzieć, jak minimalizować błędy walidacji przed wysyłką.

Instrukcja krok po kroku

1. Sprawdź, czy błąd dotyczy XML (walidacja) czy autoryzacji/sesji

Jeśli to walidacja, zwykle zobaczysz błąd wskazujący na nieprawidłową strukturę/parametry lub brak wymaganych danych.

2. Zweryfikuj wersję schematu, której używasz

Porównaj swój XML z właściwym XSD (FA(3) ma własną stronę i pliki na stronach MF).

3. Uruchom walidację XSD lokalnie

Walidacja XSD wychwytuje: brakujące elementy, złą kolejność, zły typ danych, zły format dat/kwot, błędy namespace.

4. Popraw dane biznesowe

Po przejściu XSD popraw typowe błędy: identyfikatory (NIP), daty, kwoty, wymagane pola nagłówka/podmiotów, sumy kontrolne.

5. Przetestuj wysyłkę w środowisku testowym

Jeśli integrujesz się przez API, testuj na środowisku testowym, żeby łapać błędy walidacji bez ryzyka.

Najczęstsze problemy i rozwiązania

Niezgodność ze schematem XSD (FA(2)/FA(3))

Błąd walidacji, odrzucenie dokumentu, wskazanie elementu/ścieżki w XML. Pobierz oficjalne XSD i waliduj przed wysyłką.

Brak pól obowiązkowych

Komunikat o brakującym elemencie (minOccurs) albo brak wymaganych bloków. Uzupełnij obowiązkowe sekcje: nagłówek, podmioty, dane faktury, wymagane pola pozycji.

Złe formaty danych

Błąd typu danych (np. data, liczba), walidator XSD pokazuje "invalid value". Daty w formacie ISO (YYYY-MM-DD), poprawne typy liczbowe, ograniczenia długości i pattern.

Błędy namespace / kolejności elementów

XML wygląda poprawnie, ale XSD go odrzuca. Sprawdź przestrzenie nazw i kolejność elementów (XSD bywa restrykcyjne).

Najważniejsze wnioski

Waliduj XML lokalnie względem oficjalnego XSD zanim wyślesz dokument do KSeF. Upewnij się, że używasz właściwej wersji schematu (FA(3) jest publikowana jako docelowa struktura KSeF 2.0). W odpowiedzi API szukaj pól typu "details" / listy błędów – tam zwykle jest wskazane miejsce i powód odrzucenia.

Źródła

Wsparcie dla integratorów (KSeF 2.0), Struktura logiczna FA(3) – strona MF, Schemat XSD FA(3) – plik XSD na serwerze MF, Dokumentacja API KSeF – środowisko testowe, CIRFMF/ksef-docs – sesja interaktywna (zgodność XML z XSD), CIRFMF/ksef-docs – sesja wsadowa (FA(2)/FA(3)).

FAQ

Czy wystarczy, że mój XML przechodzi walidację XSD?

To konieczny krok, ale nie zawsze wystarczający. Po XSD mogą dojść reguły biznesowe (np. spójność sum, logika pól zależnych).

Skąd mam brać oficjalne schematy XSD?

Z oficjalnych materiałów KSeF 2.0 i publikacji struktury FA(3) (MF udostępnia pliki XSD na swoich stronach).

Gdzie szukać opisu błędów i komunikatów API?

W dokumentacji API (środowisko testowe) oraz w repozytorium CIRFMF/ksef-docs, gdzie są opisane tryby sesji i walidacje.

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.