Faktura strukturalna w KSeF to plik XML zgodny ze schematem FA(3) opublikowanym przez Ministerstwo Finansów, obowiązującym od 1 lutego 2026 r. Składa się z ośmiu elementów nadrzędnych: Naglowek, Podmiot1 (sprzedawca), Podmiot2 (nabywca), Podmiot3, PodmiotUpowazniony, Fa (treść faktury), DodatkowyOpis i Stopka. Dokument musi przejść walidację XSD przed nadaniem numeru KSeF.
Ten artykuł jest dla osób, które potrzebują rozumieć, jak działa schemat XML faktury KSeF — księgowych, programistów integracji, kontrolerów audytu. Zwykły przedsiębiorca tej wiedzy nie potrzebuje (program księgowy generuje XML automatycznie). Ale jeśli debugujesz odrzuty walidacji albo budujesz integrację — to czytasz właściwy materiał.
Czym dokładnie jest schemat FA(3)
FA(3) to trzecia wersja struktury logicznej faktury ustrukturyzowanej. Wcześniej obowiązywała FA(1) (dobrowolny KSeF 2022) i FA(2) (dobrowolny KSeF 2022-2024). Schemat FA(3) wszedł w życie 1 lutego 2026 r. jako obowiązujący standard dla wszystkich faktur wystawianych w obowiązkowym KSeF.
Schemat XSD FA(3) jest publikowany na ksef.podatki.gov.pl w sekcji „Struktury dokumentów XML". Każdy program księgowy lub system ERP musi go pobrać i używać do walidacji lokalnej przed wysyłką do KSeF. Walidacja odbywa się dwustopniowo: lokalnie (zgodność z XSD) i serwerowo (zgodność biznesowa, np. czy NIP istnieje w bazie podatników).
Osiem elementów nadrzędnych FA(3) — tabela
| Element | Status | Co zawiera | Specyfika FA(3) |
|---|---|---|---|
| Naglowek | Obligatoryjny | Dane techniczne wytworzenia faktury (kod formularza, wariant, data, identyfikator systemu) | Identyfikator wariantu „3" zamiast „2" |
| Podmiot1 | Obligatoryjny | Dane sprzedawcy (NIP, nazwa, adres) | Bez większych zmian wobec FA(2) |
| Podmiot2 | Obligatoryjny | Dane nabywcy | Nowe pola: JST (jednostka samorządu terytorialnego), GV (grupa VAT) |
| Podmiot3 | Fakultatywny | Strony trzecie (np. odbiorca usługi inny niż nabywca) | Maksymalnie 100 wystąpień |
| PodmiotUpowazniony | Opcjonalny | Przedstawiciele podatkowi, komornicy | Nowy typ „pracownik" dla rozliczeń wydatków służbowych |
| Fa | Obligatoryjny | Treść faktury (rodzaj, numer, daty, transakcje, stawki VAT) | Limit nazwy towaru/usługi 512 znaków (było 256) |
| DodatkowyOpis | Fakultatywny | Notki o transakcji, klauzule, dodatkowe informacje | Możliwość załączania ustrukturyzowanych załączników |
| Stopka | Fakultatywny | Informacje końcowe (np. numer zamówienia, dane korespondencyjne) | Bez większych zmian |
Co zmieniło się między FA(2) a FA(3)
Najważniejsze zmiany ze schemy FA(2) (dobrowolnej, 2022-2024) na FA(3) (obowiązkową od 1 lutego 2026):
- Limit znaków w nazwie towaru/usługi — z 256 do 512 znaków. To rozwiązuje typowy problem branż usługowych z długimi opisami.
- Numer rachunku bankowego — format do 34 znaków (IBAN międzynarodowy). FA(2) ograniczała się do polskiego formatu 26-znakowego.
- Termin płatności — można podać jako liczbę dni od daty wystawienia, nie tylko jako konkretną datę. Praktyczne dla faktur z odroczonym terminem zmieniającym się dynamicznie.
- Nowe pola w Podmiocie2 — JST (rozróżnienie jednostek samorządu terytorialnego) i GV (oznaczenie członków grupy VAT). Krytyczne dla rozliczeń z administracją publiczną.
- Załączniki ustrukturyzowane — możliwość dołączenia np. specyfikacji zamówienia w formie kolejnego pliku XML zgodnego z mini-schematem.
- Typ kontrahenta „pracownik" — w polu PodmiotUpowazniony, dla obsługi wydatków służbowych pracowników (delegacje, zakupy biurowe).
- Nowe kody VAT — rozszerzony zestaw oznaczeń stawek dla nietypowych transakcji (np. odwrotne obciążenie wewnątrzwspólnotowe, OSS).
- Lepsze wsparcie korekt — pole odwołania do faktury pierwotnej obsługuje numery KSeF poprzedniej faktury, niezależnie od jej schemy (FA(1), FA(2), FA(3)).
Jak wygląda przykładowy XML faktury FA(3)
Uproszczona struktura (bez wszystkich pól), żeby pokazać szkielet:
| Sekcja XML | Przykładowa zawartość |
|---|---|
| Naglowek | KodFormularza FA, WariantFormularza 3, DataWytworzeniaFa 2026-04-29T10:30:00, KodSystemowy FA |
| Podmiot1 | NIP 1234567890, Nazwa „Firma ABC sp. z o.o.", AdresPL z polami Ulica/KodPocztowy/Miejscowosc |
| Podmiot2 | NIP 0987654321, Nazwa „Klient XYZ", AdresPL, opcjonalnie JST lub GV |
| Fa | KodWaluty PLN, P_1 (data wystawienia), P_1M (miejsce), P_2 (numer faktury), P_6 (data sprzedaży), DaneFaktury (pozycje), Adnotacje (stawki VAT, sumy) |
| Stopka | Informacje (np. dane kontaktowe wystawcy, numer zamówienia od klienta) |
Pełen XML faktury VAT podstawowej (jedna pozycja, klient krajowy, stawka 23%) zajmuje typowo 4-8 KB. Faktury z wieloma pozycjami i adnotacjami — do 50 KB. KSeF akceptuje pliki do 5 MB, więc nawet bardzo rozbudowane faktury mieszczą się bezproblemowo.
Walidacja FA(3) — co system sprawdza
Walidacja XML faktury w KSeF odbywa się w trzech warstwach:
Warstwa 1 — XSD. Zgodność strukturalna z plikiem schematu. Sprawdzane: obecność elementów obligatoryjnych, typy danych (string, decimal, date), długości pól, liczność wystąpień (1, 0..1, 0..n). Błąd na tym poziomie zwraca komunikat typu „nieprawidłowy format pola DataWystawienia".
Warstwa 2 — biznesowa. Reguły poza XSD. Sprawdzane: czy NIP sprzedawcy jest aktywny w rejestrze, czy NIP nabywcy istnieje (dla krajowych), czy suma stawek VAT zgadza się z kwotami pozycji, czy data wystawienia nie jest przyszła, czy adnotacje są wewnętrznie spójne.
Warstwa 3 — uprawnień. Czy wystawca ma prawo do wystawienia faktury z tym NIP-em (jest właścicielem, członkiem zarządu, pełnomocnikiem). Sprawdzane przez certyfikat lub token w nagłówku żądania API.
Pozytywna walidacja na wszystkich trzech warstwach skutkuje nadaniem numeru KSeF i zwrotem potwierdzenia (UPO — urzędowe poświadczenie odbioru). Numer KSeF ma format YYYYMMDDXXXXXXXXXXXXXXXXX-XX, gdzie pierwsze 8 znaków to data, kolejne 17 to identyfikator unikalny, ostatnie 2 to suma kontrolna.
Faktury korygujące w FA(3)
Korekty są jednym z najczęstszych miejsc problemów integracyjnych. Reguły:
- Korekta wystawiona od 1 lutego 2026 r. musi używać schemy FA(3), niezależnie od schematu faktury pierwotnej.
- W polu odwołania do faktury pierwotnej podaje się numer KSeF (jeśli pierwotna była w systemie) lub numer własny (jeśli była poza KSeF — np. korekta faktury z grudnia 2025 r.).
- Korekta zerująca (in minus do 100% wartości) jest dopuszczalna i nie wymaga zgody nabywcy.
- Korekta in plus (zwiększająca wartość) jest dopuszczalna, ale w niektórych branżach wymaga zgody nabywcy zgodnie z umową cywilnoprawną.
Najczęstszy błąd: korekta wystawiona w dawnym programie księgowym, który generuje XML w schemie FA(2). System odrzuca z komunikatem „nieobsługiwany wariant formularza". Rozwiązanie: aktualizacja programu lub ręczna konwersja XML do FA(3).
Specyfika faktur walutowych w FA(3)
Faktury wystawione w walucie innej niż PLN wymagają w FA(3) szczególnej uwagi. Pole KodWaluty obsługuje wszystkie kody ISO 4217 (EUR, USD, GBP, CHF i inne). Dla każdej pozycji podaje się kwoty w walucie obcej oraz przeliczenie na PLN według kursu zgodnego z art. 31a ustawy o VAT — czyli średni kurs NBP z ostatniego dnia roboczego poprzedzającego datę powstania obowiązku podatkowego.
System nie waliduje poprawności kursu (NBP nie jest podpięte do KSeF). Jeśli wpiszesz błędny kurs, faktura przejdzie walidację, ale problem ujawni się przy pierwszej kontroli JPK_VAT, gdy KAS porówna kurs z bazą NBP.
Drugi częsty problem: zaokrąglenia. Stawka VAT 23% przeliczana z EUR na PLN powoduje rozbieżności groszowe. KSeF akceptuje tolerancję 1 grosza na pozycję — większe odchylenia zwracają błąd „suma kwot VAT niezgodna". Programy księgowe radzą sobie z tym automatycznie, ale dla integracji własnej trzeba pilnować algorytmu zaokrągleń.
Faktury zaliczkowe i końcowe rozliczające zaliczki
FA(3) obsługuje cykl zaliczka → faktura końcowa przez specjalne pola w sekcji Fa. Faktura zaliczkowa ma flagę RodzajFaktury = ZAL (zaliczka) lub POZ (pozostała). Faktura końcowa rozliczająca zaliczki używa pola FakturaZaliczkowaCzesciowa z odwołaniem do numerów KSeF wcześniejszych zaliczek.
Sumaryczna kwota faktury końcowej musi się zgadzać z różnicą wartości całej transakcji minus suma zaliczek. KSeF tego nie waliduje wprost (bo nie wie, ile było zaliczek), ale spójność danych jest kluczowa dla rozliczenia VAT — pierwszy JPK ujawni rozbieżności.
FA(3) a integracje — schemat XSD i biblioteki
Dla deweloperów: oficjalny schemat XSD FA(3) dostępny na ksef.podatki.gov.pl w sekcji Struktury dokumentów. Poza schematem MF udostępnia: specyfikację OpenAPI (Swagger) opisującą endpointy KSeF, biblioteki SDK dla Java 11+ i .NET 6+, przykładowe XML-e faktur pokazujące różne scenariusze (krajowa, eksport, korekta, zaliczkowa, walutowa).
Walidacja lokalna XML przeciwko XSD jest darmowa i nielimitowana — można ją wykonywać w nieskończoność na własnej maszynie. Walidacja biznesowa wymaga połączenia z KSeF (testowym lub produkcyjnym) i jest limitowana w środowisku produkcyjnym (throttling).
Najczęstsze błędy walidacji FA(3) i ich rozwiązania
- „Nieprawidłowy NIP nabywcy" — sprawdź białą listę podatników VAT, czy NIP jest aktywny. Czasem klient zmienił status (np. wykreślenie z VAT) i jego NIP nie waliduje się.
- „Suma kwot VAT niezgodna" — typowy problem z zaokrągleniami. KSeF wymaga zaokrąglenia do groszy (2 miejsc po przecinku) z konsekwentną metodą (HALF_UP). Programy używające innej metody zaokrąglania dają drobne rozbieżności.
- „Wariant formularza nie jest obsługiwany" — używasz starszej wersji XSD niż FA(3). Aktualizuj.
- „Brak elementu obligatoryjnego: P_1" — pominięta data wystawienia. Sprawdź mapowanie z systemu źródłowego.
- „Nieprawidłowy format daty" — KSeF wymaga ISO 8601 (YYYY-MM-DD lub YYYY-MM-DDTHH:MM:SS). Format polski (DD-MM-YYYY) jest niezgodny.
Załączniki ustrukturyzowane — nowość FA(3)
Schemat FA(3) wprowadził możliwość dołączania do faktury załączników w formie ustrukturyzowanej. To istotna zmiana wobec FA(2), gdzie ewentualne specyfikacje, listy zamówień czy protokoły musiały krążyć poza systemem.
Załącznik dołączany jest jako odrębny fragment XML wewnątrz głównego dokumentu, z własną walidacją zgodną z mini-schemą publikowaną przez MF. Praktyczne zastosowania: rozbicie pozycji faktury na szczegółowe linie (np. każda paleta z osobnym numerem), specyfikacja techniczna usługi, protokół odbioru robót budowlanych.
Limit rozmiaru: załączniki wliczają się do całkowitego limitu 5 MB faktury. Format: XML zgodny ze schemą załącznika, nie inne formaty (PDF, DOCX). Jeśli potrzebujesz dołączyć dokument w innym formacie — robisz to poza KSeF, mailem lub przez własny system, z odwołaniem w polu Stopka.
Adnotacje i kody specjalne w FA(3)
Sekcja Adnotacje w polu Fa to miejsce na wszystkie szczególne oznaczenia faktury: split payment (MPP), odwrotne obciążenie, eksport, wewnątrzwspólnotowa dostawa towarów (WDT), procedura VAT marża, mechanizm OSS. Każde z tych oznaczeń ma swoje pole boolean (Tak/Nie) i wpływa na prezentację faktury.
Najczęściej używane adnotacje:
- P_18A (MPP) — mechanizm podzielonej płatności. Obowiązkowy dla niektórych transakcji powyżej 15 tys. zł na towary z załącznika 15 ustawy o VAT. Sprawdź zgodność z artykułem o split payment.
- P_19A (Odwrotne obciążenie) — dla branży budowlanej i niektórych usług elektronicznych B2B.
- P_22 (Procedura VAT marża) — dla biur podróży, sprzedawców towarów używanych. Zobacz też poradnik faktury VAT marża.
- P_23 (Faktura uproszczona) — dla transakcji do 450 zł brutto, krótszy zestaw danych.
- WDT/WNT — wewnątrzwspólnotowa dostawa/nabycie towarów. Pole specjalne dla transakcji UE.
Każda adnotacja zaznaczona w XML musi być uzasadniona merytorycznie. KSeF nie weryfikuje, czy oznaczenie MPP jest zasadne (czy faktycznie towar jest z załącznika 15) — to robi pierwsza kontrola skarbowa. Niewłaściwe oznaczenie to potencjalny problem przy kontroli JPK.