Faktura ustrukturyzowana XML to serce Krajowego Systemu e-Faktur. To nie zwykły dokument – to precyzyjnie zdefiniowany zestaw danych w formacie XML, zgodny ze schematem FA(2) opracowanym przez Ministerstwo Finansów. Zrozumienie tego formatu jest kluczowe dla każdego, kto wdraża lub zarządza procesem fakturowania w firmie.
W tym artykule wyjaśniamy, czym dokładnie jest faktura ustrukturyzowana XML, jak wygląda jej struktura, jakie pola są obowiązkowe i opcjonalne, oraz jak zapewnić poprawność generowanych dokumentów. To wiedza niezbędna dla programistów, wdrożeniowców i świadomych właścicieli firm.
Czym jest XML i dlaczego KSeF go używa
XML (Extensible Markup Language) to format zapisu danych w postaci ustrukturyzowanego tekstu. Dane są opisane znacznikami (tagami), które definiują ich typ i relacje. To sprawia, że XML jest czytelny zarówno dla ludzi, jak i dla maszyn.
KSeF używa XML, ponieważ umożliwia on jednoznaczną interpretację danych. W przeciwieństwie do PDF-a, gdzie dane są wizualne (obraz tekstu), XML przechowuje dane w formie ustrukturyzowanej – system wie, że NIP to NIP, a kwota brutto to kwota brutto.
Ta ustrukturyzowana forma umożliwia automatyczne przetwarzanie: walidację poprawności, import do systemu księgowego, agregację danych do JPK_VAT, analizę i raportowanie. To fundament automatyzacji KSeF.
Schemat FA(2) – mapa faktury ustrukturyzowanej
Schemat FA(2) to plik XSD (XML Schema Definition) opublikowany przez Ministerstwo Finansów, który definiuje strukturę faktury ustrukturyzowanej. Określa: jakie pola może zawierać faktura, jakie typy danych są dozwolone, które pola są obowiązkowe, a które opcjonalne.
Schemat jest aktualizowany przez MF w miarę zmian przepisów. Każda wersja schematu jest identyfikowana numerem (np. FA(2)). System generujący faktury musi obsługiwać aktualną wersję schematu.
Schemat FA(2) jest publicznie dostępny na stronie Ministerstwa Finansów i na portalu developer.mf.gov.pl. Warto go studiować, nawet jeśli nie jesteś programistą – zrozumienie struktury pomaga w konfiguracji systemu i diagnozowaniu problemów.
Główne sekcje faktury ustrukturyzowanej
Faktura ustrukturyzowana XML składa się z kilku głównych sekcji, z których każda zawiera grupę powiązanych danych.
- Naglowek – wersja schematu, rodzaj faktury, kod systemu podatkowego
- Podmiot1 – dane sprzedawcy: NIP, nazwa pełna, adres, dane kontaktowe
- Podmiot2 – dane nabywcy: NIP, nazwa, adres (opcjonalnie dane kontaktowe)
- Podmiot3 – dane dodatkowego podmiotu (np. faktor, przedstawiciel podatkowy)
- Fa – podstawowe dane faktury: numer, data wystawienia, data sprzedaży, waluta, typ transakcji
- FaWiersze – pozycje faktury: opisy towarów/usług, ilości, ceny, stawki VAT, kwoty
- Stopka – podsumowania: kwoty VAT wg stawek, kwota należności ogółem
- Zaliczka – dane dotyczące faktur zaliczkowych (jeśli dotyczy)
- Adnotacje – dodatkowe oznaczenia: MPP, TP, procedury specjalne
Pola obowiązkowe – co musi zawierać każda faktura
Nie wszystkie pola w schemacie FA(2) są obowiązkowe. Część jest wymagana zawsze, część tylko w określonych scenariuszach (np. faktura korygująca, faktura walutowa). Oto najważniejsze pola obowiązkowe.
W sekcji Podmiot1 (sprzedawca): NIP, pełna nazwa. W sekcji Podmiot2 (nabywca): NIP (dla B2B), nazwa. W sekcji Fa: numer faktury, data wystawienia, kod waluty. W sekcji FaWiersze: przynajmniej jedna pozycja z opisem, ilością, ceną, stawką VAT.
Brak obowiązkowego pola powoduje odrzucenie faktury przez KSeF z odpowiednim kodem błędu. Dlatego tak ważne jest, aby system automatyzacji poprawnie mapował wszystkie wymagane dane. Sprawdź integrację z KSeF, aby zapewnić poprawność.
Pola opcjonalne – kiedy je stosować
Pola opcjonalne służą do przekazania dodatkowych informacji, które nie są wymagane prawem, ale mogą być użyteczne dla nabywcy lub systemu przetwarzającego fakturę.
Przykłady pól opcjonalnych: numer zamówienia (KodTowaru – przydatny do automatycznego kojarzenia z zamówieniami), numer rachunku bankowego (WynijPlatn – ułatwia nabywcy przelew), opis dodatkowy pozycji (DodatkowyOpis – szczegóły usługi).
Kody GTU (Grupy Towarów i Usług) i oznaczenia procedur podatkowych (TP, SW, EE itp.) są opcjonalne w schemacie XML, ale obowiązkowe z punktu widzenia przepisów podatkowych. Ich brak nie spowoduje odrzucenia faktury przez KSeF, ale może skutkować problemami przy kontroli skarbowej.
Przykładowa struktura XML faktury
Poniżej uproszczony schemat faktury ustrukturyzowanej, pokazujący hierarchię elementów. Rzeczywisty plik XML jest bardziej rozbudowany, ale ta struktura oddaje logikę organizacji danych.
Element główny (Faktura) zawiera atrybuty wersji schematu. Wewnątrz niego znajdują się sekcje Podmiot1, Podmiot2, Fa z podelementa mi FaWiersze. Każdy FaWiersz opisuje jedną pozycję faktury ze wszystkimi wymaganymi danymi.
Ważne: XML jest wrażliwy na kolejność elementów i wielkość liter. Element
Walidacja XML – jak sprawdzić poprawność
Walidacja XML to proces sprawdzania, czy plik jest zgodny ze schematem XSD. Obejmuje dwa poziomy: walidację strukturalną (czy XML jest poprawny składniowo) i walidację schematową (czy zawiera wymagane pola w odpowiednim formacie).
Narzędzia do walidacji: walidator dostępny na portalu KSeF (online), biblioteki programistyczne (libxml2, javax.xml), narzędzia wbudowane w IDE (Visual Studio, IntelliJ). Warto walidować lokalnie przed wysyłką do KSeF.
Częste błędy walidacji: brak wymaganych elementów, nieprawidłowy format NIP (z myślnikami zamiast bez), kwota z więcej niż 2 miejscami po przecinku, data w niepoprawnym formacie (wymagany YYYY-MM-DD), nieprawidłowa suma VAT.
Faktury korygujące w XML
Faktura korygująca ma ten sam schemat XML co zwykła faktura, ale z dodatkowym elementem identyfikującym fakturę korygowaną. Element Korekta zawiera: numer referencyjny KSeF faktury pierwotnej, przyczynę korekty, korygowane wartości.
Korekta może dotyczyć dowolnego pola: danych nabywcy, pozycji, kwot. W XML faktury korygującej przedstawia się dane po korekcie, a nie różnicę. System nabywcy musi sam obliczyć różnicę na podstawie porównania z fakturą pierwotną.
Ważna zasada: w KSeF faktura korygująca jest niezależnym dokumentem z własnym numerem referencyjnym. Powiązanie z fakturą pierwotną odbywa się przez numer referencyjny, nie przez modyfikację oryginalnego dokumentu.
Encoding i znaki specjalne
Pliki XML KSeF muszą używać kodowania UTF-8, które obsługuje polskie znaki diakrytyczne (ą, ę, ó, ś, ż, ź, ć, ń, ł). Brak poprawnego kodowania to częsta przyczyna błędów, szczególnie przy generowaniu XML z systemów używających innego kodowania (np. Windows-1250).
Znaki specjalne w XML muszą być escapowane: & jako &, < jako <, > jako >, " jako ". Nazwy firm i opisy pozycji często zawierają te znaki, więc system musi je poprawnie obsługiwać.
Długość pól jest ograniczona schematem. Na przykład nazwa pozycji może mieć maksymalnie 256 znaków. Opisy dłuższe muszą być skracane lub umieszczane w polach dodatkowych.
Narzędzia do pracy z XML faktur
Dla programistów: biblioteki do parsowania XML (lxml w Python, javax.xml w Java, System.Xml w C#), walidatory XSD, narzędzia do generowania klas z schematu (xjc, xmlschema).
Dla użytkowników biznesowych: podgląd XML w przeglądarce, edytory XML z podświetlaniem składni (Notepad++, VS Code), narzędzia online do wizualizacji XML na czytelną formę.
Dla testowania: środowisko sandbox KSeF z walidatorem, generatory testowych plików XML, narzędzia do porównywania plików XML (diff). Więcej o testowaniu w artykule o integracji API KSeF.
Podsumowanie
Faktura ustrukturyzowana XML to techniczny fundament KSeF. Zrozumienie jej struktury, wymaganych pól i reguł walidacji jest kluczowe dla prawidłowego wdrożenia automatyzacji fakturowania.
Dla większości firm znajomość schematu XML nie jest konieczna na co dzień – system automatyzacji KSeF generuje poprawne pliki automatycznie. Jednak wiedza o strukturze pomaga w diagnozowaniu problemów i świadomym korzystaniu z systemu. Sprawdź też nasze strony o e-fakturach dla firm i elektronicznych fakturach VAT.