Faktura ustrukturyzowana w Krajowym Systemie e-Faktur (KSeF) to dokument w formacie XML zgodny ze schematem opublikowanym przez Ministerstwo Finansów, obowiązkowy od 2026 roku dla wszystkich podatników VAT w Polsce.
Ściśle zdefiniowana struktura XML umożliwia automatyczną walidację, odczyt i przetwarzanie dokumentów w systemach finansowo-księgowych, co znacząco ogranicza błędy i przyspiesza obieg dokumentów.
Wstęp do KSeF i faktury ustrukturyzowanej
Krajowy System e-Faktur (KSeF) wymaga, aby faktury były wystawiane w formie e-faktur o z góry określonej strukturze XML, opisanej w schematach takich jak FA(2) czy nowszy FA(3), które definiują hierarchię elementów, pola obowiązkowe i formaty danych.
Plik XML musi być zgodny z XSD (XML Schema Definition) z Centralnego Repozytorium Wzorów (CRD), co gwarantuje poprawność strukturalną i matematyczną (np. spójność sum netto, VAT i brutto). Błędy w strukturze skutkują odrzuceniem faktury przez KSeF bez możliwości ręcznej korekty.
Dla programistów kluczowe jest zrozumienie przestrzeni nazw, typów danych pól oraz walidacji i podpisu przed wysyłką przez API KSeF 2.0.
Główna struktura pliku XML
Korzeń dokumentu to element <Faktura> z przestrzenią nazw xmlns="http://crd.gov.pl/wzor/2023/06/29/12648/" (wartość zależna od wersji schematu, np. FA(3)). Dokument składa się z czterech głównych sekcji: Nagłówek, Podmiot1 (sprzedawca), Podmiot2 (nabywca) oraz Fa (treść faktury z pozycjami i podsumowaniami). Oto uproszczony przykład pliku XML zgodnego ze schematem FA(2):
<?xml version="1.0" encoding="UTF-8"?>
<Faktura xmlns="http://crd.gov.pl/wzor/2023/06/29/12648/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Naglowek>
<KodFormularza kodSystemowy="FA (2)" wersjaSchemy="1-0E">FA</KodFormularza>
<WariantFormularza>2</WariantFormularza>
<DataWytworzeniaFa>2026-03-01T10:00:00</DataWytworzeniaFa>
<SystemInfo>MojSystem v1.0</SystemInfo>
</Naglowek>
<!-- Dane sprzedawcy i nabywcy – szczegóły poniżej -->
<Podmiot1>...</Podmiot1>
<Podmiot2>...</Podmiot2>
<Fa>
<!-- Pozycje i podsumowania – szczegóły poniżej -->
</Fa>
</Faktura>
Kodowanie musi być UTF-8, a daty w formacie ISO 8601 (np. YYYY-MM-DDTHH:MM:SS).
Szczegółowy opis sekcji Nagłówek
Sekcja <Naglowek> zawiera metadane identyfikujące fakturę i oprogramowanie:
<KodFormularza>– kodFAz atrybutamikodSystemowy="FA (2)"iwersjaSchemy="1-0E";<WariantFormularza>– np.2dla standardowej faktury sprzedaży;<DataWytworzeniaFa>– moment utworzenia XML (format ISO 8601);<SystemInfo>– nazwa i wersja oprogramowania wysyłającego (pole wymagane przez walidację).
Ta sekcja jest walidowana jako pierwsza – błędy blokują dalsze przetwarzanie dokumentu.
Dane podmiotów – Podmiot1, Podmiot2 i Podmiot3
Podmiot1 – sprzedawca (obowiązkowy)
Zawiera pełne dane identyfikacyjne i adresowe. Przykładowa struktura:
<Podmiot1>
<DaneIdentyfikacyjne>
<NIP>1234567890</NIP>
<Nazwa>Firma ABC Sp. z o.o.</Nazwa>
</DaneIdentyfikacyjne>
<Adres>
<KodKraju>PL</KodKraju>
<Miejscowosc>Warszawa</Miejscowosc>
<!-- Ulica, numer, kod pocztowy itp. -->
</Adres>
</Podmiot1>
Obowiązkowe pola obejmują: NIP (10 cyfr), nazwę, kod kraju (ISO 3166-1 alpha-2, np. PL) i miejscowość. Waliduj format NIP i spójność danych, a status kontrahenta weryfikuj dodatkowymi usługami (np. wykaz podatników VAT).
Podmiot2 – nabywca (obowiązkowy)
Struktura analogiczna do sprzedawcy; jeśli nabywca nie posiada NIP, stosuje się inne identyfikatory (np. PESEL lub REGON) zgodnie ze schematem.
Podmiot3 – dodatkowe podmioty (opcjonalny)
Wykorzystywany dla faktora, płatnika lub wskazanych reprezentantów; zawiera odpowiednio NIP, nazwę i adres.
Sekcja Fa – treść faktury i pozycje
Główna część dokumentu zawiera parametry transakcji (m.in. <KodWaluty> w formacie ISO 4217, np. PLN), pozycje oraz wartości podsumowujące.
Poniżej wybrane pola P_x i ich znaczenie:
| Pole | Opis | Format/przykład |
|---|---|---|
| P_1 | Data wystawienia | 2026-03-01 |
| P_2 | Numer faktury | FV/2026/03/001 |
| P_6 | Data sprzedaży | 2026-03-01 |
| P_15 | Kwota brutto całkowita | 123.00 |
Pozycje faktury – FaWiersz
Każda pozycja towaru/usługi jest reprezentowana przez element <FaWiersz>, numerowany rosnąco przez <NrWierszaFa>. Przykład zapisu jednej pozycji:
<FaWiersz>
<NrWierszaFa>1</NrWierszaFa>
<P_7>Usługa programistyczna</P_7> <!-- Nazwa -->
<P_8A>szt</P_8A> <!-- Jednostka miary -->
<P_8B>1</P_8B> <!-- Ilość -->
<P_9A>100.00</P_9A> <!-- Cena jednostkowa netto -->
<P_10>100.00</P_10> <!-- Wartość netto -->
<P_12>23</P_12> <!-- Stawka VAT: 23, 8, 5, 0, ZW -->
</FaWiersz>
KSeF weryfikuje spójność sum i kontrolnie wylicza agregaty, m.in. P_13_x (podstawa opodatkowania dla stawki x) oraz P_14_x (kwota VAT). Kwoty należy podawać z precyzją do dwóch miejsc po przecinku.
Typy danych i formaty pól
Zgodnie z dokumentacją Ministerstwa Finansów, stosuj następujące typy i formaty:
- NIP – 10 cyfr (string);
- kwoty – typ decimal z precyzją 2 (np.
123.00); - stawki VAT – integer (23, 8, 5, 0) lub
ZW(zwolnienie); - daty –
YYYY-MM-DDlubYYYY-MM-DDTHH:MM:SS; - nazwy – string, maks. 240 znaków.
Pola opcjonalne (np. rabaty, akcyza) zależą od wariantu formularza.
Walidacja i błędy
Przed wysyłką przeprowadź walidację XML względem XSD z CRD (aktualne pliki pobierzesz z serwisu crd.gov.pl). Najczęstsze przyczyny odrzucenia to:
- niezgodność sum matematycznych,
- błędny identyfikator podatkowy lub niepoprawna przestrzeń nazw,
- brakujące pola obowiązkowe.
Po poprawnej walidacji i przyjęciu dokumentu przez KSeF system zwraca UPO (Urzędowe Poświadczenie Odbioru) z numerem KSeF.
Wskazówki dla programistów
Najważniejsze praktyki wdrożeniowe:
- Generowanie XML – użyj bibliotek do mapowania obiektów na XML, np. JAXB (Java), lxml (Python) lub XmlSerializer (.NET);
- Integracja z API – realizuj wysyłkę zgodnie z dokumentacją API KSeF 2.0; autoryzacja odbywa się z użyciem tokenu sesyjnego oraz podpisu (np. kwalifikowanego, Profilu Zaufanego lub pieczęci), a nie standardowego OAuth;
- Obsługa wariantów – FA(2) dla standardowych przypadków, FA(3) dla rozszerzonych (np. korekty, WNT);
- Testowanie – korzystaj ze środowiska testowego KSeF (np. test.ksef.gov.pl) oraz zestawów przykładowych dokumentów;
- Kontrola matematyczna – przeliczaj wartości i agregaty po stronie aplikacji przed serializacją, aby zminimalizować błędy walidacyjne.
Implementacja zgodna z najnowszym schematem (np. FA(3)) i stałe monitorowanie zmian w CRD zapewnią bezproblemowe działanie integracji w przyszłych aktualizacjach.
