Czym jest schemat XSD i do czego służy?

Masz do czynienia z fakturami XML do KSeF i zastanawiasz się, czym jest schemat XSD. Tu znajdziesz proste wyjaśnienie, jak działa ten „projekt” danych i po co w ogóle go używać. Dzięki temu łatwiej ustawisz swoje systemy tak, żeby faktury nie wracały z błędami.

Czym jest schemat XSD i do czego służy?

XSD (XML Schema Definition) to plik, który opisuje, jak ma wyglądać poprawny dokument XML. Możesz go traktować jako formalny opis: jakie elementy w ogóle mogą wystąpić, w jakiej kolejności i ile razy. XSD wskazuje też, które pola są obowiązkowe, a które dopuszczalne jako opcjonalne, co ma ogromne znaczenie przy fakturach wysyłanych do KSeF.

W schemacie XSD zapisane są reguły dla formatów danych, i to bardzo szczegółowo. Określone jest, jak ma wyglądać data, jak zapisać liczbę z miejscami po przecinku, jak długi może być tekst oraz jakie wartości są akceptowane dla danego pola. Dzięki temu system może automatycznie sprawdzić, czy np. numer NIP ma 10 cyfr, czy kwoty netto i brutto są zgodne z podsumowaniem oraz czy kod waluty jest poprawny według ISO.

Najprościej mówiąc, schemat XSD jest „projektem” dla danych w XML. Działa podobnie jak projekt budowlany, który opisuje konstrukcję obiektu jeszcze przed wejściem ekipy na budowę. Projekt budowlany określa, jakie elementy muszą się znaleźć w obiekcie, a XSD określa, jakie dane muszą znaleźć się w fakturze ustrukturyzowanej, zanim trafi ona do KSeF.

W zastosowaniach biznesowych XSD pełni kilka bardzo ważnych ról, które są szczególnie odczuwalne w firmach budowlanych obsługujących duże wolumeny dokumentów:

• zapewnienie poprawności danych już na etapie zapisu pliku XML, co ogranicza liczbę błędów pojawiających się dopiero w księgowości,
• umożliwienie automatycznej kontroli plików przed przetwarzaniem przez program księgowy lub system ERP,
• ułatwienie integracji między systemami, takimi jak program księgowy, system do zarządzania budową, system kosztorysowy czy platforma obiegu dokumentów.

Dla firm z branży budowlanej schemat XSD ma bezpośredni związek z bezpieczeństwem i spójnością danych finansowych. Dobrze przygotowany schemat i poprawna integracja systemów zmniejszają ryzyko błędnych faktur za materiały, usługi podwykonawców czy roboty dodatkowe. Mniej odrzuconych faktur w KSeF oznacza mniej korekt i mniej sporów o rozliczenia na budowie.

Jakie elementy może opisywać schemat XSD w dokumencie XML?

Schemat XSD potrafi opisać wszystkie składniki dokumentu XML, od ogólnych po bardzo szczegółowe. Definiuje elementy główne i podrzędne, ich nazwy oraz to, czy dany fragment może powtórzyć się wiele razy. Dzięki temu można odwzorować na przykład listę pozycji materiałowych, usługowych lub robót z jednego kontraktu.

W XSD opisane są także atrybuty, czyli dodatkowe informacje zapisane wewnątrz elementów XML, a do tego typy danych dla każdego pola oraz zależności hierarchiczne między fragmentami dokumentu. Taka struktura idealnie pasuje do faktury ustrukturyzowanej, gdzie mamy nagłówek, dane stron, listę pozycji, podatki i podsumowania, często z dodatkowymi oznaczeniami typowymi dla budownictwa.

W praktycznych zastosowaniach budowlanych XSD pozwala bardzo dokładnie opisać to, co pojawia się na fakturach XML, zwłaszcza tych przesyłanych jako faktura ustrukturyzowana do KSeF:

