KSeF API FA(2) vs FA(3) – różnice i migracja
Różnice między FA(2) a FA(3)
Schemat FA(2) obowiązywał do 31 stycznia 2026 r. Od 1 lutego 2026 r. obowiązkowy jest schemat FA(3). Oba schematy różnią się strukturą XML, wymaganiami dotyczącymi pól oraz formatem adresów podmiotów.
Główne różnice dotyczą: formatu adresów (FA(3) pozwala na adres w jednym polu tekstowym, FA(2) wymaga rozbicia na osobne pola), struktury niektórych elementów oraz wymagań dotyczących pól obowiązkowych.
Migracja z FA(2) do FA(3) wymaga aktualizacji struktury XML faktury, weryfikacji zgodności z nowym schematem XSD oraz aktualizacji kodu generującego faktury. Większość faktur może być łatwo przekonwertowana, jeśli formularz zbiera dane w odpowiednim formacie.
Instrukcja krok po kroku
1. Zidentyfikuj używaną wersję schematu
Sprawdź, czy Twój system używa schematu FA(3). Schemat FA(2) obowiązywał do 31 stycznia 2026 r., od 1 lutego 2026 r. wymagany jest wyłącznie FA(3). W formCode sesji musisz wskazać wersję FA(3).
2. Przeanalizuj różnice strukturalne
Przeanalizuj różnice między FA(2) a FA(3): format adresów (FA(3) pozwala na adres w jednym polu, FA(2) wymaga rozbicia), struktura niektórych elementów, wymagania dotyczące pól obowiązkowych. Sprawdź dokumentację schematów XSD.
3. Zaktualizuj kod generujący faktury
Zaktualizuj kod generujący faktury, aby obsługiwał schemat FA(3). Upewnij się, że adresy są w odpowiednim formacie (można użyć jednego pola tekstowego w FA(3)) oraz że wszystkie wymagane pola są wypełnione zgodnie z nowym schematem.
4. Zweryfikuj zgodność z XSD
Zweryfikuj wygenerowane faktury FA(3) względem schematu XSD FA(3). Użyj narzędzi do walidacji XML, aby upewnić się, że faktury są zgodne z nowym schematem przed wysłaniem do KSeF.
5. Przetestuj w środowisku testowym
Przetestuj faktury FA(3) w środowisku testowym KSeF przed przejściem na produkcję. Upewnij się, że wszystkie faktury są poprawnie przetwarzane i że nie ma błędów walidacji.
Najczęstsze problemy i rozwiązania
Kiedy muszę przejść na FA(3)?
Schemat FA(3) jest obowiązkowy od 1 lutego 2026 r. Do 31 stycznia 2026 r. można było używać schematu FA(2). Od 1 lutego 2026 r. wszystkie faktury muszą być w formacie FA(3).
Czy mogę używać obu schematów jednocześnie?
Do 31 stycznia 2026 r. można było używać zarówno FA(2), jak i FA(3). Od 1 lutego 2026 r. obowiązuje wyłącznie FA(3). W formCode sesji musisz wskazać wersję FA(3).
Różnice w formacie adresów
W schemacie FA(3) adres podmiotu może być podany w jednym polu tekstowym (np. "PL, ul. K...1 m. 2, 00-001 W..."), podczas gdy FA(2) wymaga rozbicia na osobne pola (ulica, numer, kod pocztowy, miejscowość). Większość faktur może być łatwo przekonwertowana, jeśli formularz zbiera dane w odpowiednim formacie.
Jak zaktualizować formCode?
W formCode sesji musisz wskazać właściwą wersję schematu: dla FA(2) użyj odpowiedniego systemCode, schemaVersion i value zgodnie z dokumentacją, dla FA(3) użyj odpowiednich wartości dla FA(3). Sprawdź dokumentację API dotyczącą formCode dla obu schematów.
Terminy obowiązywania schematów
Schemat FA(2) obowiązywał do 31 stycznia 2026 r. Schemat FA(3) jest obowiązkowy od 1 lutego 2026 r. Do 31 stycznia 2026 r. można było używać zarówno FA(2), jak i FA(3). Od 1 lutego 2026 r. wszystkie faktury muszą być w formacie FA(3).
Różnice strukturalne
Główne różnice między FA(2) a FA(3): format adresów (FA(3) pozwala na adres w jednym polu tekstowym, FA(2) wymaga rozbicia na osobne pola), struktura niektórych elementów, wymagania dotyczące pól obowiązkowych. Większość faktur może być łatwo przekonwertowana, jeśli formularz zbiera dane w odpowiednim formacie. Sprawdź dokumentację schematów XSD dla szczegółowych różnic.
Migracja z FA(2) do FA(3)
Migracja wymaga: aktualizacji struktury XML faktury zgodnie z schematem FA(3), weryfikacji zgodności z nowym schematem XSD, aktualizacji kodu generującego faktury, aktualizacji formCode w sesjach oraz testowania w środowisku testowym. Większość faktur może być łatwo przekonwertowana, jeśli formularz zbiera dane w odpowiednim formacie.
Walidacja i testowanie
Zweryfikuj wygenerowane faktury FA(3) względem schematu XSD FA(3) używając narzędzi do walidacji XML. Przetestuj faktury FA(3) w środowisku testowym KSeF przed przejściem na produkcję. Upewnij się, że wszystkie faktury są poprawnie przetwarzane i że nie ma błędów walidacji.
FAQ
Kiedy muszę przejść na schemat FA(3)?
Schemat FA(3) jest obowiązkowy od 1 lutego 2026 r. Do 31 stycznia 2026 r. można było używać schematu FA(2). Od 1 lutego 2026 r. wszystkie faktury muszą być w formacie FA(3).
Jakie są główne różnice między FA(2) a FA(3)?
Główne różnice dotyczą: formatu adresów (FA(3) pozwala na adres w jednym polu tekstowym, FA(2) wymaga rozbicia na osobne pola), struktury niektórych elementów oraz wymagań dotyczących pól obowiązkowych. Większość faktur może być łatwo przekonwertowana, jeśli formularz zbiera dane w odpowiednim formacie.
Czy mogę używać obu schematów jednocześnie?
Do 31 stycznia 2026 r. można było używać zarówno FA(2), jak i FA(3). Od 1 lutego 2026 r. obowiązuje wyłącznie FA(3). W formCode sesji musisz wskazać wersję FA(3).
Jak zaktualizować kod do FA(3)?
Zaktualizuj kod generujący faktury, aby obsługiwał schemat FA(3): zmień strukturę XML zgodnie z nowym schematem, zaktualizuj format adresów (można użyć jednego pola tekstowego), zweryfikuj zgodność z XSD FA(3) oraz zaktualizuj formCode w sesjach. Przetestuj w środowisku testowym przed produkcją.
Gdzie znajdę schemat XSD FA(3)?
Schemat XSD FA(3) jest dostępny w dokumentacji KSeF oraz w repozytorium GitHub CIRFMF/ksef-docs. Schemat jest opublikowany od czerwca 2025 i jest dostępny do pobrania z oficjalnych źródeł Ministerstwa Finansów.
Powiązane tematy
Przydatne serwisy
Status i komunikaty
API i narzędzia
Pierwsza grupa – status systemu KSeF i komunikaty techniczne Ministerstwa Finansów, druga – narzędzia do integracji z KSeF i walidacji faktur.