KSeF API a struktura FA(3): XSD, terminy i załączniki w integracji

Oś czasu (uproszczenie)

Do 31 stycznia 2026 r.: FA(2) dla faktur ustrukturyzowanych
        |
        v
Od 1 lutego 2026 r.: FA(3) jako struktura obowiązująca w KSeF 2.0
        v
Korekty i faktury rozliczające wystawiane od 1 lutego 2026 r.
stosują FA(3), także gdy dokument pierwotny był w FA(2) lub FA(1)

Aktualne pliki XSD publikuje Ministerstwo Finansów w materiałach dotyczących KSeF 2.0. W integracji trzeba korzystać z wersji schematu właściwej dla daty wystawienia i typu dokumentu, a od 1 lutego 2026 r. dla faktur ustrukturyzowanych punktem odniesienia jest FA(3).

Co warto uwzględnić przy integracji

• Załącznik w FA(3) – struktura zawiera element Zalacznik, ale jego użycie wymaga spełnienia formalności wskazanych przez MF, m.in. zgłoszenia w e-Urzędzie Skarbowym.
• Rozmiar i kompletność pliku – przy dokumentach z załącznikami trzeba uwzględnić ograniczenia techniczne z aktualnej dokumentacji API oraz to, że załącznik jest częścią struktury XML.
• Tryb wsadowy (batch) – przy większej liczbie dokumentów lub załączników często wykorzystuje się mechanizmy wysyłki zbiorczej dostępne w API.
• Walidacja przed wysyłką – sprawdzenie pliku względem XSD (lokalnie lub w procesie CI) pozwala uniknąć części błędów jeszcze przed komunikacją z KSeF. Spójność danych to osobny etap: Błędy walidacji: XML/XSD vs biznes.

Gdzie pobrać XSD i dokumentację

Oficjalne schematy i dokumentacja są publikowane przez Ministerstwo Finansów na stronach ksef.podatki.gov.pl w sekcji materiałów KSeF. W praktyce warto korzystać wyłącznie z aktualnych plików ze źródeł urzędowych.

Limity wywołań API

Operacje na fakturach podlegają ograniczeniom liczby zapytań. Przy planowaniu integracji warto uwzględnić te limity i sposób ich obsługi: Limity zapytań do API KSeF

Treść ma charakter informacyjny i edukacyjny. Nie stanowi porady prawnej ani podatkowej.