• dane identyfikacyjne kontrahentów – NIP, nazwa, adres, numery rejestrowe jak REGON,
• dane kontraktów i umów – numery umów, zleceń, oznaczenia inwestycji lub projektu budowlanego,
• pozycje materiałowe i usługowe – nazwa robót, opisy elementów kosztów, jednostki miary, ilości, ceny jednostkowe,
• kwoty netto, brutto i podatki – rozbite na stawki VAT, z oddzielnymi polami na wartości i stawki,
• dane płatności – terminy, forma płatności, rachunek bankowy, ewentualne zaliczki,
• numery referencyjne – numer kontraktu, zamówienia, protokołu odbioru robót, numer kosztorysu lub pozycji kosztorysowej.

Co określają elementy, atrybuty i hierarchia w schemacie XSD?

W schemacie XSD elementy to podstawowe bloki danych, które odpowiadają tagom XML. Można je porównać do „sekcji” faktury, takich jak nagłówek, dane sprzedawcy, dane nabywcy, lista pozycji czy podsumowanie podatków. Każdy element może zawierać pod-elementy, na przykład pozycja faktury może mieć nazwę robót, ilość, cenę i stawkę VAT.

Atrybuty w XSD to dodatkowe informacje „doklejone” do elementów. W praktyce faktury budowlanej mogą określać na przykład walutę, typ pozycji (robocizna, materiał, sprzęt), rodzaj stawki VAT albo status pozycji jako zaliczkowej czy końcowej. Atrybut jest więc wygodnym sposobem na doprecyzowanie znaczenia danego elementu bez dokładania kolejnych pod-elementów.

Ogromne znaczenie ma też hierarchia w schemacie XSD, czyli relacje rodzic–dziecko między elementami. Struktura odzwierciedla logiczny układ dokumentu: faktura jako całość, w niej dane stron transakcji, dalej pozycje, a na końcu podsumowania oraz dane płatności. Dzięki hierarchii system od razu wie, które dane należą do konkretnej pozycji, a które mają charakter globalny dla całego dokumentu.

W fakturach stosowanych w budownictwie taka hierarchia może odwzorowywać rzeczywistą strukturę rozliczeń na kontraktach:

• faktura główna dla kontraktu → grupy robót według etapów inwestycji → szczegółowe pozycje materiałów i robocizny,
• faktura częściowa → etap budowy (np. stan surowy, instalacje) → pozycje rozliczanych robót z danego protokołu odbioru,
• faktura podwykonawcy → kontrakt główny → zadanie lub odcinek robót → koszty materiałów, usług sprzętowych, robocizny.

Jak XSD definiuje typy danych i formaty pól?

Schemat XSD przypisuje każdemu elementowi i atrybutowi konkretny typ danych. Może to być między innymi tekst (string), data (date), liczba dziesiętna (decimal) albo wartość logiczna (boolean). Dla każdego typu można dodatkowo opisać format, na przykład liczbę miejsc po przecinku w wartościach pieniężnych lub sposób zapisu daty zgodny ze standardem ISO.

W schematach faktur XML używanych w KSeF typy danych występują w kilku powtarzalnych grupach:

• daty – data wystawienia, sprzedaży, odbioru robót, terminy płatności,
• liczby i kwoty pieniężne – ilości, ceny jednostkowe, wartości netto, brutto i VAT, zwykle z określoną liczbą miejsc po przecinku,
• teksty opisowe – nazwy robót, opisy pozycji, nazwy inwestycji, uwagi,
• identyfikatory – NIP, REGON, numery umów, zamówień, protokołów, oznaczenia kontraktów,
• kody – kody krajów, kody walut, kody stawek VAT, typy dokumentów.

Dla faktur budowlanych ma to bardzo praktyczny wymiar. Prawidłowo zdefiniowany typ i format danych wymusza poprawny format NIP kontrahenta, sposób zapisu dat wystawienia, sprzedaży i odbioru robót oraz prawidłowe wartości kwot netto, brutto i VAT przy dużej liczbie pozycji. Przy rozbudowanych fakturach częściowych czy końcowych takie techniczne „pilnowanie” danych przez XSD często ratuje przed rozjazdem sum i potrzebą wystawiania korekt.

Jakie ograniczenia wartości można ustawić w schemacie XSD?

Oprócz typów danych XSD pozwala narzucić na wartości różne ograniczenia, nazywane często facetami. Można określić minimalną i maksymalną długość tekstu, zakres liczbowy, listę dopuszczalnych wartości albo z góry ustalone kody. Dzięki temu dane trafiające do systemu są nie tylko w poprawnym formacie technicznym, ale też mieszczą się w akceptowalnym zakresie.

