Mapowanie pól faktury PDF na elementy XML FA(3)

Konwerter PDF na XML FA(3) odczytuje treść faktury i przypisuje każdą wartość do konkretnego elementu schematu Ministerstwa Finansów. Efektem nie jest „plik XML z danymi", tylko dokument o ściśle określonej strukturze, w którym numer faktury trafia do P_2, data wystawienia do P_1, a każda pozycja do osobnego elementu FaWiersz. Poniżej pokazujemy dokładnie, co z czego powstaje.

Ten tekst jest opisem mapowania pól. Jeżeli szukasz przebiegu pracy krok po kroku, znajdziesz go w przewodniku jak przekonwertować fakturę PDF do KSeF.

Co konwerter musi rozpoznać

Faktura PDF nie ma pól — ma tekst rozmieszczony na stronie. Konwerter musi więc rozstrzygnąć trzy rzeczy naraz: który podmiot jest sprzedawcą, a który nabywcą; która liczba jest wartością netto, a która brutto; oraz które fragmenty tabeli tworzą jedną pozycję faktury.

Rozpoznanie nie opiera się na stałych współrzędnych. Ten sam element bywa opisany różnie w zależności od programu, który wygenerował dokument:

• „NIP", „Nr identyfikacji podatkowej", „VAT ID" — to samo pole
• „Data wystawienia", „Wystawiono dnia", „Data dok." — to samo pole
• „Razem", „Do zapłaty", „Suma brutto" — najczęściej ta sama wartość
• „Sprzedawca" / „Wystawca" oraz „Nabywca" / „Odbiorca" / „Płatnik"

Dopiero po ustaleniu znaczenia fragmentów można przystąpić do budowy struktury XML.

Mapowanie pól — sprzedawca i nabywca

NIP zapisywany jest jako dziesięć cyfr. Prefiks PL, spacje i myślniki występujące na dokumencie są usuwane przy konwersji, ponieważ schemat ich nie dopuszcza.

W sekcji nabywcy schemat oczekuje dodatkowo elementów dotyczących jednostek samorządu terytorialnego i grup VAT. Dla zwykłej transakcji między firmami przyjmują wartość oznaczającą „nie dotyczy", ale muszą być obecne — ich pominięcie powoduje odrzucenie pliku.

Mapowanie pól — nagłówek dokumentu

Warto zwrócić uwagę na rozróżnienie, które bywa mylone: P_1 to data wystawienia faktury, natomiast DataWytworzeniaFa w nagłówku pliku to moment wygenerowania samego XML-a. To dwie różne wartości i schemat traktuje je odrębnie.

Jeżeli faktura dotyczy okresu rozliczeniowego — na przykład abonamentu miesięcznego — zamiast P_6 stosuje się parę dat początku i końca okresu. Nie należy podawać obu wariantów jednocześnie.

Mapowanie pól — pozycje i VAT

Każdy wiersz tabeli na fakturze staje się osobnym elementem FaWiersz:

Stawka podawana jest ze słownika: wartości liczbowe dla stawek podstawowych oraz oznaczenia zw dla zwolnienia i np dla czynności niepodlegających opodatkowaniu. Konwerter musi rozpoznać także zapis opisowy — „zwolniona", „zw.", „VAT zw" prowadzą do tej samej wartości w XML.

Podsumowanie VAT budowane jest przez zsumowanie pozycji w obrębie każdej stawki, a nie przez przepisanie liczby z dołu dokumentu. Dzięki temu niezgodność między sumą pozycji a podsumowaniem wychodzi na etapie konwersji, a nie po odrzuceniu przez KSeF.

Pełne zestawienie sekcji i ich kolejności opisaliśmy w opracowaniu schematu FA(3) i pól wymaganych.

Płatność — miejsce, w którym najczęściej powstaje błędny plik

Sekcja płatności ma reguły warunkowe, których nie widać na fakturze. Jeśli dokument jest oznaczony jako zapłacony, schemat wymaga podania daty zapłaty i jednocześnie zabrania podawania terminu płatności. Jeśli faktura ma odroczony termin — obowiązuje sytuacja odwrotna.

Konwerter musi więc rozstrzygnąć status płatności na podstawie treści dokumentu („zapłacono", „do zapłaty", „forma płatności: gotówka") i dopiero wtedy zbudować sekcję. Typowe komunikaty walidatora wynikające z tej reguły omawiamy w zestawieniu błędów walidacji XML FA(3).

Kontrola wyniku

Wygenerowany plik przechodzi walidację względem schematu XSD jeszcze przed pobraniem — sprawdzana jest kolejność elementów, obecność pól wymaganych oraz formaty dat i liczb. Jeżeli chcesz sprawdzić plik pochodzący z innego systemu, skorzystaj z walidatora KSeF XML.

Najczęstsze pytania

Czy konwerter działa na fakturach z dowolnego programu? Tak. Rozpoznanie opiera się na treści, a nie na stałym układzie strony, więc nie wymaga szablonu dla konkretnego wystawcy.

Co się dzieje, gdy faktura ma pozycje w kilku stawkach VAT? Podsumowanie budowane jest osobno dla każdej stawki, zgodnie z wymaganiami schematu. Wartości wyliczane są z pozycji.

Czy mogę poprawić odczytane dane przed pobraniem pliku? Tak. Wszystkie wartości są edytowalne, a zmiana od razu przekłada się na generowany XML.

Czy plik XML FA(3) można zaimportować do programu księgowego? To format przeznaczony dla KSeF. Do importu do systemów księgowych służą odrębne formaty — omawiamy je przy okazji Comarch ERP Optima.

Co z fakturami korygującymi? Korekta ma odrębny rodzaj w schemacie i wymaga dodatkowych pól. Warto zweryfikować rozpoznany rodzaj dokumentu przed wysyłką.

Sprawdź na własnej fakturze

Wgraj dokument i porównaj wygenerowany XML z oryginałem — uruchom konwerter PDF do KSeF FA(3). Przy większych wolumenach zobacz opis masowej konwersji faktur.