Faktura ustrukturyzowana w formacie XML to fundament całego Krajowego Systemu e-Faktur. To właśnie ten format — ściśle zdefiniowany przez Ministerstwo Finansów — decyduje o tym, jakie dane musi zawierać każda faktura przesyłana do KSeF. Dla wielu przedsiębiorców i księgowych pojęcie faktury ustrukturyzowanej brzmi abstrakcyjnie, jednak w praktyce oznacza ono precyzyjnie opisany dokument elektroniczny, w którym każde pole ma swoje określone miejsce, typ danych i reguły walidacji. Zrozumienie struktury XML faktury jest kluczowe zarówno dla programistów budujących integracje z KSeF API, jak i dla osób odpowiedzialnych za poprawność danych fakturowych w firmie. W tym artykule dokładnie omawiamy schemat FA(2) — od nagłówka dokumentu, przez dane stron transakcji, aż po pozycje fakturowe i pola opcjonalne. Poznasz wymagania dotyczące walidacji, najczęstsze błędy i praktyczne wskazówki pozwalające uniknąć odrzucenia faktury przez system.
Czym jest faktura ustrukturyzowana i dlaczego XML?
Faktura ustrukturyzowana to elektroniczny dokument handlowy zapisany w formacie XML (eXtensible Markup Language), którego struktura jest ściśle zdefiniowana przez schemat XSD opublikowany przez Ministerstwo Finansów. W odróżnieniu od faktury PDF czy papierowej, faktura XML nie jest przeznaczona do bezpośredniego odczytu przez człowieka — jest dokumentem maszynowo czytelnym, co umożliwia automatyczne przetwarzanie.
Wybór formatu XML nie jest przypadkowy. XML to standard szeroko stosowany w administracji publicznej i systemach B2B na całym świecie. Pozwala na jednoznaczne opisanie każdego elementu faktury, walidację zgodności z wymaganiami oraz bezproblemową wymianę danych między różnymi systemami informatycznymi. Dzięki temu KSeF może automatycznie przetwarzać miliony faktur bez udziału człowieka.
Schemat FA(2) — główny standard faktury w KSeF
Ministerstwo Finansów opublikowało schemat XSD o nazwie FA(2), który definiuje strukturę faktury ustrukturyzowanej. Schemat ten określa wszystkie elementy, ich typy danych, wymagalność oraz reguły walidacji. Każda faktura przesyłana do KSeF musi być zgodna z tym schematem — w przeciwnym razie zostanie odrzucona.
Schemat FA(2) jest regularnie aktualizowany — nowe wersje mogą dodawać pola, modyfikować reguły walidacji lub wprowadzać obsługę nowych typów transakcji. Dlatego firmy i deweloperzy muszą na bieżąco śledzić zmiany i aktualizować swoje systemy. Aktualną wersję schematu można pobrać ze strony Ministerstwa Finansów lub z repozytorium na platformie ePUAP.
Struktura dokumentu XML — elementy główne
Dokument XML faktury ustrukturyzowanej składa się z kilku głównych sekcji, z których każda odpowiada za określoną grupę danych. Zrozumienie tej hierarchii jest kluczowe dla prawidłowego generowania faktur.
Głównym elementem (root) dokumentu jest Faktura, który zawiera przestrzeń nazw (namespace) zgodną ze schematem FA(2). Wewnątrz tego elementu znajdują się sekcje opisujące nagłówek faktury, dane sprzedawcy i nabywcy, pozycje fakturowe, podsumowania kwotowe oraz opcjonalne załączniki i adnotacje.
- Naglowek — informacje o typie faktury, dacie wystawienia, walucie
- Podmiot1 — dane sprzedawcy (NIP, nazwa, adres)
- Podmiot2 — dane nabywcy (NIP, nazwa, adres)
- Fa — właściwa treść faktury z pozycjami i kwotami
- Stopka — opcjonalne informacje dodatkowe
Sekcja nagłówkowa — metadane faktury
Sekcja nagłówkowa (Naglowek) zawiera metadane dokumentu, które identyfikują go w systemie KSeF. Do najważniejszych pól należą: kod formularza (zawsze KodFormularza=FA), wariant schematu, wersja schematu, data wytworzenia dokumentu oraz system wystawiający fakturę.
Nagłówek zawiera także informacje o rodzaju faktury — czy jest to faktura pierwotna, korekta, faktura zaliczkowa czy faktura końcowa rozliczająca zaliczki. Poprawne oznaczenie rodzaju faktury jest krytyczne, ponieważ determinuje dalszą logikę przetwarzania dokumentu w KSeF i w systemach odbiorcy.
- KodFormularza — zawsze FA dla faktur
- WariantFormularza — numer wariantu schematu
- WersjaSchemy — wersja schematu XSD
- DataWytworzeniaFa — data i czas utworzenia dokumentu XML
- SystemInfo — identyfikator systemu wystawiającego
Dane stron transakcji — Podmiot1 i Podmiot2
Sekcje Podmiot1 (sprzedawca) i Podmiot2 (nabywca) zawierają pełne dane identyfikacyjne stron transakcji. Dla podmiotów krajowych kluczowym identyfikatorem jest NIP, który musi być podany w formacie 10-cyfrowym bez kresek i spacji. Dla podmiotów zagranicznych stosuje się inne identyfikatory (np. numer VAT UE).
Dane adresowe obejmują: kod kraju, województwo, powiat, gminę, miejscowość, ulicę, numer domu, numer lokalu i kod pocztowy. Nie wszystkie pola adresowe są wymagane — np. numer lokalu jest opcjonalny. Jednak im pełniejsze dane adresowe, tym mniejsze ryzyko problemów z identyfikacją kontrahenta. Warto pamiętać, że dane w KSeF muszą być spójne z danymi w rejestrze REGON i rejestrze VAT.
Pozycje fakturowe — serce dokumentu XML
Sekcja Fa zawiera właściwą treść faktury, w tym pozycje fakturowe (FaWiersz). Każda pozycja opisuje pojedynczy towar lub usługę i musi zawierać określone pola: numer wiersza, nazwę towaru/usługi, jednostkę miary, ilość, cenę jednostkową, wartość netto, stawkę VAT oraz kwotę VAT.
Pozycje fakturowe podlegają ścisłej walidacji arytmetycznej — iloczyn ceny jednostkowej i ilości musi odpowiadać wartości netto z dokładnością do grosza. Podobnie suma kwot VAT z pozycji musi zgadzać się z podsumowaniem VAT w sekcji zbiorczej. Nawet minimalna rozbieżność groszowa spowoduje odrzucenie faktury przez system KSeF.
- NrWierszaFa — numer pozycji (sekwencyjny od 1)
- P_7 — nazwa towaru lub usługi
- P_8A — jednostka miary
- P_8B — ilość
- P_9A — cena jednostkowa netto
- P_11 — wartość netto pozycji
- P_12 — stawka VAT (np. 23, 8, 5, 0, zw, oo, np)
- P_11A–P_11E — wartości netto wg stawek VAT
Podsumowania kwotowe i stawki VAT
Faktura XML musi zawierać sekcję podsumowań, w której agregowane są kwoty z poszczególnych pozycji. Podsumowanie obejmuje: łączną wartość netto, łączną kwotę VAT i łączną wartość brutto, z podziałem na poszczególne stawki VAT.
Schemat FA(2) definiuje osobne pola dla każdej stawki VAT obowiązującej w Polsce: 23%, 8%, 5%, 0% (z prawem i bez prawa do odliczenia), zwolniona (zw), odwrotne obciążenie (oo) i niepodlegająca (np). Prawidłowe przypisanie kwot do odpowiednich stawek jest kluczowe dla poprawnych rozliczeń VAT i generowania plików JPK_VAT.
Pola opcjonalne — kiedy i jak je stosować
Schemat FA(2) zawiera wiele pól opcjonalnych, które nie są wymagane przy standardowej fakturze, ale stają się konieczne w specyficznych scenariuszach. Znajomość tych pól pozwala prawidłowo obsłużyć transakcje nietypowe.
Do najważniejszych pól opcjonalnych należą: oznaczenia procedur szczególnych (np. mechanizm podzielonej płatności, transakcje trójstronne, dostawy łańcuchowe), informacje o zaliczkach i rozliczeniach, dane dotyczące waluty obcej i kursu przeliczeniowego, a także adnotacje i uwagi dodatkowe. Nieprawidłowe użycie pól opcjonalnych — np. pominięcie oznaczenia MPP, gdy jest ono wymagane — może skutkować sankcjami podatkowymi.
- Mechanizm podzielonej płatności (MPP) — obowiązkowe oznaczenie dla transakcji powyżej 15 000 zł
- Waluta obca — kurs przeliczeniowy i źródło kursu
- Faktura zaliczkowa — dane zamówienia i wpłacone kwoty
- Transakcje wewnątrzwspólnotowe — dodatkowe identyfikatory VAT UE
- Odwrotne obciążenie — oznaczenie i podstawa prawna
Walidacja XSD — jak uniknąć odrzucenia faktury
Walidacja XML względem schematu XSD to pierwszy etap kontroli jakości faktury. KSeF wykonuje tę walidację automatycznie — każda faktura niezgodna ze schematem jest natychmiast odrzucana. Dlatego zdecydowanie zaleca się walidację po stronie klienta, jeszcze przed wysłaniem dokumentu do API.
Walidacja XSD sprawdza: obecność wymaganych elementów, poprawność typów danych (np. NIP musi być 10-cyfrowy, daty w formacie YYYY-MM-DD), dopuszczalność wartości (np. stawka VAT musi być jedną z predefiniowanych wartości) oraz strukturę hierarchiczną dokumentu. Narzędzia takie jak Finito Pro oferują wbudowaną walidację XSD, co pozwala wychwycić błędy przed wysłaniem.
Korekty faktur w formacie XML
Faktur wystawionych w KSeF nie można edytować ani usuwać — jedynym sposobem poprawienia błędu jest wystawienie faktury korygującej. Korekta w formacie XML ma specyficzną strukturę — musi odwoływać się do numeru KSeF faktury korygowanej i precyzyjnie wskazywać, które pola uległy zmianie.
Schemat FA(2) obsługuje różne typy korekt: korektę danych (np. zmiana nazwy nabywcy), korektę pozycji (zmiana ilości, ceny lub stawki VAT), korektę zbiorczą (korekta wielu pozycji jednocześnie) oraz korektę do zera (pełne wycofanie transakcji). Każdy typ korekty wymaga prawidłowego wypełnienia odpowiednich pól identyfikujących pierwotną fakturę.
- Korekta danych identyfikacyjnych — zmiana NIP, nazwy lub adresu
- Korekta pozycji — zmiana ilości, ceny, stawki VAT
- Korekta zbiorcza — dla wielu faktur z danego okresu
- Korekta do zera — pełne wycofanie transakcji
- Pole PrzyczynaKorekty — obowiązkowe uzasadnienie korekty
Narzędzia do pracy z XML faktur — edytory i walidatory
Do pracy z fakturami XML przydatne są specjalistyczne narzędzia. Dla programistów podstawowym narzędziem jest edytor XML z obsługą XSD — np. Oxygen XML Editor, Visual Studio Code z rozszerzeniem XML, lub XMLSpy. Narzędzia te oferują podświetlanie składni, autouzupełnianie na podstawie schematu i walidację w czasie rzeczywistym.
Dla osób nietechnicznych istnieją programy do KSeF, które ukrywają złożoność XML za przyjaznym interfejsem graficznym. Użytkownik wypełnia formularz, a program automatycznie generuje poprawny dokument XML. To rozwiązanie jest optymalne dla mniejszych firm, które nie potrzebują własnej integracji API, ale chcą mieć kontrolę nad treścią faktur.
Podsumowanie
Faktura ustrukturyzowana XML to nie tylko wymóg techniczny — to nowy standard komunikacji handlowej w Polsce. Zrozumienie schematu FA(2), struktury dokumentu i reguł walidacji jest fundamentem sprawnej pracy z KSeF. Kluczowe elementy to: poprawna struktura nagłówka i danych stron, precyzyjne pozycje fakturowe ze spójną arytmetyką, prawidłowe podsumowania kwotowe oraz właściwe użycie pól opcjonalnych. Walidacja XSD po stronie klienta pozwala uniknąć odrzuceń przez system. Niezależnie od tego, czy generujesz XML programistycznie, czy korzystasz z gotowego oprogramowania, znajomość struktury dokumentu pozwala szybko diagnozować problemy i zapewniać zgodność z wymogami. Sprawdź także nasz poradnik o integracji z KSeF API, aby dowiedzieć się, jak automatycznie wysyłać i odbierać faktury XML.