W fakturach XML, także tych przesyłanych do KSeF, często stosuje się między innymi takie ograniczenia:

• wymaganą długość identyfikatorów – dokładnie 10 cyfr dla polskiego NIP, określona długość dla innych numerów,
• minimalne i maksymalne wartości kwot – na przykład zakaz używania ujemnych kwot tam, gdzie nie mają sensu biznesowo,
• dopuszczalne kody walut – tylko kody zgodne z ISO, jak PLN, EUR, USD,
• lista dozwolonych stawek VAT – wyłącznie stawki dopuszczone przepisami i przewidziane w schemacie,
• obowiązkowe kody krajów dla kontrahentów zagranicznych, zgodne z aktualnymi standardami ISO.

Dzięki takim ograniczeniom systemy, w tym KSeF, mogą od razu odrzucać niepoprawne faktury, zanim trafią do obiegu księgowego. W firmach budowlanych, gdzie obsługuje się bardzo dużo faktur za materiały, sprzęt, usługi i roboty podwykonawcze, taka automatyczna walidacja pozwala uniknąć wielu problemów z rozliczeniami oraz blokad płatności.

Co to jest schemat XSD w KSeF i jak wpływa na fakturę ustrukturyzowaną?

W Krajowym Systemie e-Faktur (KSeF) schemat XSD to oficjalny wzorzec struktury, według którego tworzona jest faktura ustrukturyzowana. Ministerstwo Finansów publikuje go jako plik XSD, a każdy program księgowy lub system ERP musi się do niego dopasować. Schemat ten określa komplet pól, ich wzajemne powiązania, typy danych i zasady poprawności.

W takim schemacie XSD dla KSeF opisane są całe sekcje faktury. Dotyczy to danych sprzedawcy i nabywcy, informacji o transakcji, listy pozycji z kwotami i stawkami VAT, a także danych płatności i pól dodatkowych wymaganych przepisami. Każda faktura XML wysyłana do KSeF musi być z tym schematem zgodna, inaczej zostanie odrzucona już na etapie walidacji technicznej.

Do 31 stycznia 2026 r. KSeF korzystał ze schematu FA(2), a od 1 lutego 2026 r. wszystkie nowe dokumenty muszą być zgodne ze schematem FA(3). Faktury ustrukturyzowane korygujące wcześniejsze dokumenty także wystawia się w strukturze FA(3). Dobrze przygotowany program księgowy lub system ERP po stronie firmy sam używa właściwej wersji schematu, ale jego konfiguracja i integracja wciąż wymagają pracy.

Schemat XSD KSeF wpływa na kilka najważniejszych obszarów faktury, które dla firm budowlanych są szczególnie istotne:

• dane sprzedawcy i nabywcy – pełne dane kontrahentów, w tym identyfikatory podatkowe i adresy,
• dane transakcji – daty, numery dokumentów, rodzaj faktury, powiązanie z umowami lub zamówieniami,
• pozycje faktury – każda pozycja robót, materiałów lub usług wraz z ilością, ceną i stawką VAT,
• podatki i podsumowania – wartości dla poszczególnych stawek VAT i łączne kwoty na fakturze,
• dane płatności i pola dodatkowe – terminy, rachunki bankowe, informacje wymagane szczególnymi przepisami podatkowymi.

Dla branży budowlanej przejście na FA(3) od 1 lutego 2026 r. oznacza obowiązek wystawiania w tej strukturze wszystkich faktur za roboty budowlane, w tym faktur częściowych i zaliczkowych oraz rozliczeń z podwykonawcami. Im bardziej poprawnie odwzorujesz w systemie pola schematu FA(3), tym mniejsze ryzyko błędów i wstrzymanych płatności przy dużych inwestycjach.

Poprawne mapowanie danych z systemu kosztorysowego lub ERP do pól schematu FA(3) – zwłaszcza nazw robót, etapów inwestycji i danych kontrahentów – wyraźnie zmniejsza ryzyko odrzucenia faktur przez KSeF i opóźnień w płatnościach.

