Kiedy muszę przejść na schemat FA(3) w KSeF?

KSeF API FA(2) vs FA(3) – różnice i migracja

KSeF API 2.0 wspiera schematy FA(2) do 31 stycznia 2026 oraz FA(3) od 1 lutego 2026. Zrozumienie różnic między schematami jest kluczowe dla prawidłowej migracji i przygotowania do obowiązkowego użycia FA(3).

Różnice między FA(2) a FA(3)

Schemat FA(2) jest obowiązujący do 31 stycznia 2026, po czym obowiązkowy staje się schemat FA(3). Oba schematy różnią się strukturą XML, wymaganiami dotyczącymi pól oraz formatem adresów podmiotów.

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 używasz schematu FA(2) czy FA(3). Schemat FA(2) jest obowiązujący do 31 stycznia 2026, FA(3) od 1 lutego 2026. W formCode sesji musisz wskazać właściwą wersję schematu.

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. Do 31 stycznia 2026 możesz używać schematu FA(2). Po 1 lutego 2026 wszystkie faktury muszą być w formacie FA(3). Zaleca się wcześniejsze przygotowanie i testowanie FA(3) w środowisku testowym.

Czy mogę używać obu schematów jednocześnie?

Do 31 stycznia 2026 możesz używać zarówno FA(2), jak i FA(3). Od 1 lutego 2026 obowiązuje wyłącznie FA(3). W formCode sesji musisz wskazać właściwą wersję schematu. Różne sesje mogą używać różnych schematów, jeśli są w odpowiednim okresie.

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) jest obowiązujący do 31 stycznia 2026. Schemat FA(3) jest obowiązkowy od 1 lutego 2026. Do 31 stycznia 2026 możesz używać zarówno FA(2), jak i FA(3). Po 1 lutego 2026 wszystkie faktury muszą być w formacie FA(3). Zaleca się wcześniejsze przygotowanie i testowanie FA(3) w środowisku testowym.

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)?

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?

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.