Wystawianie faktur

Schemat XSD FA(3) w KSeF: gdzie go pobrać i jak sprawdzić plik XML

W skrócie

Schemat faktury KSeF to plik schemat.xsd struktury logicznej FA(3), opublikowany przez MF w Centralnym Repozytorium Wzorów Dokumentów Elektronicznych pod adresem crd.gov.pl/wzor/2025/06/25/13775/. Obowiązuje dla wszystkich faktur w KSeF od 1 lutego 2026 r. Do walidacji offline potrzebujesz jeszcze trzech importowanych plików MF, a sama zgodność z XSD nie wystarcza – KSeF sprawdza też m.in. kodowanie, duplikaty, datę P_1 i sumę kontrolną NIP.

Spis treści
  1. Gdzie pobrać schemat XSD faktury KSeF?
  2. Co jest w schemacie FA(3)?
  3. FA(2) a FA(3) – czym różnią się schematy?
  4. Jak zwalidować plik XML ze schematem FA(3)?
  5. Co KSeF sprawdza poza schematem XSD?
  6. Najczęstsze błędy walidacji schematu FA(3)

Schema KSeF – inaczej schema faktury KSeF albo schemat XSD faktury ustrukturyzowanej – to plik schemat.xsd struktury logicznej FA(3). MF opublikowało go 25 czerwca 2025 r. w Centralnym Repozytorium Wzorów Dokumentów Elektronicznych pod adresem crd.gov.pl/wzor/2025/06/25/13775/, a od 1 lutego 2026 r. każda faktura wysłana do KSeF musi być z nim zgodna – inaczej nie dostanie numeru KSeF.

Schemat określa kolejność elementów, formaty i słowniki wartości. Nie mówi, co wpisać w konkretnej sytuacji – do tego służy broszura FA(3), a w naszym poradniku tekst o obowiązkowych elementach faktury KSeF.

Gdzie pobrać schemat XSD faktury KSeF?

Strona wzoru w CRD zawiera trzy pliki. Sam schemat.xsd do walidacji nie wystarczy: importuje wspólne definicje MF, a te dołączają kolejne dwa pliki. Strona „Struktura logiczna FA(3)” na ksef.podatki.gov.pl odsyła właśnie do CRD.

Plik Adres Do czego służy
schemat.xsd crd.gov.pl/wzor/2025/06/25/13775/ schemat FA(3) – według niego KSeF sprawdza plik
styl.xsl ten sam katalog arkusz XSLT, który zamienia XML w podgląd HTML „e-FAKTURA KSeF”
wyroznik.xml ten sam katalog metryka wzoru: twórca MF, ważność od 2026-02-01, podpis
StrukturyDanych_v10-0E.xsd crd.gov.pl/xml/schematy/dziedzinowe/mf/2022/01/05/eD/DefinicjeTypy/ importuje go schemat.xsd (prefiks etd)
ElementarneTypyDanych_v10-0E.xsd ten sam katalog dołącza go plik wyżej; m.in. wzorzec NIP, typ daty, znaczniki 1 i 1/2
KodyKrajow_v10-0E.xsd ten sam katalog słownik kodów krajów, dołączany przez plik wyżej
schemat_FA(3)_v1-0E.xsd i katalog bazowe CIRFMF/ksef-api kopia MF na GitHubie, obok niej schemat FA(2)
broszura FA(3) i przykładowe pliki XML (ZIP) Pliki do pobrania opis pól z przykładami i 26 wzorcowych faktur

17 listopada 2026 r. porównaliśmy schemat.xsd z CRD z kopią w repozytorium CIRFMF – to ten sam plik, bajt w bajt (183 798 bajtów). Faktury z paczki MF omawiamy w tekście przykładowy plik XML FA(3).

Co jest w schemacie FA(3)?

Element główny to Faktura w przestrzeni nazw http://crd.gov.pl/wzor/2025/06/25/13775/. Dwie rzeczy łatwo przeoczyć:

  • http, nie https. Plik z xmlns="https://crd.gov.pl/..." nie przejdzie walidacji – parser w ogóle nie znajdzie definicji elementu głównego.
  • Każdy element w tej przestrzeni nazw. Schemat ma elementFormDefault="qualified", więc najprościej ustawić domyślne xmlns w Faktura. Deklaracje xmlns:etd i xmlns:xsi, które MF umieszcza w przykładach, nie są potrzebne.

Nagłówek zawiera stałe zapisane w schemacie jako wartości fixed:

<Naglowek>
  <KodFormularza kodSystemowy="FA (3)" wersjaSchemy="1-0E">FA</KodFormularza>
  <WariantFormularza>3</WariantFormularza>
  <DataWytworzeniaFa>2026-11-17T09:30:00Z</DataWytworzeniaFa>
</Naglowek>

