Wtyczki importu faktur

Wtyczka importuje faktury z plików JPK_FA(4) w formacie XML, zgodnych ze schematem JPK_FA obowiązującym na podstawie ustawy o VAT. Pliki odczytywane są z wybranego katalogu. Po przetworzeniu każdy plik przenoszony jest do podkatalogu Processed (sukces) lub Failed (błąd).

1. Konfiguracja wtyczki

Ustawienie	Typ	Wymagane	Domyślna	Opis
SourcePath	ścieżka	Tak	C:\JPK_FA	Katalog źródłowy z plikami JPK_FA XML. Przeszukiwany jest tylko katalog główny (bez podkatalogów).
DuplicateCheckMode	enum	Nie	RejectFile	Sposób obsługi duplikatów: RejectFile — odrzuć cały plik, SkipDuplicate — pomiń duplikat i przetwórz pozostałe, AcceptAll — nie sprawdzaj.
PominOsobyFizyczne	bool	Nie	false	Gdy włączone, faktury bez NIP nabywcy (pole P_5B puste) — faktury dla osób fizycznych — są pomijane podczas importu.
Zaplacono	bool	Nie	false	Gdy włączone, data zapłaty ustawiana jest na datę sprzedaży z faktury (pole P_6).
FormaPlatnosci	enum	Nie	przelew	Forma płatności ustawiana na wszystkich fakturach: gotówka, karta, przelew, inna.
TerminPlatnosciDni	int	Nie	14	Liczba dni od daty wystawienia do terminu płatności. Używane tylko gdy opcja Zaplacono jest wyłączona.

2. Nagłówek faktury — pola JPK_FA

Dane czerpane są ze struktury ZAP_Faktura w pliku JPK_FA. Jeden dokument JPK może zawierać wiele faktur.

Pole JPK_FA	Mapowanie KSeF	Opis
KodWaluty	Fa.KodWaluty	Kod waluty ISO 4217 (np. PLN, EUR)
P_1	Fa.P_1	Data wystawienia faktury (wymagane)
P_2A	Fa.P_2	Numer faktury (wymagane)
P_3A	Podmiot2.DaneIdentyfikacyjne.Nazwa	Imię i nazwisko lub nazwa nabywcy
P_3B	Podmiot2.Adres.AdresL1	Adres nabywcy (w JPK_FA jako jedno pole tekstowe)
P_5A	Podmiot2.Adres.KodKraju	Prefiks kraju nabywcy (kod ISO 2-literowy). Wpływa na rozpoznanie typu stawki 0% (krajowa/WDT/eksport).
P_5B	Podmiot2.DaneIdentyfikacyjne.NIP / PESEL	NIP/identyfikator nabywcy. Puste pole oznacza osobę fizyczną — patrz opcja PominOsobyFizyczne.
P_6	Fa.Item	Data dokonania lub zakończenia dostawy towarów / wykonania usługi
P_13_1 – P_13_7	Fa.P_13_x	Wartości netto wg stawek VAT (23%, 8%, 5%, 0%, zwolniona i inne)
P_14_1 – P_14_5	Fa.P_14_x	Kwoty podatku VAT wg stawek
P_15	Fa.P_15	Kwota należności ogółem (wartość brutto faktury)
P_16	Fa.Adnotacje.P_16	Metoda kasowa (art. 21 ustawy)
P_17	Fa.Adnotacje.P_17	Samofakturowanie (art. 106d ust. 1 ustawy)
P_18	Fa.Adnotacje.P_18	Odwrotne obciążenie
P_18A	Fa.Adnotacje.P_18A	Mechanizm podzielonej płatności (MPP)
RodzajFaktury	Fa.RodzajFaktury	Rodzaj faktury — patrz tabela poniżej
PrzyczynaKorekty	Fa.PrzyczynaKorekty	Przyczyna korekty (tylko dla faktur korygujących)
NrFaKorygowanej	Fa.DaneFaKorygowanej.NrFaKorygowanej	Numer faktury korygowanej (tylko dla faktur korygujących). W JPK FA nie ma numeru KSeF faktury korygującej - odwołanie zawsze będzie do numery własnego faktury.
P_106E_2 / P_106E_3	Fa.Adnotacje.PMarzy	Procedura marży — towary używane, dzieła sztuki, przedmioty kolekcjonerskie i antyki

Obsługiwane rodzaje faktur

Wartość JPK_FA	Rodzaj faktury KSeF	Opis
VAT	TRodzajFaktury.VAT	Faktura VAT (domyślna)
KOREKTA	TRodzajFaktury.KOR	Faktura korygująca
ZAL	TRodzajFaktury.ZAL	Faktura zaliczkowa
inne	TRodzajFaktury.VAT	Nierozpoznana wartość — traktowana jako VAT

3. Pozycje faktury — pola JPK_FA

Dane czerpane ze struktury ZAP_FakturaWiersz w pliku JPK_FA. Każdy wiersz z niepustym polem P_7 tworzy osobną pozycję faktury KSeF (FaWiersz). Wiersze łączone są z fakturą na podstawie pola P_2B (numer faktury).

