Mapowanie danych z ERP do struktury FA(3) - lista kontrolna: jak nie utonąć w 400 polach XML

FA(3) vs FA(2) - co faktycznie zmienia się w polach XML

AITekst opracowany z wykorzystaniem sztucznej inteligencji. Zasady i ograniczenia

Struktura FA(3) wprowadza istotne modyfikacje względem poprzedniej wersji schematu logicznego, co wymusza rewizję procesów ETL (Extract, Transform, Load) w działach IT. Rozporządzenie Ministra Finansów z 30 czerwca 2025 r. w sprawie struktury logicznej faktury definiuje nowe wymogi dotyczące precyzji danych, zwiększając liczbę pól opcjonalnych o 41 oraz wprowadzając 5 nowych pól obowiązkowych. Najważniejszą zmianą technologiczną jest odejście od prostej replikacji danych na rzecz rygorystycznej walidacji typów i długości znaków, co ma na celu uszczelnienie systemu podatkowego i usprawnienie kontroli organów Krajowej Administracji Skarbowej.

W nowym schemacie FA(3) dotychczasowe pole P_7, określające numer faktury, zmienia swoją nazwę systemową na P_7_NrFaktury, a jego dopuszczalna długość zostaje zwiększona z 50 do 60 znaków. Eksperci ds. wdrożeń podkreślają, że obalenie mitu o powtarzalności pól jest kluczowe dla powodzenia projektu; przykładem jest wprowadzenie pola P_80 dedykowanego dacie dostawy oraz P_81 dla kodu CN (Nomenklatura Scalona). Co istotne, pole P_26, służące do wskazywania numeru zamówienia, staje się elementem krytycznym w relacjach B2B, szczególnie w przypadku dostaw do dużych sieci handlowych, które uzależniają przyjęcie dokumentu od obecności tej informacji w strukturze XML.

Mapowanie danych ERP musi uwzględniać fakt, że KSeF 2.0 nie przewiduje okresów przejściowych dla podatników zwolnionych z VAT na podstawie art. 113 ustawy o VAT. Oznacza to, że każda jednostka gospodarcza musi dostosować swoje systemy finansowo-księgowe do obsługi załączników w schemie FA(3), które zastępują dotychczasową swobodę w przesyłaniu dokumentów dodatkowych. W przypadku braku odpowiedniego mapowania, faktura ustrukturyzowana może zostać odrzucona przez bramkę KSeF już na etapie wstępnej weryfikacji formatu i długości pól.

Warto również zwrócić uwagę na eliminację ogólnych stawek "NP" oraz 0% VAT, które w strukturze FA(3) zostają zastąpione przez bardziej rozbudowane kodyfikacje. Aby poznać rozwiązania dedykowane KSeF 2.0, administratorzy systemów powinni skontaktować się z dostawcą oprogramowania i pobrać aktualny plik XSD z repozytorium MF. Porównanie plików metodą "diff" pozwala na szybką identyfikację zmian w hierarchii tagów, co jest niezbędne do poprawnego skonfigurowania interfejsu API i zapewnienia stabilności komunikacji z serwerami Ministerstwa Finansów.

Lista kontrolna mapowania - 7 kroków przed pierwszym testem w środowisku KSeF

Przygotowanie systemów ERP takich jak SAP czy TETA AIR do współpracy z KSeF wymaga precyzyjnego wyodrębnienia danych z wielu tabel relacyjnych baz danych. Krok zero to eksport danych źródłowych, gdzie kluczowe znaczenie ma identyfikacja tabel przechowujących dane kontrahentów, nagłówki oraz pozycje faktur. Przykładowo, pole GLN (Global Location Number) musi zostać pobrane z tabeli kontrahentów i precyzyjnie zmapowane na pole P_82 w schemacie XML, aby umożliwić automatyczną identyfikację punktu dostawy przez systemy nabywcy.

• KH.Kontrahent - pole GLN (mapuj na P_82)
• FK.Nagłówki - pole OrderNumber (mapuj na P_26)
• FK.Pozycje - pole PKWiU (mapuj na P_81)

Kolejnym etapem jest walidacja jednoznaczności, gdzie należy rozstrzygnąć przypadki, w których jedna informacja z ERP może zasilać dwa różne pola w FA(3). Przykładem jest data sprzedaży, która domyślnie trafia do pola P_8, ale w określonych scenariuszach biznesowych musi być również zmapowana jako data dostawy w polu P_80. Brak rozdzielenia tych terminów może prowadzić do sytuacji, w której faktura przejdzie walidację techniczną na bramce KSeF, ale zostanie odrzucona przez system ERP nabywcy ze względu na niespójność merytoryczną danych logistycznych.

Przed uruchomieniem pełnej integracji niezbędne jest przeprowadzenie testów w środowisku próbnym KSeF. Bramka testowa akceptuje pliki o rozmiarze do 10 MB i zawierające do 10 000 pozycji towarowych, co pozwala na weryfikację wydajności skryptów mapujących. Należy pamiętać, że certyfikat KSeF w środowisku testowym zachowuje ważność przez 2 lata i służy do uwierzytelnienia sesji. Poniższa lista kontrolna definiuje niezbędne kroki procesowe:

1. Eksport danych źródłowych z tabel systemowych ERP.
2. Walidacja jednoznaczności i rozdzielenie dat P_8 i P_80.
3. Uzupełnienie brakujących numerów GLN w kartotekach kontrahentów.
4. Testowa wysyłka XML na bramkę Ministerstwa Finansów.
5. Weryfikacja ograniczenia długości pola P_26 do 100 znaków.
6. Sprawdzenie poprawności certyfikatu KSeF i uprawnień API.
7. Przeprowadzenie "suchego przebiegu" w systemie TETA AIR.

Zaleca się, aby po uzyskaniu pierwszego statusu "200 OK" sporządzić dokumentację techniczną procesu, co ułatwi późniejszy audyt systemów informatycznych. Dobrze wdrożone API nie tylko skraca czas pracy zespołów księgowych, ale przede wszystkim minimalizuje ryzyko błędu ludzkiego przy wprowadzaniu danych operacyjnych, które w nowym systemie mogą być przekazywane w ramach pól opcjonalnych lub dodatkowych.

Najczęstsze błędy mapowania - case study z 3 firm

Analiza wdrożeń w dużych podmiotach gospodarczych wskazuje na powtarzalne schematy błędów, które paraliżują obieg dokumentów. W przypadku hurtowni spożywczej (Firma X), głównym problemem okazało się systematyczne pomijanie pola P_82 (GLN nabywcy), wynikające z błędnego założenia, że pole to jest wyłącznie opcjonalne. Takie sytuacje nie są czysto teoretyczne - znamy przykłady dostawców do dużych sieci handlowych, którzy często słyszą, że faktura bez określonego numeru zamówienia czy kodu GLN nie zostanie przyjęta. W praktyce brak mapowania pola P_82 powodował, że aż 12% faktur wracało do wystawcy jako nieobsługiwane przez systemy logistyczne odbiorców.

Drugi przypadek dotyczy błędu polegającego na przekroczeniu dopuszczalnej długości znaków w polu P_26. System ERP jednego z producentów generował numery zamówień o długości 120 znaków, zawierające wewnętrzne kody sekwencyjne. Chociaż system KSeF przyjął taki dokument (walidacja techniczna XSD dopuszczała dłuższe ciągi w niektórych wersjach), to system SAP nabywcy ucinał dane powyżej 100 znaków, co uniemożliwiało automatyczne sparowanie faktury z zamówieniem. Rozwiązaniem problemu było zastosowanie w procesie ETL funkcji LEFT(100), która przycinała ciąg znaków do limitu akceptowalnego przez standard rynkowy i strukturę FA(3).

Trzeci typowy błąd wiąże się z logiką chronologiczną dat w fakturze ustrukturyzowanej. Kod błędu 422 często pojawia się w sytuacjach, gdy zmapowana data dostawy (P_80) jest wcześniejsza niż data wystawienia lub sprzedaży (P_8). W strukturze FA(3) pole P_80 jest opcjonalne, jednak jego wypełnienie aktywuje dodatkowe reguły walidacyjne. Przykładowy komunikat zwrotny z bramki KSeF w takim przypadku wskazuje na "Niezgodność dat w polach P_8 i P_80". Aby uniknąć takich sytuacji, administratorzy powinni skonfigurować system tak, aby automatycznie blokował eksport faktur naruszających zasady logiczne przed ich wysyłką do repozytorium MF.

Gotowy szablon SQL/ETL do pobrania - mapowanie SAP, Symfonia, TETA AIR

Udostępniony szablon mapowania stanowi fundament dla programistów SQL i konsultantów systemów ERP, pozwalając na skrócenie czasu implementacji o około dwa dni robocze. Dokumentacja techniczna określa, że rozwiązanie jest darmowe do użytku wewnętrznego w przedsiębiorstwach, jednak nie stanowi gwarancji pełnej zgodności z każdą konfiguracją bazodanową. Aktualizacja: wersja 1.0 - czerwiec 2025, zgodna z XSD 1.02 Ministerstwa Finansów. Szablon zawiera 67 gotowych mapowań dla środowiska SAP S/4HANA oraz 59 dla systemu Symfonia Handel, obejmując najbardziej newralgiczne punkty styku danych finansowych z formatem ustrukturyzowanym.

Poniższy fragment kodu SQL ilustruje podstawową strukturę mapowania pięciu kluczowych pól, które najczęściej generują problemy integracyjne. Wykorzystuje on standardowe nazewnictwo pól spotykane w systemach klasy ERP i przypisuje je do odpowiednich tagów XML wymaganych przez Krajowy System e-Faktur:

SELECT OrderNumber AS P_26, GLN AS P_82, SaleDate AS P_8, DeliveryDate AS P_80, CNCode AS P_81 FROM Invoices WHERE ExportStatus = 'Ready';

Zastosowanie powyższego zapytania pozwala na szybkie przygotowanie widoku danych dla szyny integracyjnej. Należy podkreślić, że pełny plik SQL o rozmiarze 4,3 KB zawiera 127 linii kodu, uwzględniających również zaawansowaną obsługę stawek VAT oraz danych transportowych. Przed wdrożeniem produkcyjnym zaleca się uruchomienie narzędzia typu "diff" między własnym schematem XSD a oficjalną wersją opublikowaną w Centralnym Repozytorium Wzorów Dokumentów Elektronicznych (CRWDE), aby upewnić się, że kolejność tagów nie uległa zmianie.