KSeF API walidacja XML – lokalna walidacja przed wysyłką

Lokalna walidacja faktury XML względem schematu XSD przed wysłaniem do KSeF pozwala na wczesne wykrycie błędów i uniknięcie odrzuceń przez system. Walidacja powinna być integralną częścią procesu generowania faktur.

Lokalna walidacja XML w KSeF

Walidacja faktury XML względem schematu XSD przed wysłaniem do KSeF pozwala na wczesne wykrycie błędów strukturalnych, nieprawidłowych wartości i niezgodności ze schematem.

KSeF wymaga faktur zgodnych ze schematem XSD FA(2) (do 31 stycznia 2026) lub FA(3) (od 1 lutego 2026). Lokalna walidacja przed wysłaniem zmniejsza liczbę odrzuceń i poprawia wydajność integracji.

Dostępne są różne narzędzia do walidacji XML: biblioteki programistyczne (XML Schema validatory), narzędzia wiersza poleceń (xmllint), edytory XML z walidacją oraz online validatory. Wybór narzędzia zależy od środowiska i preferencji.

Instrukcja krok po kroku

1. Pobierz schemat XSD

Pobierz aktualny schemat XSD FA(2) lub FA(3) z dokumentacji KSeF lub repozytorium GitHub CIRFMF/ksef-docs. Schematy są regularnie aktualizowane, więc upewnij się, że używasz najnowszej wersji.

2. Wybierz narzędzie walidacji

Wybierz narzędzie do walidacji XML: biblioteka programistyczna (np. .NET XmlSchemaSet, Java javax.xml.validation, Python lxml), narzędzie wiersza poleceń (xmllint), edytor XML z walidacją lub online validator. Wybór zależy od środowiska i preferencji.

3. Zweryfikuj fakturę względem XSD

Zweryfikuj wygenerowaną fakturę XML względem schematu XSD. Sprawdź strukturę XML, zgodność z definicjami typów, wymagane pola, formaty dat i wartości. Narzędzie walidacji zwróci szczegółowe błędy i ostrzeżenia.

4. Napraw błędy walidacji

Napraw wszystkie błędy walidacji przed wysłaniem faktury do KSeF. Błędy mogą dotyczyć: brakujących pól obowiązkowych, nieprawidłowych formatów dat, wartości poza dozwolonym zakresem, nieprawidłowej struktury XML. Po naprawie zweryfikuj ponownie.

5. Zweryfikuj kodowanie

Upewnij się, że faktura jest kodowana w UTF-8 bez znaku BOM. Nieprawidłowe kodowanie może powodować błędy walidacji lub przetwarzania w KSeF. Sprawdź deklarację XML () i rzeczywiste kodowanie pliku.

Najczęstsze problemy i rozwiązania

Błędy walidacji XSD

Sprawdź szczegółowe komunikaty błędów zwrócone przez narzędzie walidacji. Typowe błędy: brakujące pola obowiązkowe, nieprawidłowe formaty dat (wymagany format zgodny z XSD), wartości poza dozwolonym zakresem, nieprawidłowa struktura XML. Napraw błędy i zweryfikuj ponownie.

Różnice między lokalną walidacją a walidacją KSeF

Lokalna walidacja sprawdza zgodność ze schematem XSD, ale KSeF wykonuje dodatkowe walidacje biznesowe (np. sprawdzanie duplikatów, limity rozmiarów, weryfikacja szyfrowania). Lokalna walidacja pozwala na wczesne wykrycie błędów strukturalnych, ale nie zastępuje walidacji KSeF.

Jak wybrać narzędzie walidacji?

Wybór zależy od środowiska: biblioteki programistyczne dla integracji w kodzie, narzędzia wiersza poleceń dla testów i debugowania, edytory XML dla ręcznej weryfikacji, online validatory dla szybkich testów. Zaleca się użycie biblioteki programistycznej w procesie generowania faktur.

Walidacja kodowania UTF-8

Upewnij się, że faktura jest kodowana w UTF-8 bez znaku BOM. Sprawdź deklarację XML () i rzeczywiste kodowanie pliku. Nieprawidłowe kodowanie może powodować błędy walidacji lub przetwarzania. Użyj narzędzi do sprawdzania kodowania plików.