Jak działa walidacja faktury XML na podstawie schematu XSD w KSeF?

Żeby faktura trafiła do obiegu w KSeF, najpierw musi powstać w systemie źródłowym. Może to być program księgowy, system ERP w firmie budowlanej albo moduł faktur w systemie zarządzania budową. Taki system generuje plik XML zgodny z aktualnym schematem XSD, zwykle FA(3), a następnie wysyła go do KSeF przez API KSeF lub za pomocą Aplikacji Podatnika KSeF.

Po otrzymaniu pliku KSeF uruchamia automatyczną walidację na podstawie schematu XSD. Najpierw sprawdzana jest poprawność techniczna pliku XML, a później zgodność ze strukturą FA(3), obecność wymaganych elementów, typy danych i dopuszczalne wartości. W tle mogą być też wykonywane dodatkowe reguły biznesowe, na przykład porównanie sum pozycji z kwotami z podsumowania.

W trakcie walidacji KSeF sprawdza kilka grup wymagań bardzo istotnych z punktu widzenia firm budowlanych:

• poprawność techniczną XML – czy tagi są poprawnie otwarte i zamknięte oraz czy kodowanie znaków jest właściwe,
• zgodność ze strukturą XSD – czy w pliku znajdują się wszystkie wymagane elementy i czy są w odpowiednich miejscach hierarchii,
• poprawność typów danych i zakresów – czy daty mają właściwy format, kwoty są liczbami dziesiętnymi, a identyfikatory mają wymaganą długość,
• zgodność z wersją schematu – czy faktura jest przygotowana zgodnie z obowiązującym schematem FA(3), a nie starszym FA(2).

Wynik walidacji decyduje o tym, czy faktura zostanie przyjęta do KSeF. Poprawny dokument otrzymuje numer identyfikujący w systemie, a informacja o przyjęciu wraz z tym numerem wraca do programu księgowego lub systemu ERP. Jeśli faktura nie przejdzie walidacji, system zwróci komunikat z opisem błędu i faktura nie będzie uznana za wystawioną.

Jak przebiega automatyczna walidacja faktury w KSeF krok po kroku?

Pełny proces walidacji faktury w KSeF można opisać w kilku logicznych krokach, które po kolei wykonują systemy po obu stronach:

1. Przygotowanie faktury w systemie firmy budowlanej – w programie księgowym lub systemie ERP zasilanym danymi z systemu kosztorysowego lub modułu budowy.
2. Wygenerowanie pliku XML zgodnego ze schematem FA(3), na bazie aktualnych danych kontrahentów, kontraktów i pozycji faktury.
3. Wysłanie pliku do KSeF – przez API KSeF z poziomu systemu finansowo–księgowego lub z użyciem Aplikacji Podatnika KSeF.
4. Weryfikacja techniczna struktury XML po stronie KSeF, obejmująca między innymi poprawność znaczników i kodowania.
5. Walidacja zgodności z schematem XSD – sprawdzenie obecności wymaganych elementów, zgodności typów danych i ograniczeń wartości.
6. Sprawdzenie części reguł biznesowych, na przykład zgodności sum pozycji z podsumowaniem oraz dopuszczalności kodów i stawek VAT.
7. Zwrot komunikatu do systemu nadawcy – przyjęcie faktury z nadaniem numeru KSeF albo odrzucenie z opisem błędu, który trzeba poprawić.

Z perspektywy zwykłego użytkownika proces ten często wygląda bardzo prosto i sprowadza się do komunikatu „faktura przyjęta” lub „faktura odrzucona”. W tle działa jednak szczegółowa walidacja zgodności z XSD, która decyduje, czy dokument stanie się oficjalną, fakturą ustrukturyzowaną w KSeF, czy wróci do poprawy.

Jakie błędy walidacji pojawiają się najczęściej?

Najwięcej problemów z walidacją w KSeF wynika z rozbieżności między tym, jakie dane zapisano w systemie firmy, a tym, czego wymaga schemat FA(3). Czy zdarzyło ci się, że faktura wróciła z błędem, mimo że „na oko” wszystko wyglądało dobrze. Właśnie takie sytuacje są zwykle efektem ostrych reguł XSD, których nie widać wprost w interfejsie programu.

