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

Oś czasu (uproszczenie)

...  FA(2) jako struktura przejściowa ...
        |
        v
   FA(3) jako struktura obowiązująca w KSeF 2.0
        |   (dla faktur wystawianych od momentu wejścia w życie nowych przepisów)
        v
  Korekty: nowe korekty wystawiane po wejściu FA(3)
           stosują strukturę FA(3), nawet gdy pierwotna faktura była w starszej wersji

Dokładne daty obowiązywania oraz aktualne pliki XSD publikuje Ministerstwo Finansów w materiałach dotyczących KSeF 2.0 – przed wdrożeniem warto upewnić się, że korzystasz z właściwej wersji schematu.

Co warto uwzględnić przy integracji

• Jeden plik XML może zawierać fakturę wraz z załącznikami jako jedną całość – wpływa to na sposób generowania dokumentów w systemach (np. ERP).
• Limity rozmiaru pliku – obowiązują ograniczenia wielkości przesyłanych danych; przy fakturach z załącznikami liczy się łączny rozmiar całego dokumentu 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