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

Czego KSeF nie sprawdza

Zgodność pliku XML ze schematem XSD (FA(3)) to walidacja techniczna — KSeF nie ocenia, czy kwoty, stawki VAT, dane kontrahenta ani warunki transakcji są poprawne biznesowo. Dokument może przejść XSD i nadal zawierać błędy merytoryczne.

Jak można to zweryfikować automatycznie

Przed wysyłką warto walidować XML lokalnie względem oficjalnego XSD (np. w CI). Po integracji z API sensowne są dodatkowe reguły: porównanie z zamówieniem, sprawdzenie NIP-u i rachunku oraz scoring ryzyka faktur wymagających uwagi człowieka.

FAQ

Powiązane artykuły

• Co powinna zawierać faktura w KSeF? Struktura FA(3) – zawartość i pola schematu FA(3)
• Jak czytać XML faktury z KSeF – parsowanie i odczyt pliku XML
• Limity zapytań do API KSeF – rate limiting i obsługa 429
• Jak zwalidować fakturę przed wysłaniem do KSeF – walidacja przed integracją

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