Typowe błędy walidacji, z którymi spotykają się firmy budowlane, można podzielić na kilka grup:

• użycie nieaktualnej wersji schematu, na przykład FA(2) zamiast FA(3) po 1 lutego 2026 r.,
• brak obowiązkowych pól, takich jak NIP nabywcy, dane adresowe czy data sprzedaży lub zakończenia robót,
• nieprawidłowy format danych, na przykład zły format daty, nieodpowiednia długość NIP, niepoprawny kod kraju lub waluty,
• niezgodność sum – suma pozycji nie zgadza się z kwotami w podsumowaniach lub w rozbiciu na stawki VAT,
• niedopuszczone kody lub stawki VAT według schematu XSD, w tym użycie stawek niewspieranych przez FA(3),
• błędne oznaczenia waluty albo niekonsekwentne użycie waluty w nagłówku i pozycjach.

W realiach firm budowlanych takie błędy pojawiają się częściej, bo dane kontrahentów i umów zmieniają się dynamicznie, a faktury potrafią mieć dziesiątki lub setki pozycji. Dodatkowo rozliczenia częściowe i końcowe, a także korekty do wcześniejszych faktur zwiększają ryzyko rozjazdu dat, kwot i numerów referencyjnych, co wprost przekłada się na odrzucenia przez KSeF.

Jak samodzielnie sprawdzić poprawność faktury XML przed wysłaniem?

Fakturę XML można wstępnie sprawdzić lokalnie, zanim w ogóle trafi do KSeF. Część programów księgowych ma wbudowaną walidację na podstawie schematu FA(3), a tam, gdzie jej brakuje, można użyć zewnętrznych narzędzi. Przy bardziej złożonych integracjach dział IT często korzysta z dedykowanych narzędzi deweloperskich do walidacji XML względem XSD.

Najczęściej stosowane podejścia do sprawdzenia poprawności faktury XML wyglądają tak:

• wbudowana walidacja w programach księgowych lub systemach ERP zintegrowanych z KSeF, działająca automatycznie przed wysyłką dokumentu,
• użycie darmowego walidatora faktury XML online lub specjalistycznych narzędzi do weryfikacji struktury i danych przed wysłaniem do KSeF,
• testowanie w środowisku testowym KSeF, gdzie można „przećwiczyć” wysyłkę faktur bez skutków podatkowych,
• wykorzystanie narzędzi deweloperskich przez informatyków, którzy bezpośrednio sprawdzają plik XML względem pliku XSD FA(3).

Dla firm budowlanych wcześniejsza walidacja ma duże znaczenie, bo przyspiesza obieg dokumentów i zmniejsza liczbę faktur wracających do poprawy. Mniej odrzuceń oznacza mniej przestojów w płatnościach dla wykonawców i podwykonawców, a także mniejsze ryzyko wystawiania wielu korekt do tej samej dostawy materiałów lub etapu robót.

Wielokrotne odrzucanie faktur przez KSeF z powodu powtarzających się błędów, takich jak zły format dat czy braki w danych kontrahenta, może mocno spowolnić rozliczenia z inwestorami i podwykonawcami – warto regularnie testować walidację na przykładowych fakturach o dużej liczbie pozycji typowych dla inwestycji budowlanych.

Przejście z FA(2) na FA(3) w KSeF i powody zmian schematów XSD

Zmiana schematu XSD w KSeF miała wyraźnie określoną chronologię. Schemat FA(2) był używany do 31 stycznia 2026 r. dla wszystkich faktur ustrukturyzowanych. Od 1 lutego 2026 r. obowiązkowa stała się struktura FA(3), która dotyczy nie tylko nowych faktur, ale także faktur korygujących wystawianych do dokumentów z poprzednich okresów.

Różnice między FA(2) i FA(3) można ująć w prostym porównaniu, przydatnym przy planowaniu zmian w oprogramowaniu:

Powody aktualizacji schematu XSD są związane zarówno z przepisami podatkowymi, jak i z potrzebami technicznymi systemu KSeF:

• dostosowanie do zmian w prawie podatkowym, w tym nowych wymogów dotyczących zawartości faktury,
• wprowadzenie nowych wymaganych informacji na fakturze ustrukturyzowanej, potrzebnych organom podatkowym do analizy danych,
• poprawa błędów i niedoskonałości zidentyfikowanych w poprzedniej wersji schematu FA(2),
• zwiększenie precyzji opisu transakcji, w tym precyzyjniejszego powiązania pozycji z danymi kontraktu,
• lepsze wsparcie dla automatycznej analizy danych, także w dużej skali, gdzie pracuje się na milionach faktur.

Dla firm budowlanych oznacza to możliwość dokładniejszego raportowania rodzaju robót, etapów inwestycji, zaliczek i rozliczeń końcowych na fakturach ustrukturyzowanych. Jeśli oprogramowanie i integracje zostaną odpowiednio przygotowane do FA(3), nowa struktura może ułatwić analizę kosztów kontraktów oraz zestawianie danych pomiędzy systemem kosztorysowym, ERP i księgowością.

Jak przygotować oprogramowanie i procesy w firmie do zmian schematu XSD w KSeF?

Zmiana schematu XSD, taka jak przejście z FA(2) na FA(3), wymaga działań nie tylko po stronie dostawcy systemu, ale też wewnątrz firmy. Chodzi zarówno o aktualizację oprogramowania, jak i dostosowanie procedur obiegu dokumentów finansowych oraz komunikacji między działem realizacji a księgowością. Bez tego nawet najlepszy program nie ochroni przed błędami w KSeF.

Od strony oprogramowania warto zaplanować kilka bardzo konkretnych działań:

• sprawdzenie, czy program księgowy lub ERP ma zapewnioną aktualizację do schematu FA(3) przez dostawcę,
• ustalenie terminu aktualizacji i przeprowadzenie jej z wyprzedzeniem, a nie w ostatnim dniu przed zmianą,
• testy integracji z KSeF w środowisku testowym, szczególnie tam, gdzie faktury są generowane z kilku systemów źródłowych,
• weryfikacja mapowania pól – czy wszystkie wymagane dane z systemów budowlanych trafiają do odpowiednich pól schematu XSD FA(3).

Od strony organizacyjnej trzeba też zadbać o jasny podział zadań i aktualną dokumentację procesu fakturowania:

• przegląd wewnętrznych procedur wystawiania faktur, w tym odpowiedzialności za dostarczenie danych o kontrakcie lub robocie,
• weryfikacja procesu aktualizacji danych kontrahentów, aby NIP, adresy i inne identyfikatory były zawsze aktualne,
• aktualizacja instrukcji dla działu księgowości i działów realizacyjnych, opisująca nowe wymagania FA(3),
• szkolenia dla pracowników odpowiedzialnych za fakturowanie, szczególnie w kontekście specyficznych wymagań KSeF.

Do tego warto wprowadzić działania kontrolne, które pozwolą szybko wychwycić problemy już po zmianie schematu XSD:

• przygotowanie scenariuszy testowych na reprezentatywnych fakturach – zaliczkowych, częściowych, końcowych, z dużymi dostawami materiałów i rozliczeniami z podwykonawcami,
• monitorowanie pierwszych wysyłek po zmianie schematu pod kątem częstości i rodzaju błędów walidacji,
• szybkie reagowanie na komunikaty błędów oraz ich analiza, aby poprawiać konfigurację integracji, a nie tylko pojedyncze faktury.

Znaczenie ma także współpraca z dostawcą oprogramowania i działem IT przy interpretacji wymagań FA(3). To szczególnie ważne, jeśli firma korzysta z rozbudowanych integracji między systemem do zarządzania budowami, systemem kosztorysowym a programem księgowym zintegrowanym z KSeF. Bez wspólnej pracy nad mapowaniem pól i testami łatwo o powtarzalne błędy walidacji.

Dobrą praktyką dla firm budowlanych jest przeprowadzenie przed wejściem w życie nowej wersji schematu, takiej jak FA(3), „próbnego fakturowania” – wysłanie do środowiska testowego KSeF zestawu typowych faktur zaliczkowych, częściowych i końcowych z wieloma pozycjami i różnymi stawkami VAT, co pozwala wychwycić błędy mapowania pól zanim zaczną obowiązywać realne rozliczenia.