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. Przed wysyłką sprawdź trzy poziomy: XSD określa budowę XML, polskie przepisy VAT wskazują wymagane dane, a rodzaj transakcji decyduje o właściwych gałęziach warunkowych. 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. Schemat 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ć?

Użyj docelowej przestrzeni nazw 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.

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

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

Schemat określa również kolejność. 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. Dodawaj sekcje warunkowe 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ą. Środowisko produkcyjne weryfikuje sumę kontrolną NIP inaczej niż TEST, dlatego sprawdzaj ją 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 modeluj typami domenowymi, a dopiero potem mapuj do FA(3).

Testy scenariusza powinny sprawdzać uzgodnienie wierszy z sumami, regułę zaokrągleń, P_15, formaty niezależne od ustawień języka i regionu, 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 wyprowadzaj z danych faktury i osobno testuj dla zwolnienia, odwrotnego obciążenia, split payment czy marży.

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

1. Zapisz niezmienny snapshot z typami danych stron, wierszy, VAT, sum, dat i rodzaju.
2. Zastosuj reguły biznesowe z czytelnymi błędami pól.
3. Serializuj deterministycznie jako XML 1.0, UTF-8 bez BOM, w poprawnej przestrzeni i kolejności.
4. Waliduj przypiętym XSD wraz z importowanymi definicjami; zapisz sumę kontrolną i URL.
5. Zachowaj niezmienną sekwencję bajtów i z niej oblicz rozmiar oraz hash przed szyfrowaniem.
6. Zapisz 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. Używaj 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. Zapisz ją od razu i ustaw 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. Numer KSeF przedstawiaj jako dowód dopiero po przyjęciu faktury. HTTP 202 oznacza skierowanie do przetwarzania, nie przyjęcie 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.

KSeF Kit obsługuje serializację, szyfrowanie, wysyłkę, asynchroniczne stany i zapis potwierdzeń. Dane podatkowe oraz zakres obsługiwanych transakcji trzeba sprawdzić przed uruchomieniem integracji. W obu wariantach potrzebujesz prawidłowego XML FA(3), zakończonego przetwarzania i zachowanych potwierdzeń. Więcej materiałów znajdziesz w archiwum inżynierii zgodności.