Pole JPK_FA	Mapowanie KSeF	Precyzja	Opis
P_7	FaWiersz.P_7	—	Nazwa towaru lub usługi (wymagane). Wiersz bez tej wartości jest pomijany.
P_8A	FaWiersz.P_8A	—	Miara dostarczonych towarów lub zakres usług (jednostka miary)
P_8B	FaWiersz.P_8B	—	Ilość (liczba) dostarczonych towarów lub zakres usług
P_9A	FaWiersz.P_9A	4 miejsca	Cena jednostkowa netto. Zaokrąglana do 4 miejsc po przecinku.
P_9B	FaWiersz.P_9B	4 miejsca	Cena jednostkowa brutto (art. 106e ust. 7 i 8). Zaokrąglana do 4 miejsc po przecinku.
P_11	FaWiersz.P_11	2 miejsca	Wartość sprzedaży netto. Zaokrąglana do 2 miejsc po przecinku.
P_11A	FaWiersz.P_11A	2 miejsca	Wartość sprzedaży brutto (art. 106e ust. 7 i 8). Zaokrąglana do 2 miejsc po przecinku.
P_12	FaWiersz.P_12	—	Stawka podatku VAT — patrz tabela stawek poniżej

Uwaga: Wartości liczbowe w plikach JPK_FA mogą zawierać do 12 miejsc po przecinku. Wtyczka automatycznie zaokrągla je do precyzji wymaganej przez schemat KSeF (AwayFromZero).

Obsługiwane stawki VAT w pozycjach

Wartość P_12	Mapowanie KSeF	Opis
23	TStawkaPodatku.Item23	Stawka 23% (domyślna dla nierozpoznanych wartości)
8	TStawkaPodatku.Item8	Stawka 8%
5	TStawkaPodatku.Item5	Stawka 5%
0 (kraj PL)	TStawkaPodatku.Item0KR	Stawka 0% krajowa
0 (kraj UE)	TStawkaPodatku.Item0WDT	Stawka 0% WDT (wewnątrzwspólnotowa dostawa towarów)
0 (kraj poza UE)	TStawkaPodatku.Item0EX	Stawka 0% eksport
ZW	TStawkaPodatku.zw	Zwolniony z VAT
OO	TStawkaPodatku.oo	Odwrotne obciążenie
NP (kraj UE)	TStawkaPodatku.npII	Nie podlega opodatkowaniu — kontrahent z kraju UE
NP (kraj poza UE)	TStawkaPodatku.npI	Nie podlega opodatkowaniu — kontrahent spoza UE
NP (kraj PL)	❌ Błąd	Stawka NP nie jest obsługiwana przez KSeF dla kontrahentów krajowych — faktura zostanie odrzucona.
22	TStawkaPodatku.Item22	Stawka 22% (historyczna)
7	TStawkaPodatku.Item7	Stawka 7% (historyczna)
inne	TStawkaPodatku.Item23	Nierozpoznana stawka — domyślnie 23%

Uwaga: Wybór wariantu stawki 0% (krajowa/WDT/eksport) następuje automatycznie na podstawie pola P_5A (prefiks kraju nabywcy): brak lub PL → 0KR, kraj UE → 0WDT, kraj poza UE → 0EX.

4. Przetwarzanie transakcyjne i archiwizacja

Plik JPK_FA przetwarzany jest w dwóch fazach:

1.Walidacja — sprawdzenie wszystkich faktur w pliku (numery, duplikaty). Błąd w jakiejkolwiek fakturze powoduje odrzucenie całego pliku w trybie RejectFile.

2.Zapis — faktury zapisywane są kolejno. W razie błędu wszystkie już zapisane faktury z tego pliku zostają wycofane (rollback).

Po zakończeniu przetwarzania plik przenoszony jest:

•{SourcePath}\Processed\{timestamp}_{nazwapliku} — przetworzono pomyślnie

•{SourcePath}\Failed\{timestamp}_{nazwapliku} — wystąpił błąd (szczegóły w dzienniku błędów)

Uwaga: Żaden plik nie jest pomijany bez archiwizacji. Pliki, których struktura nie odpowiada schematowi JPK_FA (brak nagłówka namespace jpk.mf.gov.pl) są ignorowane (nie archiwizowane) — nie są plikami JPK_FA.

5. Ograniczenia konwersji

Konwersja JPK_FA(4) na KSeF jest uproszczona ze względu na różnice między schematami. Poniższe informacje z JPK_FA nie są przenoszone do KSeF:

•Dane sprzedawcy (Podmiot1) — uzupełniane automatycznie z konfiguracji KSeF

•Miejsce wystawienia faktury (P_1M) — brak odpowiednika w JPK_FA

•Dane nowych środków transportu

•Kurs waluty (KursWalutyZ)

•Zwolnienia podmiotowe z adnotacjami tekstowymi (P_19A, P_19B, P_19C) — przenoszone jako flaga bez tekstu