Czym jest FA(3)
FA(3) to trzecia wersja struktury logicznej polskiej faktury ustrukturyzowanej (e-Faktury), publikowanej przez Ministerstwo Finansów jako XSD. Od KSeF 2.0 każda faktura wysyłana do KSeF musi być poprawnym XML FA(3). W KSeF to XML jest fakturą, a PDF jest tylko jego wizualizacją.
Każdy dokument FA(3) zaczyna się od takiego samego nagłówka:
<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-10-12T07:23:07Z</DataWytworzeniaFa>
</Naglowek>
<!-- Podmiot1 (sprzedawca), Podmiot2 (nabywca), Fa (dane faktury) -->
</Faktura>Struktura faktury FA(3)
Standardowa faktura VAT składa się z czterech głównych bloków. Tabela pokazuje, gdzie trafia każde pole żądania POST /invoices w Notaly.
| Element FA(3) | Zawartość | Pole JSON |
|---|---|---|
Naglowek | Kod formularza, wersja schematu, data wytworzenia | Generowane |
Podmiot1 | Sprzedawca: NIP, Nazwa, Adres | seller |
Podmiot2 | Nabywca: NIP, Nazwa, Adres | buyer |
Fa/KodWaluty | Waluta (ISO 4217) | currency |
Fa/P_1 | Data wystawienia | issueDate |
Fa/P_2 | Numer faktury | number |
Fa/P_13_x, P_14_x | Sumy netto i VAT według stawki (23%, 8%, 5%, 0%) | Liczone z items |
Fa/P_15 | Kwota brutto | Liczone |
Fa/Adnotacje | Obowiązkowe adnotacje (MPP, zwolnienia, procedura marży…) | Wartości domyślne |
Fa/FaWiersz | Pozycje: P_7 nazwa, P_8A jednostka, P_8B ilość, P_9A cena netto, P_11 wartość netto, P_12 stawka VAT | items[] |
Jak zwalidować FA(3) względem XSD
Waliduj lokalnie, zanim cokolwiek wyślesz do KSeF. Pobierz oficjalny schemat FA(3) ze strony Ministerstwa Finansów (główny schemat.xsd importuje wspólne definicje typów, więc trzymaj wszystkie pliki w jednym folderze) i uruchom:
xmllint --noout --schema schemat.xsd faktura.xml
# faktura.xml validatesWalidacja XSD wychwytuje błędy struktury i typów. KSeF po XSD wykonuje też kontrole biznesowe, więc plik zgodny ze schematem nadal może zostać odrzucony. Notaly waliduje każdą fakturę względem XSD przed wysyłką i zwraca odrzucenia KSeF jako stałe kody błędów.
Najczęstsze błędy walidacji FA(3)
- Nieprawidłowy NIP. NIP ma 10 cyfr i cyfrę kontrolną (wagi 6, 5, 7, 2, 3, 4, 5, 6, 7 modulo 11). Literówka zatrzyma fakturę, zanim zobaczy ją KSeF.
- Sumy, które się nie zgadzają.
P_13_xiP_14_xmuszą równać się sumie pozycji dla każdej stawki VAT, aP_15kwocie brutto, w zaokrągleniu do 2 miejsc. - Zły format daty lub waluty. Daty w formacie
RRRR-MM-DD, waluty według ISO 4217 (PLN,EUR), kraje według ISO 3166 alpha-2 (PL). - Brak adnotacji.
Adnotacjesą obowiązkowe nawet wtedy, gdy nic szczególnego nie występuje: każdą flagę (P_16,P_17,P_18,P_18A,P_23…) trzeba ustawić jawnie. - Stara przestrzeń nazw. Pliki FA(2) mają inną przestrzeń nazw i nie są akceptowane jako FA(3).
- Niezakodowane znaki. Nazwy zawierające
&,<lub cudzysłowy trzeba zakodować w XML.
Generowanie XML FA(3) z JSON
Z Notaly nie piszesz FA(3) ręcznie. Wysyłasz fakturę jako JSON, a Notaly liczy sumy według stawek VAT, uzupełnia nagłówek i adnotacje, koduje tekst, waliduje wynik i wysyła go do KSeF.
- Utwórz fakturęWyślij
POST /invoicesze sprzedawcą, nabywcą i pozycjami, jak w przykładzie API KSeF. - Pobierz dokładny XMLWywołaj
GET /invoices/{id}/xml, aby pobrać dokument FA(3) wysłany do KSeF, bajt w bajt. - Zachowaj dowódGdy faktura ma status
accepted, zapisz numer KSeF i UPO, a klientowi przekaż PDF z kodem QR KSeF.
curl https://api.getnotaly.com/invoices/inv_8f2c…/xml \
-H "Authorization: Bearer $NOTALY_API_KEY" -o faktura.xml