Struktura XML FA(3): przewodnik po KSeF dla programistów

Struktura XML FA(3) to schemat używany przez KSeF dla faktur ustrukturyzowanych wystawianych od 1 lutego 2026 roku. Należy traktować ją jako trzy odrębne umowy: XSD określa budowę XML, polskie przepisy VAT — wymagane dane, a transakcja — właściwe gałęzie warunkowe. Przed wysyłką trzeba sprawdzić wszystkie trzy poziomy. O przyjęciu świadczy końcowy status KSeF, nie odpowiedź na przesłanie pliku.

To przewodnik techniczny, nie porada podatkowa. Sposób rozliczenia VAT i ustawowo wymagane dane każdego typu faktury warto potwierdzić ze specjalistą.

Czym jest struktura XML FA(3)?

FA(3) to struktura logiczna faktury ustrukturyzowanej opublikowana przez Ministerstwo Finansów. Nie jest układem PDF ani szablonem wizualnym. Ta umowa XML wyznacza dozwolone elementy, ich położenie, liczność, typy i formaty.

Podręcznik KSeF 2.0 rozdziela dwa obowiązki. Struktura określa, co plik XML powinien lub może zawierać, natomiast art. 106e ustawy o VAT nadal wskazuje dane wymagane na konkretnej fakturze. FA(3) udostępnia też pola fakultatywne, takie jak dane kontaktowe.

minOccurs="0" oznacza jedynie, że XSD pozwala pominąć element. Nie przesądza, że prawo pozwala na to zawsze. Pole wypełnione w przykładzie MF również nie staje się przez to obowiązkowe w każdej fakturze.

Jakiej przestrzeni nazw i nagłówka FA(3) użyć?

Należy użyć przestrzeni docelowej z oficjalnego XSD FA(3):

http://crd.gov.pl/wzor/2025/06/25/13775/

Końcowy ukośnik ma znaczenie. Oficjalny przykład klienta Java pokazuje odpowiadający nagłówek:

<Faktura xmlns="http://crd.gov.pl/wzor/2025/06/25/13775/">
  <Naglowek>
    <KodFormularza kodSystemowy="FA (3)" wersjaSchemy="1-0E">FA</KodFormularza>
    <WariantFormularza>3</WariantFormularza>
    <DataWytworzeniaFa>2026-08-28T09:30:00Z</DataWytworzeniaFa>
    <SystemInfo>YourApp 4.2</SystemInfo>
  </Naglowek>
  <!-- Remaining sections in XSD order -->
</Faktura>

Przestrzeń nazw, kodSystemowy, wersjaSchemy i wariant powinny znaleźć się w jednym wersjonowanym serializerze. Nowy schemat MF wymaga jawnego wyboru wersji i osobnych fixtures, nie globalnej zamiany tekstu.

XML 1.0 należy generować jako UTF-8 bez BOM. Reguły weryfikacji pozwalają pominąć deklarację XML, ale nie zadeklarować inne kodowanie. KSeF odrzuca też instrukcje przetwarzania i wskazane zakresy Unicode.

Jakie są główne sekcje FA(3)?

Kolejność jest częścią umowy. XSD korzysta z sequence i choice, więc ogólny mapper może wypisać poprawne wartości w złej kolejności. Kolejność serializacji powinna być jawna i objęta testem XSD. Sekcje warunkowe należy dodawać tylko wtedy, gdy wynikają z modelu domenowego.

Jak wygląda szkielet faktury FA(3)?

Poniższy szkielet jest celowo niepełny: nie nadaje się do skopiowania, nie jest minimalnym dokumentem XSD ani prawnie wystarczającą fakturą.

<Faktura xmlns="http://crd.gov.pl/wzor/2025/06/25/13775/">
  <Naglowek><KodFormularza kodSystemowy="FA (3)" wersjaSchemy="1-0E">FA</KodFormularza><WariantFormularza>3</WariantFormularza><DataWytworzeniaFa>2026-08-28T09:30:00Z</DataWytworzeniaFa><SystemInfo>YourApp 4.2</SystemInfo></Naglowek>
  <Podmiot1><DaneIdentyfikacyjne><NIP>1234567890</NIP><Nazwa>Example Seller sp. z o.o.</Nazwa></DaneIdentyfikacyjne></Podmiot1>
  <Podmiot2><DaneIdentyfikacyjne><NIP>9876543210</NIP><Nazwa>Example Buyer sp. z o.o.</Nazwa></DaneIdentyfikacyjne></Podmiot2>
  <Fa><KodWaluty>PLN</KodWaluty><P_1>2026-08-28</P_1><P_2>FV/2026/08/1042</P_2><P_15>123.00</P_15><Adnotacje><!-- Applicable markers and branches --></Adnotacje><RodzajFaktury>VAT</RodzajFaktury><FaWiersz><NrWierszaFa>1</NrWierszaFa><P_7>Software subscription</P_7><P_8A>szt.</P_8A><P_8B>1</P_8B><P_9A>100.00</P_9A><P_11>100.00</P_11><P_12>23</P_12></FaWiersz></Fa>
</Faktura>

Minimum zależy od rodzaju faktury, stron, VAT, płatności, korekt i zaliczek. Dokument spełniający wyłącznie liczności XSD może nie zawierać danych ustawowych. Punktem wyjścia powinien być typowany model faktury i fixtures dla poszczególnych scenariuszy.

