Dlaczego mapowanie FA(3) nie powinno być zestawem przypadkowych reguł
Struktura FA(3) jest obowiązującą strukturą logiczną e-Faktury w KSeF 2.0. Faktura ustrukturyzowana ma format XML zgodny ze wzorem opublikowanym w Centralnym Repozytorium Wzorów Dokumentów Elektronicznych. MF udostępnia również przykładowe pliki.
W ERP dane rzadko są przechowywane w układzie identycznym ze strukturą XML. Jeden dokument może łączyć dane kontrahenta, zamówienia, magazynu, podatków, płatności i księgi głównej. Dlatego bezpośrednie przypisanie „kolumna bazy → element XML” szybko staje się trudne do testowania.
Poniższe podejście dotyczy architektury danych. Nie rozstrzyga, jakie dane są wymagane w konkretnej sytuacji podatkowej.
Trzy warstwy zamiast jednego transformatora
Najbezpieczniejszy model składa się z trzech jawnych warstw:
- ekstrakcja z ERP — pobranie danych i identyfikatorów źródłowych,
- kanoniczny model faktury — uporządkowany model niezależny od XML,
- generator FA(3) — transformacja modelu na XML i walidacja względem XSD.
Model pośredni izoluje logikę biznesową ERP od szczegółów schematu. Pozwala też zapisać reguły w sposób czytelny dla księgowości, na przykład: „data sprzedaży pochodzi z dokumentu wydania, jeśli proces firmy tak ją wyznacza”, zamiast ukrywać warunek w szablonie XML.
Jak zbudować macierz mapowania
Dla każdego pola używanego w integracji warto zapisać:
| Element procesu | Co dokumentujemy |
|---|---|
| Pole docelowe | Ścieżka lub element struktury FA(3) |
| Źródło | Tabela, encja, API lub pole ERP |
| Reguła | Transformacja, warunek obecności, wartość domyślna |
| Właściciel | Osoba zatwierdzająca znaczenie biznesowe |
| Test | Przypadek pozytywny, graniczny i negatywny |
| Ślad | Identyfikator dokumentu źródłowego |
Macierz powinna rozróżniać dane obowiązkowe ze względu na schemat, dane zależne od konkretnego przypadku i dane dobrowolne. Nie należy wypełniać pól opcjonalnych sztucznymi wartościami tylko po to, aby uzyskać rozbudowany XML.
Obszary, które wymagają osobnych decyzji
Identyfikacja stron
ERP powinien jednoznacznie wskazać sprzedawcę, nabywcę i ewentualne podmioty dodatkowe. W środowisku wielospółkowym sama nazwa firmy nie wystarcza — kontekst NIP wpływa również na autoryzację do API.
Zasady izolacji tych kontekstów opisuje przewodnik KSeF dla wielu spółek i numerów NIP.
Numer dokumentu i numer KSeF
Numer faktury nadawany w ERP i numer KSeF to różne identyfikatory. Numer KSeF jest nadawany po przyjęciu dokumentu przez system, zwracany w UPO i nie jest elementem wejściowego XML.
Model danych powinien przechowywać:
- niezmienny identyfikator techniczny dokumentu ERP,
- numer faktury z systemu źródłowego,
- identyfikator żądania albo sesji,
- numer KSeF po przyjęciu,
- status oraz czas ostatniej aktualizacji.
Daty
Nie należy sprowadzać wszystkich dat do jednego pola ERP. Data wystawienia, sprzedaży, płatności i przyjęcia przez KSeF pełnią różne role. Reguły ich wyznaczania powinny być zatwierdzone przez właściciela procesu.
Pozycje, jednostki i zaokrąglenia
Testy powinny objąć rabaty, różne stawki, jednostki miary, wartości ujemne w dozwolonych scenariuszach, waluty oraz zaokrąglenia na poziomie pozycji i podsumowania. Generator nie powinien „naprawiać” różnic bez pozostawienia śladu.
Płatność
FA(3) wprowadza zmiany związane między innymi z prezentacją terminu płatności. ERP może przechowywać kilka terminów, harmonogram albo rozliczenia częściowe. Macierz mapowania musi wskazywać, które dane są źródłem dla konkretnego wariantu dokumentu.
Podmiot3 i role dodatkowe
MF wskazuje wśród zmian FA(3) nową rolę pracownika w Podmiot3 oraz rozwiązania dla JST i Grup VAT. Nie oznacza to, że każda integracja ma automatycznie wypełniać te pola. Powinna natomiast świadomie obsłużyć scenariusze występujące w organizacji.
Korekty
Korekta wymaga wiarygodnego powiązania z dokumentem pierwotnym. Jeśli ERP dopuszcza zmianę numerów, scalanie kartotek albo migracje, integracja musi zachować stabilny klucz techniczny i dane potrzebne do rekonstrukcji relacji.
Walidacja na dwóch poziomach
Walidacja biznesowa
Przed generowaniem XML system sprawdza reguły wynikające z procesu firmy:
- czy dokument ma właściwego właściciela i spółkę,
- czy kontrahent ma komplet danych używanych w danym scenariuszu,
- czy sumy pozycji zgadzają się z nagłówkiem,
- czy korekta wskazuje dokument pierwotny,
- czy dokument nie został już skierowany do wysyłki.
Walidacja strukturalna
Wygenerowany XML musi być zgodny z aktualnym schematem FA(3). MF informuje, że dokument zawierający błędy, na przykład brak pól wymaganych przez strukturę, zostanie odrzucony.
Walidację XSD warto wykonywać:
- w pipeline CI na zestawie wzorcowych dokumentów,
- przed wysłaniem dokumentu,
- po każdej zmianie mapowania,
- po aktualizacji ERP lub generatora.
Błędy schematu to tylko jedna z klas awarii. Przed wdrożeniem warto sprawdzić również 12 typowych błędów integracji KSeF, w tym statusy, ponowienia i wynik częściowy paczki.
Testy kontraktowe i „złote pliki”
Dobry zestaw regresji zawiera zanonimizowane albo syntetyczne dane, które odzwierciedlają rzeczywiste warianty firmy. Dla każdego przypadku zapisuje się:
- dane wejściowe modelu kanonicznego,
- oczekiwany XML,
- wynik walidacji,
- oczekiwane powiązania identyfikatorów,
- odpowiedź środowiska testowego, jeśli test obejmuje API.
Przykładowe pliki MF są punktem odniesienia dla schematu, lecz nie zastępują przypadków biznesowych przedsiębiorstwa.
Wersjonowanie mapowania
Każda zmiana reguły powinna mieć:
- numer wersji,
- autora i osobę zatwierdzającą,
- opis wpływu,
- listę testów regresji,
- datę wdrożenia,
- sposób obsługi dokumentów utworzonych wcześniej.
Warto zapisywać wersję mapowania przy każdym wygenerowanym XML. Ułatwia to odtworzenie, dlaczego dokument miał konkretną postać.
Kryteria gotowego mapowania FA(3)
Mapowanie można uznać za gotowe, gdy:
- każde używane pole ma jawne źródło i właściciela biznesowego,
- identyfikatory ERP i KSeF nie są ze sobą mylone,
- wszystkie rzeczywiste typy dokumentów mają testy,
- XML przechodzi walidację na aktualnym XSD,
- odrzucenie nie powoduje utraty dokumentu ani tworzenia niekontrolowanej kopii,
- zmiany są wersjonowane,
- księgowość zatwierdziła próbki,
- testy na środowisku przeznaczonym do integracji nie używają rzeczywistych danych, jeśli regulamin środowiska tego zabrania.
Potrzebujesz przełożyć model FA(3) na konkretny ERP?
Macierz pól jest dopiero początkiem: produkcyjna integracja wymaga również wersjonowania reguł, walidacji, obsługi korekt i śladu identyfikatorów. Zobacz zakres integracji KSeF z ERP, jeśli chcesz przejść od analizy danych do kompletnego, testowalnego przepływu.
Omówmy mapowanie i integrację ERP →
Źródła oficjalne
- Faktura ustrukturyzowana i struktura logiczna FA(3) — Ministerstwo Finansów
- Materiały i przykładowe pliki FA(3) — Ministerstwo Finansów
- Informacje dla integratorów IT — Ministerstwo Finansów
- Numer KSeF i zbiorczy identyfikator — Ministerstwo Finansów
- Dokumentacja i środowiska dla integratorów — Ministerstwo Finansów
Stan informacji: 31 lipca 2026 r.; źródła oficjalne zweryfikowano 2 sierpnia 2026 r. Materiał opisuje praktykę projektowania integracji, a nie interpretację prawa podatkowego.
