Struktura KSeF FA3 XML — Techniczny Przewodnik po Schemacie Faktury Ustrukturyzowanej

Tablixa Blog · 2026-05-08

Struktura KSeF FA3 XML — Techniczny Przewodnik po Schemacie Faktury Ustrukturyzowanej

Jeśli integrujesz swój system z Krajowym Systemem e-Faktur (KSeF) lub budujesz generator plików FA3 XML, ten przewodnik jest dla Ciebie. Omówimy strukturę schematu od korzenia dokumentu aż po szczegóły poszczególnych sekcji — z przykładami kodu i wskazaniem miejsc, gdzie łatwo popełnić błąd.

Czym Jest FA3 i Skąd Pochodzi Schemat?

FA3 (Faktura wersja 3) to aktualnie obowiązujący schemat XML dla faktur ustrukturyzowanych w KSeF. Ministerstwo Finansów opublikowało schemat XSD pod adresem repozytorium na stronie podatki.gov.pl. Schemat FA3 zastąpił wcześniejsze wersje FA i FA(2) — żadna z poprzednich wersji nie jest już akceptowana przez API KSeF.

Obowiązujący namespace (przestrzeń nazw) dla FA3:


xmlns="http://crd.gov.pl/wzor/2023/06/29/12648/"

Dodatkowe namespace wymagane w dokumencie:


xmlns:etd="http://crd.gov.pl/xml/schematy/dziedzinowe/mf/2022/01/05/eD/DefinicjeTypy/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

Szkielet Dokumentu FA3 XML

Pełny dokument FA3 składa się z kilku głównych sekcji umieszczonych wewnątrz elementu korzeniowego :


<?xml version="1.0" encoding="UTF-8"?>
<Faktura xmlns="http://crd.gov.pl/wzor/2023/06/29/12648/"
         xmlns:etd="http://crd.gov.pl/xml/schematy/dziedzinowe/mf/2022/01/05/eD/DefinicjeTypy/"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  <Naglowek>...</Naglowek>
  <Podmiot1>...</Podmiot1>
  <Podmiot2>...</Podmiot2>
  <Fa>...</Fa>
  <!-- opcjonalnie: Stopka, Rozszerzenie -->

</Faktura>

Kolejność elementów na poziomie jest sztywna — XSD wymaga ich dokładnie w tej kolejności. Zmiana kolejności skutkuje błędem walidacji cvc-complex-type.

Struktura dokumentu FA3 XML <Faktura> Naglowek Podmiot1 Podmiot2 Fa Stopka* FaWiersz (1..n) Rozliczenie Platnosc * Stopka — opcjonalna. Kolejność elementów jest ściśle określona przez XSD.

Sekcja Naglowek

Element zawiera metadane identyfikujące fakturę na poziomie systemowym:


<Naglowek>
  <KodFormularza kodSystemowy="FA (3)" wersjaSchemy="1-0E">FA</KodFormularza>
  <WariantFormularza>3</WariantFormularza>
  <DataWytworzeniaFa>2026-05-07T10:30:00</DataWytworzeniaFa>
  <NazwaSystemu>NazwaTwojegoSystemu</NazwaSystemu>
</Naglowek>

DataWytworzeniaFa musi być w formacie RRRR-MM-DDTHH:MM:SS (ISO 8601 z czasem). Pole NazwaSystemu to identyfikator oprogramowania generującego fakturę.

Sekcja Podmiot1 — Sprzedawca

opisuje sprzedawcę. Struktura jest hierarchiczna:


<Podmiot1>
  <DaneIdentyfikacyjne>
    <NIP>1234567890</NIP>
    <Nazwa>Firma ABC Sp. z o.o.</Nazwa>
  </DaneIdentyfikacyjne>
  <Adres>
    <KodKraju>PL</KodKraju>
    <AdresL1>ul. Przykładowa 1</AdresL1>
    <AdresL2>00-001 Warszawa</AdresL2>
  </Adres>
  <DaneKontaktowe>
    <Email>faktura@firmabc.pl</Email>
  </DaneKontaktowe>
</Podmiot1>

NIP musi być 10-cyfrowym ciągiem bez przedrostka "PL" i bez myślników. KSeF weryfikuje sumę kontrolną NIP — fikcyjny numer zostanie odrzucony.

Sekcja Podmiot2 — Nabywca

ma analogiczną strukturę do . W przypadku nabywcy będącego osobą fizyczną (B2C) zamiast można użyć , ale uwaga — faktury B2C i tak nie podlegają obowiązkowi KSeF.