Narzędzia do walidacji XML

Dostępne narzędzia: biblioteki programistyczne (.NET XmlSchemaSet, Java javax.xml.validation, Python lxml, Node.js xmldom), narzędzia wiersza poleceń (xmllint dla Linux/Mac, XMLStarlet), edytory XML z walidacją (XMLSpy, Oxygen XML Editor), online validatory (XML Validation, W3C Markup Validation Service). Wybór zależy od środowiska i preferencji.

Schematy XSD dla KSeF

KSeF wymaga faktur zgodnych ze schematem XSD FA(2) (do 31 stycznia 2026) lub FA(3) (od 1 lutego 2026). Schematy są dostępne w dokumentacji KSeF oraz w repozytorium GitHub CIRFMF/ksef-docs. Schematy są regularnie aktualizowane, więc upewnij się, że używasz najnowszej wersji. Schematy zawierają definicje typów, wymagane pola i ograniczenia wartości.

Typowe błędy walidacji

Typowe błędy: brakujące pola obowiązkowe (wszystkie pola oznaczone jako required w XSD muszą być wypełnione), nieprawidłowe formaty dat (wymagany format zgodny z XSD, np. YYYY-MM-DD), wartości poza dozwolonym zakresem (sprawdź ograniczenia w XSD), nieprawidłowa struktura XML (zagnieżdżenie elementów, kolejność, namespace). Narzędzie walidacji zwróci szczegółowe komunikaty błędów.

Najlepsze praktyki

Waliduj faktury lokalnie przed wysłaniem do KSeF, używaj najnowszych schematów XSD, zaimplementuj automatyczną walidację w procesie generowania faktur, sprawdzaj kodowanie UTF-8 bez BOM, testuj walidację w środowisku testowym, loguj błędy walidacji dla analizy i poprawy. Lokalna walidacja zmniejsza liczbę odrzuceń i poprawia wydajność integracji.

FAQ

Jak zwalidować fakturę XML przed wysłaniem do KSeF?

Pobierz aktualny schemat XSD FA(2) lub FA(3) z dokumentacji KSeF. Użyj narzędzia walidacji XML (biblioteka programistyczna, narzędzie wiersza poleceń, edytor XML) do weryfikacji faktury względem schematu. Napraw wszystkie błędy walidacji przed wysłaniem. Upewnij się, że faktura jest kodowana w UTF-8 bez BOM.

Jakie narzędzia do walidacji XML są dostępne?

Dostępne narzędzia: biblioteki programistyczne (.NET XmlSchemaSet, Java javax.xml.validation, Python lxml), narzędzia wiersza poleceń (xmllint), edytory XML z walidacją (XMLSpy, Oxygen XML Editor), online validatory. Wybór zależy od środowiska i preferencji. Zaleca się użycie biblioteki programistycznej w procesie generowania faktur.

Czy lokalna walidacja zastępuje walidację KSeF?

Nie, lokalna walidacja sprawdza zgodność ze schematem XSD, ale KSeF wykonuje dodatkowe walidacje biznesowe (sprawdzanie duplikatów, limity rozmiarów, weryfikacja szyfrowania). Lokalna walidacja pozwala na wczesne wykrycie błędów strukturalnych, ale nie zastępuje walidacji KSeF. Zaleca się lokalną walidację przed wysłaniem.

Gdzie znajdę schematy XSD dla KSeF?

Schematy XSD FA(2) i FA(3) są dostępne w dokumentacji KSeF oraz w repozytorium GitHub CIRFMF/ksef-docs. Schematy są regularnie aktualizowane, więc upewnij się, że używasz najnowszej wersji. Sprawdź oficjalne źródła Ministerstwa Finansów dla aktualnych wersji schematów.

Jakie są typowe błędy walidacji?

Typowe błędy: brakujące pola obowiązkowe, nieprawidłowe formaty dat (wymagany format zgodny z XSD), wartości poza dozwolonym zakresem, nieprawidłowa struktura XML (zagnieżdżenie, kolejność, namespace), nieprawidłowe kodowanie (wymagane UTF-8 bez BOM). Narzędzie walidacji zwróci szczegółowe komunikaty błędów z lokalizacją problemu.