Jak mapować identyfikatory sprzedawcy i nabywcy?

KSeF używa Podmiot2/DaneIdentyfikacyjne/NIP, aby udostępnić fakturę polskiemu nabywcy. NIP wpisany do NrID może więc zaburzyć doręczenie. tax_identifier_kind, country_code, identifier i has_no_identifier warto przechowywać oddzielnie, a wykluczające się gałęzie sprawdzać przed serializacją. Produkcja weryfikuje sumę kontrolną NIP inaczej niż TEST, dlatego należy robić to także w aplikacji.

Jak modelować Fa, sumy i wiersze?

Fa zawiera transakcję: walutę (KodWaluty), datę (P_1), numer sprzedawcy (P_2), sumy, adnotacje, rodzaj (RodzajFaktury), FaWiersz i płatność. Nazwy XML nie powinny być głównym modelem biznesowym. Kwoty, kategorie podatkowe, ilości, daty i strony należy modelować typami domenowymi, a dopiero potem mapować do FA(3).

Testy scenariusza powinny sprawdzać uzgodnienie wierszy z sumami, regułę zaokrągleń, P_15, formaty niezależne od locale, brak przyszłej daty P_1 i stabilność P_2. Klucz duplikatu łączy NIP sprzedawcy, RodzajFaktury i P_2, więc ponowienie musi uzgodnić tę samą fakturę, a nie tworzyć nowy numer. Adnotacje należy wyprowadzać z faktów i osobno testować dla zwolnienia, odwrotnego obciążenia, split payment czy marży.

Jak lokalnie walidować FA(3) przed wysyłką?

1. Zamrozić typowany snapshot stron, wierszy, VAT, sum, dat i rodzaju.
2. Zastosować reguły biznesowe z czytelnymi błędami pól.
3. Serializować deterministycznie jako XML 1.0, UTF-8 bez BOM, w poprawnej przestrzeni i kolejności.
4. Walidować przypiętym XSD wraz z importowanymi definicjami; zapisać checksum i URL.
5. Zamrozić bajty i z tej samej sekwencji obliczyć rozmiar oraz hash przed szyfrowaniem.
6. Zapisać diagnostykę: wersję serializera, źródłowy snapshot, hash, rozmiar i wynik. XML faktury to wrażliwe dane finansowe.

Limit wynosi 1 MB bez załącznika i 3 MB z załącznikiem. Walidacja XSD nie sprawdza limitów usługi. Fixtures powinny obejmować VAT krajowy, UE, państwo trzecie, konsumenta, korektę, zaliczkę, zwolnienie i każdy obsługiwany schemat.

Jak testować w TEST, DEMO i produkcji?

Oficjalna macierz środowisk opisuje TEST jako integracyjny, DEMO jako zbliżony do produkcji, a PRD jako środowisko faktur wywołujących skutki prawne. Do TEST i DEMO nie wolno wysyłać danych produkcyjnych. Należy używać syntetycznych tożsamości i NIP.

Najpierw warto przetestować mapowanie i XSD lokalnie, potem wysłać scenariusze do TEST, w DEMO sprawdzić uprawnienia, odpytywanie statusu i UPO, a ten sam build serializera kontrolowanie wdrożyć do PRD. Przyjęcie w TEST nie dowodzi poprawności produkcyjnego NIP. Możliwości środowisk trzeba wersjonować oddzielnie.

Kiedy wysłana faktura jest naprawdę przyjęta?

Wysyłka w sesji online jest asynchroniczna. API może zwrócić referencję przed przyjęciem samej faktury. Trzeba ją natychmiast zapisać i ustawić widoczny stan processing.

Przewodnik po statusach i UPO opisuje statusy, błędy i pobranie UPO. Model powinien rozróżniać: wygenerowano i zwalidowano; wysłano z referencją; przetwarzanie; odrzucono; przyjęto z numerem KSeF; zapisano UPO. Tylko ścieżka przyjęta może przedstawiać numer KSeF jako dowód końcowy. HTTP 202 oznacza kolejkę, nie sukces faktury.

Budować FA(3) samodzielnie czy użyć KSeF Kit?

Własna integracja ma sens, gdy FA(3) jest podstawową funkcją produktu, źródła wykraczają poza Stripe albo potrzebne są szczególne scenariusze podatkowe. Trzeba uwzględnić aktualizacje schematu, fixtures, poświadczenia, środowiska, monitoring i obsługę operacyjną.

Jeśli źródłem jest Stripe, KSeF Kit przekształca sfinalizowane faktury Stripe do FA(3), wysyła je i zapisuje numer KSeF oraz UPO. Dokumentacja konfiguracji opisuje połączenia i środowiska testowe oraz produkcyjne.

Nie zastępuje to poprawnych danych podatkowych ani nie gwarantuje zgodności w każdym przypadku. Ogranicza jednak zakres integracji: serializer, szyfrowanie, wysyłkę, asynchroniczne stany i przekazanie dowodów. W obu wariantach standard pozostaje ten sam: poprawne fakty, prawidłowy XML FA(3), zakończone przetwarzanie KSeF i zachowane dowody. Więcej materiałów znajduje się w archiwum inżynierii zgodności.