Czy do walidacji XSD potrzebuję dostępu do CRD w trakcie działania aplikacji?

Nie, jeśli schematy pobierzesz wcześniej i skonfigurujesz resolver mapujący odwołania schemaLocation na lokalne pliki. Dzięki temu walidacja nie zależy od dostępności zewnętrznego serwera.

Czy XSD sprawdza podpis XAdES w KSeF?

Nie. XSD waliduje strukturę XML, a podpis XAdES jest weryfikowany osobnym mechanizmem kryptograficznym. W procesie uwierzytelniania KSeF podpis XAdES jest wymagany, ale to nie jest ten sam typ walidacji.

Walidacja XSD: schematy z CRD, brak dostępu i podpis XAdES

Jeśli walidator XML próbuje pobierać schematy XSD z internetu i kończy się to błędem, rozwiązaniem jest lokalne cache i własny resolver. Podpis XAdES to osobny etap, niezależny od XSD.

Co musisz wiedzieć

W integracjach z KSeF najczęściej waliduje się XML (np. fakturę FA) względem schematu XSD jeszcze przed wysyłką. Pozwala to szybciej wychwycić błędy struktury, przestrzeni nazw i typów danych niż w samej odpowiedzi z API.

Schematu XSD nie trzeba pobierać przy każdym uruchomieniu walidacji. W praktyce lepiej pobrać schematy do repozytorium lub artefaktu (cache) i skonfigurować walidator tak, aby rozwiązywał odwołania lokalnie. To jest szczególnie ważne, gdy schematy są publikowane jako zewnętrzne zasoby (np. w CRD) i mogą być chwilowo trudno dostępne.

Walidacja XSD nie weryfikuje kryptograficznie podpisu XAdES. W KSeF podpis XAdES jest używany m.in. w procesie uwierzytelniania (AuthTokenRequest), ale jego poprawność sprawdza się osobnym mechanizmem, a nie przez XSD.

Instrukcja krok po kroku

1. Ustal, jaki schemat XSD jest właściwy dla Twojego XML

Dla faktur korzystaj z oficjalnych schematów FA(2) lub FA(3) w repozytorium CIRFMF/ksef-docs. Jeśli walidujesz inne dokumenty urzędowe poza schematami KSeF, źródłem schematów bywa CRD (Centralne Repozytorium Wzorów Dokumentów Elektronicznych).

2. Pobierz schematy do lokalnego cache

Zamiast polegać na pobieraniu schematów w locie, przechowuj je lokalnie (np. w katalogu projektu lub w artefaktach CI). Dzięki temu walidacja nie zależy od dostępności zewnętrznych serwerów.

3. Skonfiguruj resolver (catalog) dla importów i include

Jeśli schemat główny odwołuje się do innych XSD, skonfiguruj resolver mapujący schemaLocation na pliki lokalne. W zależności od biblioteki może to być XML Catalog, własny EntityResolver/LSResourceResolver albo dedykowana konfiguracja walidatora.

4. Rozdziel walidację XSD od walidacji podpisu XAdES

Najczęściej waliduj XSD na etapie generowania XML (przed podpisaniem). Walidację podpisu XAdES traktuj jako osobny krok: sprawdzanie integralności, certyfikatu i czasu podpisu.

Najczęstsze problemy i rozwiązania

Walidator zawiesza się lub timeoutuje przy pobieraniu schematu

Wyłącz pobieranie schematów z sieci i podaj lokalne pliki XSD. Jeśli biblioteka tego wymaga, skonfiguruj XML Catalog lub resolver zasobów.

Walidacja przechodzi lokalnie, ale KSeF odrzuca dokument

Lokalna walidacja XSD nie zastępuje walidacji semantycznej i reguł biznesowych po stronie KSeF. Traktuj XSD jako pierwszy filtr, a nie pełny odpowiednik walidacji systemowej.

Błędy po podpisaniu dokumentu XML

Waliduj strukturę XML przed podpisaniem, a po podpisaniu waliduj podpis osobno. Jeśli musisz walidować po podpisie, upewnij się, że używasz schematu, który dopuszcza obecność elementów podpisu.

Schematy FA(2) i FA(3) z oficjalnych źródeł

Oficjalne schematy faktur są dostępne w repozytorium CIRFMF/ksef-docs. Przykładowo: schemat FA(2) oraz schemat FA(3). W praktyce warto pinować wersje schematów w projekcie i aktualizować je świadomie.

CRD jako źródło schematów zewnętrznych

CRD (Centralne Repozytorium Wzorów Dokumentów Elektronicznych) publikuje listy schematów i wzorów. Jeśli Twoja walidacja dotyczy schematów wskazywanych przez CRD, weź pod uwagę, że dostęp do konkretnych plików XSD może zależeć od warunków sieciowych i dlatego lepiej mieć lokalny cache. Strona główna CRD: https://crd.gov.pl.

Typowe przyczyny błędów walidacji związanych z pobieraniem XSD

Najczęstszy problem to próba pobrania zewnętrznych importów w trakcie walidacji. Wtedy zobaczysz błędy typu timeout, brak połączenia lub odmowa dostępu. Rozwiązanie to: lokalna kopia zależności XSD oraz resolver mapujący URL do pliku lokalnego.

Podpis XAdES a walidacja XSD w KSeF

W procesie uwierzytelniania KSeF wykorzystywany jest dokument XML AuthTokenRequest podpisany XAdES. Dokumentacja opisuje kolejne kroki: przygotowanie XML, podpisanie XAdES, a następnie wysłanie do API. To ważne rozróżnienie: XSD sprawdza strukturę XML, a XAdES jest warstwą kryptograficzną weryfikowaną niezależnie. Dokumentacja CIRFMF/ksef-docs: https://github.com/CIRFMF/ksef-docs/tree/main (plik: uwierzytelnianie.md). Dokumentacja MF: https://api-test.ksef.mf.gov.pl/docs/v2/index.html.

FAQ

Czy muszę mieć dostęp do internetu, aby walidować XML względem XSD?

Nie, jeśli przechowujesz schematy lokalnie. Dostęp do internetu jest potrzebny tylko wtedy, gdy walidator ma pobierać schemaLocation z URL i nie masz resolvera mapującego te odwołania na lokalne pliki.

Czy walidacja XSD sprawdza poprawność podpisu XAdES?

Nie. Walidacja XSD dotyczy struktury XML. Podpis XAdES wymaga osobnej walidacji kryptograficznej (certyfikat, integralność, czas).

Skąd brać schematy FA(2) i FA(3)?

Najbezpieczniej z oficjalnego repozytorium CIRFMF/ksef-docs. Linki do FA(2) i FA(3) są również podane w OpenAPI KSeF API.

Jak ograniczyć ryzyko, że walidacja przestanie działać przez zewnętrzny serwer?

Pobierz schematy do lokalnego cache, skonfiguruj resolver i nie polegaj na pobieraniu XSD w locie. W CI warto dodać test walidacji na znanych przykładach XML.

Powiązane tematy

Przydatne serwisy

Status KSeF

Pierwszy serwis prezentuje informacje o statusie samego KSeF, drugi – komunikaty techniczne Ministerstwa Finansów.