W kodSystemowy jest spacja przed nawiasem – zapis „FA(3)” to błąd. Tę samą trójkę (FA (3), 1-0E, FA) program podaje w formCode przy otwieraniu sesji w API KSeF, a KSeF sprawdza plik ze schematem zadeklarowanym w sesji. DataWytworzeniaFa to chwila utworzenia pliku – nie wcześniej niż 1 września 2025 r. Nie zastępuje daty wystawienia z P_1 (FAQ, pyt. 12).

Pod nagłówkiem schemat ustala sztywną kolejność ośmiu elementów: obowiązkowych Naglowek, Podmiot1, Podmiot2 i Fa oraz nieobowiązkowych Podmiot3 (do 100 razy), PodmiotUpowazniony, Stopka i Zalacznik. Typy danych, które sprawiają programom najwięcej kłopotu:

  • kwoty (TKwotowy) – kropka dziesiętna, najwyżej 2 miejsca po kropce, bez spacji; ceny P_9A i P_9B oraz opusty P_10 – do 8 miejsc, ilości i kursy walut – do 6,
  • daty (TDataT) – RRRR-MM-DD, w zakresie lat 2006–2050,
  • teksty – zwykle 1–256 znaków, nazwy i linie adresu do 512,
  • NIP (TNrNIP) – dziesięć cyfr według wzorca; sumy kontrolnej XSD nie liczy.

FA(2) a FA(3) – czym różnią się schematy?

Poprzednia wersja, FA(2), działała od 1 września 2023 r. aż do końca stycznia 2026 r. Teraz wszystkie faktury w KSeF wystawiasz w FA(3) – także korekty faktur z FA(2) i faktury rozliczające zaliczki zafakturowane przed lutym (broszura FA(3), wstęp).

FA(2) miała WariantFormularza = 2, kodSystemowy="FA (2)" i własną przestrzeń nazw: http://crd.gov.pl/wzor/2023/06/29/12648/. Nie było w niej pól JST i GV ani elementu Zalacznik, a w P_12 istniały tylko „0” i „np” – dziś są to np I, np II oraz 0 KR, 0 WDT i 0 EX. MF w FAQ (pyt. 4) wymienia jeszcze nowy zapis terminu płatności, rolę „pracownik” w Podmiot3 i dłuższe pole P_7.

Według dokumentacji API z 16 marca 2026 r. (CIRFMF, zestawienie środowisk) produkcja przyjmuje z faktur VAT tylko FA(3). FA(2) zostało na środowisku testowym.

Jak zwalidować plik XML ze schematem FA(3)?

schemat.xsd importuje StrukturyDanych_v10-0E.xsd z adresu zaczynającego się od http://crd.gov.pl/, a ten dołącza dwa kolejne pliki. Walidator bez dostępu do sieci albo z blokadą pobierania (np. xmllint --nonet) ich nie znajdzie. Najprostsza droga:

  1. Pobierz cztery pliki XSD do jednego katalogu.
  2. W schemat.xsd zmień schemaLocation importu na samą nazwę pliku. Tak samo popraw xsd:include w dwóch plikach bazowych – w kopii CIRFMF są już względne.
  3. Uruchom walidację lokalnie.

Jeśli wolisz nie ruszać oryginałów, przekieruj adresy crd.gov.pl na pliki z dysku katalogiem XML.

xmllint --noout --schema schemat.xsd faktura.xml

To samo w Pythonie z biblioteką lxml:

from lxml import etree

schemat = etree.XMLSchema(etree.parse("schemat.xsd"))
faktura = etree.parse("faktura.xml")

if schemat.validate(faktura):
    print("Plik zgodny z FA(3)")
else:
    for blad in schemat.error_log:
        print(blad.line, blad.message)

Tym skryptem sprawdziliśmy wszystkie 26 przykładowych plików MF – każdy przeszedł. W Javie użyjesz klas SchemaFactory i Validator z pakietu javax.xml.validation, w C# – XmlSchemaSet i XmlReaderSettings z ValidationType.Schema. MF zachęca, by program sprawdzał plik ze wzorem jeszcze przed wysyłką (cz. II pkt 1.6.1).

Co KSeF sprawdza poza schematem XSD?

Kontrola XSD KSeF
obecność i kolejność elementów, formaty, słowniki (stawki, waluty) tak tak
UTF-8 bez BOM; prolog nie może wskazywać innego kodowania nie tak
instrukcje przetwarzania XML i niezalecane znaki Unicode nie tak
suma kontrolna NIP sprzedawcy, nabywcy, Podmiot3 i PodmiotUpowazniony nie tak, na produkcji
duplikat: ten sam NIP sprzedawcy, RodzajFaktury i P_2 nie tak
data P_1 nie późniejsza niż dzień przyjęcia pliku nie tak
rozmiar: 1 MB, z załącznikami 3 MB nie tak
uprawnienia wysyłającego, zgłoszenie faktur z załącznikiem nie tak
rachunki: VAT od kwoty netto, suma w P_15 nie nie