Jeśli nabywca nie ma NIP (np. transakcja z podmiotem zagranicznym), stosuje się pole 1 zamiast .

Sekcja Fa — Główna Treść Faktury

To najobszerniejsza sekcja, zawierająca:

Dane nagłówkowe faktury:


<Fa>
  <KodWaluty>PLN</KodWaluty>
  <P_1>2026-05-07</P_1>        <!-- data wystawienia -->
  <P_1M>2026-05</P_1M>         <!-- miesiąc i rok wystawienia -->
  <P_2>FV/2026/05/001</P_2>    <!-- numer faktury -->
  <P_6>2026-05-07</P_6>        <!-- data dokonania dostawy/usługi -->

Pozycje fakturowe (FaWiersz):


  <FaWiersz>
    <NrWierszaFa>1</NrWierszaFa>
    <P_7>Usługi programistyczne</P_7>   <!-- nazwa towaru/usługi -->
    <P_8A>godz</P_8A>                   <!-- jednostka miary -->
    <P_8B>10</P_8B>                     <!-- ilość -->
    <P_9A>500.00</P_9A>                 <!-- cena jednostkowa netto -->
    <P_11>5000.00</P_11>                <!-- wartość netto -->
    <P_12>23</P_12>                     <!-- stawka VAT: 23, 8, 5, 0, ZW, NP, OO -->
  </FaWiersz>

Rozliczenie (podsumowanie kwot):


  <Rozliczenie>
    <P_13_1>5000.00</P_13_1>    <!-- netto wg stawki 23% -->
    <P_14_1>1150.00</P_14_1>    <!-- VAT wg stawki 23% -->
    <P_15>6150.00</P_15>         <!-- suma brutto -->
  </Rozliczenie>

Kwoty w muszą być dokładnie zgodne z sumą pozycji z . Różnica nawet o jeden grosz skutkuje odrzuceniem faktury.

Płatność:


  <Platnosc>
    <Zaplacono>2</Zaplacono>    <!-- 1=tak, 2=nie, 3=częściowo -->
    <TerminPlatnosci>
      <Termin>2026-05-21</Termin>
    </TerminPlatnosci>
    <FormaPlatnosci>6</FormaPlatnosci>  <!-- 6=przelew -->
    <RachunekBankowy>
      <NrRB>PL61109010140000071219812874</NrRB>
    </RachunekBankowy>
  </Platnosc>
</Fa>

Najczęstsze Pułapki Implementacyjne

Kodowanie UTF-8 bez BOM: Plik musi być w UTF-8. Edytory Windows często dodają BOM (Byte Order Mark) na początku pliku — KSeF traktuje BOM jako nieprawidłowy znak i odrzuca dokument. Generując XML programowo, jawnie wyłącz BOM w strumieniu wyjściowym.

Zaokrąglenie kwot: Obliczaj VAT dla każdej pozycji z dokładnością do 2 miejsc po przecinku. Sumuj już zaokrąglone wartości, nie nieokrągloną sumę.

Wartości liczbowe bez separatora tysięcy: 5000.00 jest prawidłowe, 5 000.00 lub 5,000.00 nie.

Separator dziesiętny: Używaj kropki (.), nie przecinka (,) w wartościach numerycznych XML.

Kolejność elementów XSD: Schemat XSD stosuje xs:sequence — elementy muszą być w dokładnie takiej kolejności, jak zdefiniowane w schemacie. Niezgodność kolejności to jeden z najczęstszych błędów przy ręcznym budowaniu XML.

Walidacja Pliku FA3 XML

Przed wysyłką do KSeF waliduj plik względem oficjalnego schematu XSD. Możesz to zrobić:

  • lokalnie, używając narzędzia xmllint lub kodu w języku programowania (np. lxml w Pythonie, javax.xml.validation w Javie)
  • online, korzystając z narzędzia Tablixa Walidator KSeF XML — automatycznie sprawdza zgodność ze schematem FA3

Walidacja lokalna jest szybsza i nie zużywa limitów API KSeF.

Generuj Poprawne Pliki FA3 XML z Tablixa

Jeśli nie chcesz implementować generatora FA3 XML od zera, Tablixa oferuje konwerter PDF do KSeF — automatycznie tworzy poprawny plik FA3 XML z faktury PDF, obsługując wszystkie niuanse schematu, kodowanie UTF-8, zaokrąglenia i weryfikację NIP.

Odwiedź tablixa.app, żeby przetestować narzędzia za darmo.