Na środowisku testowym sumę kontrolną NIP włączysz nagłówkiem X-KSeF-Feature: subject-identifier-validation. Co znaczą kody odrzucenia 430, 440 i 450, wyjaśniamy w tekście kody błędów KSeF, a ograniczenia liczby zapytań – w artykule limity KSeF.

Najczęstsze błędy walidacji schematu FA(3)

Komunikaty pochodzą z biblioteki libxml2, na której działają xmllint i lxml. Wywołaliśmy je, psując po kolei przykładowy plik MF nr 1:

Co jest w pliku Komunikat walidatora (fragment) Jak poprawić
xmlns="https://crd.gov.pl/..." No matching global declaration adres z http://
kodSystemowy="FA(3)" fixed value constraint FA (3) ze spacją
brak JST i GV albo GV przed JST Missing child element(s) lub This element is not expected – w obu wypadkach z podpowiedzią „Expected is one of (… IDNabywcy, … JST)” JST, potem GV na końcu Podmiot2
<P_15>2 051,00</P_15> is not a valid value (typ TKwotowy) 2051.00
<NIP>PL1111111111</NIP> albo NIP z kreskami is not accepted by the pattern same cyfry; kod kraju w osobnym polu
<P_12>5%</P_12> albo 0 is not an element of the set 5, a przy zerowej stawce 0 KR, 0 WDT lub 0 EX
<P_1>15.02.2026</P_1> is not a valid value (typ TDataT) 2026-02-15

Po każdej poprawce uruchom walidację jeszcze raz – błąd kolejności w jednym elemencie potrafi zasłonić następne usterki w tym samym miejscu pliku.

Najczęstsze pytania

Gdzie pobrać schemat XSD faktury KSeF?

Plik schemat.xsd struktury FA(3) pobierzesz z crd.gov.pl/wzor/2025/06/25/13775/, czyli z Centralnego Repozytorium Wzorów Dokumentów Elektronicznych. Kopię razem ze schematami bazowymi MF udostępnia też w repozytorium CIRFMF/ksef-api na GitHubie, w katalogu faktury/schemy/FA.

Czy KSeF przyjmie jeszcze fakturę w strukturze FA(2)?

Nie na środowisku produkcyjnym. Od 1 lutego 2026 r. obowiązuje FA(3), także dla korekt faktur wystawionych wcześniej w FA(2). Według dokumentacji API MF schemat FA(2) działa już tylko na środowisku testowym.

Dlaczego walidator nie może wczytać schematu FA(3)?

Schemat importuje plik StrukturyDanych_v10-0E.xsd z adresu http na crd.gov.pl, a ten dołącza dwa kolejne pliki. Bez sieci walidator ich nie znajdzie. Pobierz wszystkie cztery pliki do jednego katalogu i zmień adresy w schemaLocation na nazwy plików albo użyj katalogu XML.

Czy plik zgodny ze schematem XSD na pewno przejdzie w KSeF?

Nie zawsze. KSeF odrzuci też plik ze znakiem BOM, z instrukcją przetwarzania XML, z datą P_1 z przyszłości, z błędną sumą kontrolną NIP (na produkcji) albo duplikat. Nie sprawdza za to rachunków, np. kwoty VAT.

Jaka jest przestrzeń nazw faktury FA(3)?

http://crd.gov.pl/wzor/2025/06/25/13775/ – z http, nie https. Wszystkie elementy faktury muszą należeć do tej przestrzeni nazw, najprościej przez atrybut xmlns w elemencie Faktura.

Źródła

  1. Wzór FA(3) w Centralnym Repozytorium Wzorów Dokumentów Elektronicznych (nr 13775) – schemat.xsd, styl.xsl, wyroznik.xml
  2. Broszura informacyjna struktury logicznej FA(3) (MF, sierpień 2026) – wstęp, formaty pól pkt 1–10, tabele 2 i 3
  3. Podręcznik KSeF 2.0 cz. II (MF, 06.08.2026), pkt 1.6.1 i rozdz. 2
  4. CIRFMF/ksef-api, „Weryfikacja faktury” (09.04.2026); dokument z 16.03.2026 o środowiskach API; api-changelog, wersje 2.3.0 i 2.4.0
  5. CIRFMF/ksef-api – schematy FA(2), FA(3) i schematy bazowe (faktury/schemy/FA)
  6. Pytania i odpowiedzi KSeF 2.0 (MF) – „Rozwiązania informatyczne, integracje i struktura KSeF”, pyt. 3, 4, 6 i 12

Artykuł ma charakter informacyjny i nie stanowi porady podatkowej. W konkretnej sprawie skonsultuj się z księgowym lub doradcą podatkowym.

Przeczytaj też