Dokumentacja pól importu faktur — pluginy Excel i CSV

<< Pokaż spis treści >>

Nawigacja:  Wtyczki importu faktur >

Dokumentacja pól importu faktur — pluginy Excel i CSV

Oba pluginy (Excel .xlsx i CSV .csv) odczytują te same nazwy kolumn/pól. Wiersze z tym samym numerem faktury (numer) są grupowane w jedną fakturę z wieloma pozycjami.

 

Podsumowanie obsługi pól

Status

Znaczenie

✅ Mapowane

Pole odczytywane i mapowane na strukturę KSeF (Faktura)

￿ Odczytywane

Pole odczytywane z pliku (CSV), ale jeszcze niemapowane na KSeF

❌ Nieobsługiwane

Pole nie jest rozpoznawane przez plugin

Porównanie obsługi pól

Pole

Excel

CSV

Opis

numer

✅

✅

Numer faktury (wymagane)

rodzaj

✅

✅

Rodzaj dokumentu

data_wyst

✅

✅

Data wystawienia (wymagane)

data_dost

✅

✅

Data dostawy

waluta

✅

✅

Kod waluty

nazwa

✅

✅

Nazwa kontrahenta

nip

✅

✅

NIP kontrahenta

kraj

✅

✅

Kod kraju

adres

✅

✅

Adres kontrahenta

miejscowosc

✅

✅

Miejscowość

kod_poczt

✅

✅

Kod pocztowy

email

✅

✅

E-mail kontrahenta

nabywca_ist

✅

✅

Jednostka samorządu terytorialnego (JST)

nabywca_gv

✅

✅

Grupa VAT (GV)

odbiorca_nazwa

✅

✅

Nazwa odbiorcy (Podmiot3)

odbiorca_nip

✅

✅

NIP odbiorcy

odbiorca_kraj

✅

✅

Kod kraju odbiorcy

odbiorca_adres

✅

✅

Adres odbiorcy

odbiorca_miejscowosc

✅

✅

Miejscowość odbiorcy

odbiorca_kod_poczt

✅

✅

Kod pocztowy odbiorcy

odbiorca_email

✅

✅

E-mail odbiorcy

odbiorca_idwew

✅

✅

Identyfikator wewnętrzny odbiorcy

odbiorca_rola

✅

✅

Rola Podmiotu3 (domyślnie: odbiorca)

platnik_nazwa

✅

✅

Nazwa płatnika (Podmiot3)

platnik_nip

✅

✅

NIP płatnika

platnik_kraj

✅

✅

Kod kraju płatnika

platnik_adres

✅

✅

Adres płatnika

platnik_miejscowosc

✅

✅

Miejscowość płatnika

platnik_kod_poczt

✅

✅

Kod pocztowy płatnika

platnik_email

✅

✅

E-mail płatnika

platnik_idwew

✅

✅

Identyfikator wewnętrzny płatnika

platnik_rola

✅

✅

Rola Podmiotu3 (domyślnie: płatnik)

nazwa_pozycji

✅

✅

Nazwa pozycji

gtin

✅

✅

GTIN/EAN pozycji

indeks

✅

✅

Indeks towaru/usługi

pkwiu

✅

✅

Symbol PKWiU

cn

✅

✅

Kod CN

netto_brutto

✅

✅

Sposób obliczania (N/B)

stawka_vat

✅

✅

Stawka VAT

jm

✅

✅

Jednostka miary

ilosc

✅

✅

Ilość

cena

✅

✅

Cena jednostkowa

wartosc

✅

✅

Wartość pozycji

wartosc_vat

✅

✅

Wartość VAT pozycji

zaplacono

✅

✅

Czy faktura zapłacona

termin_plat

✅

✅

Termin płatności

forma_plat

✅

✅

Forma płatności

forma_plat_opis

✅

✅

Opis formy płatności (płatność inna)

data_zaplaty

✅

✅

Data zapłaty (wymagana gdy zaplacono = tak)

bank_konto

✅

✅

Numer rachunku bankowego

bank_swift

✅

✅

Kod SWIFT/BIC banku

bank_nazwa

✅

✅

Nazwa banku

bank_opis

✅

✅

Opis rachunku bankowego

bank2_konto

✅

✅

Numer drugiego rachunku bankowego

bank2_swift

✅

✅

Kod SWIFT/BIC drugiego banku

bank2_nazwa

✅

✅

Nazwa drugiego banku

bank2_opis

✅

✅

Opis drugiego rachunku bankowego

nr_dok_korygowanego

✅

✅

Numer dokumentu korygowanego

nr_dok_korygowanego_ksef

✅

✅

Numer KSeF dokumentu korygowanego

przyczyna_korekty

✅

✅

Przyczyna korekty

data_dok_korygowanego

✅

✅

Data dokumentu korygowanego

opis

✅

✅

Komentarz (DodatkowyOpis)

dodopis_1_klucz–dodopis_9_klucz

✅

✅

Klucz dodatkowego opisu (DodatkowyOpis[].Klucz)

dodopis_1_wartosc–dodopis_9_wartosc

✅

✅

Wartość dodatkowego opisu (DodatkowyOpis[].Wartosc)

nr_wz

✅

✅

Numer dokumentu WZ (wydanie zewnętrzne). → Fa.WZ[]

nr_zamowienia

✅

✅

Numer zamówienia. → Fa.WarunkiTransakcji.Zamowienia[].NrZamowienia

umowa_numer

✅

✅

Numer umowy. → Fa.WarunkiTransakcji.Umowy[].NrUmowy

umowa_data

✅

✅

Data umowy. → Fa.WarunkiTransakcji.Umowy[].DataUmowy

mpp

✅

✅

Mech. Podz. Płatności (P_18A)

tp

✅

✅

Transakcje z podmiotami powiązanymi (Fa.TP)

fp

✅

✅

Faktura do paragonu (Fa.FP)

nr_wz

✅

✅

Numer dokumentu WZ (Fa.WZ)

nr_zamowienia

✅

✅

Numer zamówienia (WarunkiTransakcji)

umowa_numer

✅

✅

Numer umowy (WarunkiTransakcji)

umowa_data

✅

✅

Data umowy (WarunkiTransakcji)

gtu_01–gtu_13

✅

✅

Oznaczenia GTU (FaWiersz)

kurs

✅

✅

Kurs waluty

Procedury JPK

✅

✅

Procedury KSeF (FaWiersz)

 
 

1. Dane podstawowe faktury

Pole

Typ

Wymagane

Domyślna

Excel

CSV

Opis

numer

string

Tak

—

✅

✅

Numer dokumentu. Wiersze z tą samą wartością są grupowane w jedną fakturę. Pusta wartość = wiersz pomijany.

rodzaj

string

Nie

VAT

✅

✅

Rodzaj dokumentu. Odczytywany z pierwszego wiersza grupy.

data_wyst

data

Tak

bieżąca data

✅

✅

Data wystawienia dokumentu. Odczytywana z pierwszego wiersza grupy.

Obsługiwane rodzaje

Wartość

Rodzaj faktury KSeF

Opis

VAT lub FS

TRodzajFaktury.VAT

Faktura VAT (domyślna)

KOR

TRodzajFaktury.KOR

Faktura korygująca

ZAL

TRodzajFaktury.ZAL

Faktura zaliczkowa

ROZ

TRodzajFaktury.ROZ

Faktura rozliczeniowa

Uwaga CSV: Pole rodzaj w CSV obsługuje dodatkowe wartości zdefiniowane w modelu: FS, WDT, WDU, EXU, EXP, FM, FZ, WNT, WNU, IMU, IMP, FZM, PA — jednak tylko FS/VAT, KOR, ZAL, ROZ są mapowane na typy KSeF. Pozostałe traktowane są jako VAT.

 

2. Dane kontrahenta (nabywcy)

Dane odczytywane z pierwszego wiersza grupy o danym numerze faktury.

Pole

Typ

Wymagane

Domyślna

Excel

CSV

Opis

nazwa

string

Nie

Nabywca

✅

✅

Pełna nazwa kontrahenta (nabywcy)

nip

string

Nie

—

✅

✅

NIP kontrahenta. Dla kontrahentów zagranicznych z prefixem kraju (np. DE123456789). Automatyczne rozpoznanie NIP/PESEL/BrakID.

kraj

string

Nie

PL

✅

✅

Kod kraju ISO 3166-1 alpha-2 (2 litery)

adres

string

Nie

—

✅

✅

Ulica i numer lokalu → mapowane na AdresL2

miejscowosc

string

Nie

—

✅

✅

Miejscowość → mapowane na AdresL1 (z kodem pocztowym)

kod_poczt

string

Nie

—

✅

✅

Kod pocztowy → mapowane na AdresL1 (z miejscowością)

email

string

Nie

—

✅

✅

Adres e-mail kontrahenta → mapowane na DaneKontaktowe

nabywca_ist

string

Nie

—

✅

✅

Jednostka samorządu terytorialnego: 1 = JST, 2 = jednostka organizacyjna JST → mapowane na Podmiot2.JST

nabywca_gv

string

Nie

—

✅

✅

Grupa VAT: 1 = przedstawiciel grupy VAT, 2 = członek grupy VAT → mapowane na Podmiot2.GV

Mapowanie adresu na strukturę KSeF

AdresL1 = "{kod_poczt}, {miejscowosc}"
AdresL2 = "{adres}"
KodKraju = ParseKodKraju("{kraj}")

3. Pozycje faktury

Każdy wiersz w pliku (z niepustym polem nazwa_pozycji) tworzy osobną pozycję faktury.

Pole

Typ

Wymagane

Domyślna

Excel

CSV

Opis

gtin

string

Nie

—

✅

✅

Globalny numer jednostki handlowej (GTIN/EAN) → FaWiersz.GTIN

indeks

string

Nie

—

✅

✅

Indeks towaru/usługi sprzedawcy → FaWiersz.Indeks

pkwiu

string

Nie

—

✅

✅

Symbol PKWiU towaru/usługi → FaWiersz.PKWiU

cn

string

Nie

—

✅

✅

Kod CN (Nomenklatura Scalona) → FaWiersz.CN

nazwa_pozycji

string

Tak*

—

✅

✅

Nazwa towaru/usługi. Wiersz bez nazwy pozycji jest pomijany.

netto_brutto

string

Nie

N

✅

✅

Sposób obliczania: N = netto (domyślnie), B = brutto. Określa interpretację pól cena i wartosc.

stawka_vat

string

Nie

—

✅

✅

Stawka VAT — patrz tabela poniżej

jm

string

Nie

szt

✅

✅

Jednostka miary (P_8A)

ilosc

decimal

Nie

1

✅

✅

Ilość (P_8B)

cena

decimal

Nie

obliczana

✅

✅

Cena jednostkowa. Gdy netto_brutto = N → P_9A (netto). Gdy B → P_9B (brutto), P_9A obliczane. Gdy brak — obliczana z wartosc / ilosc.

wartosc

decimal

Nie

0

✅

✅

Wartość pozycji. Gdy netto_brutto = N → P_11 (netto). Gdy B → P_11A (brutto), P_11 obliczane.

wartosc_vat

decimal

Nie

obliczana

✅

✅

Wartość VAT pozycji (P_11Vat). Gdy brak — obliczana automatycznie.

* Wymagane dla pozycji — wiersz bez nazwa_pozycji jest pomijany (nie tworzy pozycji).
 

Obsługiwane stawki vat

Wartość

Mapowanie KSeF

Opis

23

TStawkaPodatku.Item23

Stawka 23%

22

TStawkaPodatku.Item22

Stawka 22%

8

TStawkaPodatku.Item8

Stawka 8%

7

TStawkaPodatku.Item7

Stawka 7%

5

TStawkaPodatku.Item5

Stawka 5%

4

TStawkaPodatku.Item4

Stawka 4%

3

TStawkaPodatku.Item3

Stawka 3%

0 lub 0 KR

TStawkaPodatku.Item0KR

Stawka 0% (krajowa)

0 WDT

TStawkaPodatku.Item0WDT

Stawka 0% (WDT)

0 EX

TStawkaPodatku.Item0EX

Stawka 0% (eksport)

ZW

TStawkaPodatku.zw

Zwolniony z VAT

OO

TStawkaPodatku.oo

Odwrotne obciążenie

NP lub NP I

TStawkaPodatku.npI

Nie podlega opodatkowaniu (I)

NP II

TStawkaPodatku.npII

Nie podlega opodatkowaniu (II)

Uwaga: Gdy stawka_vat nie pasuje do żadnej z powyższych wartości, domyślnie przyjmowana jest stawka 23%.

Automatyczne obliczanie cen, wartości i VAT

Tryb netto (netto_brutto = N lub puste, domyślny):

wartosc                    → P_11 (wartość netto)
cena (lub wartosc / ilosc) → P_9A (cena netto)
wartosc_vat (lub netto × stawka%) → P_11Vat

Tryb brutto (netto_brutto = B):

wartosc                    → P_11A (wartość brutto)
wartosc / (1 + stawka%)    → P_11  (wartość netto, obliczana)
cena (lub wartosc / ilosc) → P_9B  (cena brutto)
cena / (1 + stawka%)       → P_9A  (cena netto, obliczana)
wartosc_vat (lub brutto - netto) → P_11Vat

Uwaga: Tryb brutto wymaga podania stawka_vat. Bez stawki VAT pozycja jest traktowana jak netto.

Automatyczne sumowanie wg stawek VAT

Oba pluginy automatycznie sumują wartości netto i VAT po stawkach, wypełniając pola:

•P_13_1 / P_14_1 — stawka 23%

•P_13_2 / P_14_2 — stawka 8%

•P_13_3 / P_14_3 — stawka 5%

•P_13_4 / P_14_4 — stawka 0%

•P_13_5 / P_14_5 — zwolnione (ZW)

•P_15 — suma brutto (netto + VAT) ze wszystkich pozycji

4. Daty dodatkowe

Pole

Typ

Wymagane

Domyślna

Excel

CSV

Opis

data_dost

data

Nie

—

✅

✅

Data zakończenia dostawy/sprzedaży. Gdy podana, mapowana na Fa.Item.

5. Dane odbiorcy (Podmiot3)

Dane odbiorcy są mapowane na Faktura.Podmiot3[] z odpowiednią rolą. Odczytywane z pierwszego wiersza grupy.

Pole

Typ

Wymagane

Domyślna

Excel

CSV

Opis

odbiorca_nazwa

string

Nie*

—

✅

✅

Nazwa odbiorcy → Podmiot3.DaneIdentyfikacyjne.Nazwa

odbiorca_nip

string

Nie*

—

✅

✅

NIP odbiorcy (z prefixem kraju dla zagranicznych). Automatyczne rozpoznanie NIP/PESEL/BrakID.

odbiorca_kraj

string

Nie

PL

✅

✅

Kod kraju ISO 3166-1 alpha-2 → Podmiot3.Adres.KodKraju

odbiorca_adres

string

Nie

—

✅

✅

Ulica i numer lokalu → Podmiot3.Adres.AdresL2

odbiorca_miejscowosc

string

Nie

—

✅

✅

Miejscowość → Podmiot3.Adres.AdresL1

odbiorca_kod_poczt

string

Nie

—

✅

✅

Kod pocztowy → Podmiot3.Adres.AdresL1

odbiorca_email

string

Nie

—

✅

✅

E-mail odbiorcy → Podmiot3.DaneKontaktowe.Email

odbiorca_idwew

string

Nie

—

✅

✅

Identyfikator wewnętrzny. Gdy podany, używany zamiast NIP → Podmiot3.DaneIdentyfikacyjne.IDWew

odbiorca_rola

string

Nie

odbiorca (2)

✅

✅

Rola Podmiotu3 — patrz tabela ról

* Podmiot3 (odbiorca) jest tworzony tylko gdy wypełnione jest odbiorca_nazwa, odbiorca_nip lub odbiorca_idwew.

6. Dane płatnika (Podmiot3)

Dane płatnika są mapowane na Faktura.Podmiot3[] z odpowiednią rolą. Odczytywane z pierwszego wiersza grupy.

Pole

Typ

Wymagane

Domyślna

Excel

CSV

Opis

platnik_nazwa

string

Nie*

—

✅

✅

Nazwa płatnika → Podmiot3.DaneIdentyfikacyjne.Nazwa

platnik_nip

string

Nie*

—

✅

✅

NIP płatnika (z prefixem kraju dla zagranicznych). Automatyczne rozpoznanie NIP/PESEL/BrakID.

platnik_kraj

string

Nie

PL

✅

✅

Kod kraju ISO 3166-1 alpha-2 → Podmiot3.Adres.KodKraju

platnik_adres

string

Nie

—

✅

✅

Ulica i numer lokalu → Podmiot3.Adres.AdresL2

platnik_miejscowosc

string

Nie

—

✅

✅

Miejscowość → Podmiot3.Adres.AdresL1

platnik_kod_poczt

string

Nie

—

✅

✅

Kod pocztowy → Podmiot3.Adres.AdresL1

platnik_email

string

Nie

—

✅

✅

E-mail płatnika → Podmiot3.DaneKontaktowe.Email

platnik_idwew

string

Nie

—

✅

✅

Identyfikator wewnętrzny. Gdy podany, używany zamiast NIP → Podmiot3.DaneIdentyfikacyjne.IDWew

platnik_rola

string

Nie

jst_wystawca (7)

✅

✅

Rola Podmiotu3 — patrz tabela ról

* Podmiot3 (płatnik) jest tworzony tylko gdy wypełnione jest platnik_nazwa, platnik_nip lub platnik_idwew.

Uwaga: Odbiorca i płatnik mogą być jednocześnie obecni na fakturze — tworzą osobne wpisy w tablicy Podmiot3[].

7. Płatność

Dane płatności są mapowane na Faktura.Fa.Platnosc. Odczytywane z pierwszego wiersza grupy. Sekcja płatności jest tworzona tylko gdy przynajmniej jedno z pól płatności jest wypełnione.

Pole

Typ

Wymagane

Domyślna

Excel

CSV

Opis

zaplacono

string

Nie

nie

✅

✅

Czy faktura jest zapłacona (1, T, TAK, TRUE = tak). Gdy zapłacona — termin płatności nie jest zapisywany. → Platnosc.Zaplacono

termin_plat

data

Nie

—

✅

✅

Termin płatności. Ignorowany gdy zaplacono = tak. → Platnosc.TerminPlatnosci[].Termin

forma_plat

string

Nie

—

✅

✅

Forma płatności — patrz tabela poniżej. → Platnosc.FormaPlatnosci

forma_plat_opis

string

Nie

—

✅

✅

Opis formy płatności innej. Gdy podany — forma płatności ustawiana na PlatnoscInna z opisem. Pole forma_plat jest wtedy ignorowane. → Platnosc.PlatnoscInna + Platnosc.OpisPlatnosci

bank_konto

string

Nie

—

✅

✅

Numer rachunku bankowego. → Platnosc.RachunekBankowy[].NrRB

bank_swift

string

Nie

—

✅

✅

Kod SWIFT/BIC banku. → Platnosc.RachunekBankowy[].SWIFT

bank_nazwa

string

Nie

—

✅

✅

Nazwa banku. → Platnosc.RachunekBankowy[].NazwaBanku

bank_opis

string

Nie

—

✅

✅

Opis rachunku bankowego. → Platnosc.RachunekBankowy[].OpisRachunku

bank2_konto

string

Nie

—

✅

✅

Numer drugiego rachunku bankowego. → Platnosc.RachunekBankowy[1].NrRB

bank2_swift

string

Nie

—

✅

✅

Kod SWIFT/BIC drugiego banku. → Platnosc.RachunekBankowy[1].SWIFT

bank2_nazwa

string

Nie

—

✅

✅

Nazwa drugiego banku. → Platnosc.RachunekBankowy[1].NazwaBanku

bank2_opis

string

Nie

—

✅

✅

Opis drugiego rachunku bankowego. → Platnosc.RachunekBankowy[1].OpisRachunku

Obsługiwane formy płatności

Wartość

Mapowanie KSeF

Opis

1, G, GOT, GOTÓWKA

TFormaPlatnosci.Item1

Gotówka

2, K, KARTA

TFormaPlatnosci.Item2

Karta

3, BON

TFormaPlatnosci.Item3

Bon

4, CZEK

TFormaPlatnosci.Item4

Czek

5, KREDYT

TFormaPlatnosci.Item5

Kredyt

6, P, PRZELEW

TFormaPlatnosci.Item6

Przelew

7, M, MOBILNA

TFormaPlatnosci.Item7

Płatność mobilna

Logika zapisu płatności

Jeżeli zaplacono = tak:
    → Platnosc.Zaplacono = 1 (termin płatności NIE jest zapisywany)
Jeżeli zaplacono = nie i termin_plat podany:
    → Platnosc.TerminPlatnosci = termin_plat
Jeżeli forma_plat_opis podany:
    → Platnosc.PlatnoscInna = 1, OpisPlatnosci = forma_plat_opis
W przeciwnym razie jeżeli forma_plat podany:
    → Platnosc.FormaPlatnosci = parsowana wartość

8. Korekta

Dane korekty są mapowane na fakturę KSeF tylko gdy rodzaj = KOR. Odczytywane z pierwszego wiersza grupy.

Pole

Typ

Wymagane

Domyślna

Excel

CSV

Opis

nr_dok_korygowanego

string

Nie*

—

✅

✅

Zwykły numer dokumentu korygowanego. → DaneFaKorygowanej[].NrFaKorygowanej z NrKSeFN = 1

nr_dok_korygowanego_ksef

string

Nie*

—

✅

✅

Numer KSeF dokumentu korygowanego. → Fa.NrFaKorygowany

przyczyna_korekty

string

Nie

—

✅

✅

Przyczyna powstania korekty → Fa.PrzyczynaKorekty

data_dok_korygowanego

data

Nie

—

✅

✅

Data dokumentu korygowanego → DaneFaKorygowanej[].DataWystFaKorygowanej (tylko z nr_dok_korygowanego)

* Tylko jedno z pól nr_dok_korygowanego / nr_dok_korygowanego_ksef powinno być wypełnione.

Logika zapisu korekty

Jeżeli rodzaj ≠ KOR:
    → pola korekty są ignorowane
Jeżeli nr_dok_korygowanego_ksef podany:
    → Fa.NrFaKorygowany = nr_dok_korygowanego_ksef
Jeżeli nr_dok_korygowanego podany (bez numeru KSeF):
    → DaneFaKorygowanej.NrFaKorygowanej = nr_dok_korygowanego
    → DaneFaKorygowanej.NrKSeFN = 1 (brak numeru KSeF)
    → DaneFaKorygowanej.DataWystFaKorygowanej = data_dok_korygowanego (jeśli podana)
Jeżeli przyczyna_korekty podana:
    → Fa.PrzyczynaKorekty = przyczyna_korekty

9. Dodatkowe informacje

Pole

Typ

Wymagane

Domyślna

Excel

CSV

Opis

opis

string

Nie

—

✅

✅

Tekstowy opis/komentarz dokumentu. Mapowany na Fa.DodatkowyOpis[] z kluczem UWAGI.

mpp

string

Nie

—

✅

✅

Mechanizm Podzielonej Płatności (1, T, TAK, TRUE = tak). → Fa.Adnotacje.P_18A (1 = tak, 2 = nie)

tp

string

Nie

—

✅

✅

Transakcje z podmiotami powiązanymi (1, T, TAK, TRUE = tak). → Fa.TP

fp

string

Nie

—

✅

✅

Faktura do paragonu (1, T, TAK, TRUE = tak). → Fa.FP

10. Oznaczenia GTU (JPK_V7M)

Pola odczytywane z każdego wiersza (per pozycja faktury). Wartość 1 lub T oznacza aktywne. Każdy wiersz faktury może mieć co najwyżej jedno oznaczenie GTU. Pierwszy aktywny GTU jest mapowany na FaWiersz.GTU.

Pole

Excel

CSV

Mapowanie KSeF

Opis

gtu_01

✅

✅

TGTU.GTU_01

Dostawa napojów alkoholowych

gtu_02

✅

✅

TGTU.GTU_02

Dostawa paliw

gtu_03

✅

✅

TGTU.GTU_03

Dostawa oleju opałowego

gtu_04

✅

✅

TGTU.GTU_04

Dostawa wyrobów tytoniowych

gtu_05

✅

✅

TGTU.GTU_05

Dostawa odpadów

gtu_06

✅

✅

TGTU.GTU_06

Dostawa urządzeń elektronicznych

gtu_07

✅

✅

TGTU.GTU_07

Dostawa pojazdów i części

gtu_08

✅

✅

TGTU.GTU_08

Dostawa metali szlachetnych

gtu_09

✅

✅

TGTU.GTU_09

Dostawa produktów leczniczych

gtu_10

✅

✅

TGTU.GTU_10

Dostawa budynków/budowli/gruntów

gtu_11

✅

✅

TGTU.GTU_11

Świadczenie usług w zakresie emisji gazów

gtu_12

✅

✅

TGTU.GTU_12

Świadczenie usług niematerialnych

gtu_13

✅

✅

TGTU.GTU_13

Świadczenie usług transportowych

11. Procedury (JPK_V7M)

Pola odczytywane z każdego wiersza (per pozycja faktury). Wartość 1 lub T oznacza aktywne. Każdy wiersz faktury może mieć co najwyżej jedną procedurę. Pierwsza aktywna procedura jest mapowana na FaWiersz.Procedura.

Procedury mapowane na KSeF (TOznaczenieProcedury)

Pole

Excel

CSV

Mapowanie KSeF

Opis

WSTO_EE

✅

✅

TOznaczenieProcedury.WSTO_EE

Wewnątrzwspólnotowa sprzedaż towarów na odległość

IED

✅

✅

TOznaczenieProcedury.IED

Interfejs elektroniczny, dostawca

TT_D

✅

✅

TOznaczenieProcedury.TT_D

Transakcja trójstronna — dostawa

I_42

✅

✅

TOznaczenieProcedury.I_42

Procedura celna 42 — import

I_63

✅

✅

TOznaczenieProcedury.I_63

Procedura celna 63 — import

B_SPV

✅

✅

TOznaczenieProcedury.B_SPV

Transfer bonu jednego przeznaczenia

B_SPV_DOSTAWA

✅

✅

TOznaczenieProcedury.B_SPV_DOSTAWA

Dostawa towarów — bon jednego przeznaczenia

B_MPV_PROWIZJA

✅

✅

TOznaczenieProcedury.B_MPV_PROWIZJA

Prowizja od bonu różnego przeznaczenia

12. Waluta i kurs

Pole

Typ

Wymagane

Domyślna

Excel

CSV

Opis

waluta

string

Nie

PLN

✅

✅

Kod waluty ISO 4217 (np. PLN, EUR, USD). Mapowane na Fa.KodWaluty.

kurs

decimal

Nie

—

✅

✅

Kurs waluty. Mapowany tylko gdy waluta ≠ PLN i kurs ≠ 0. Przypisywany do każdego wiersza faktury. → FaWiersz.KursWaluty

Różnice między pluginami

Pola obsługiwane tylko przez Excel

Brak — wszystkie pola są obsługiwane przez oba pluginy.

Pola obsługiwane tylko przez CSV (odczytywane, ale niezamapowane na KSeF)

Plugin CSV definiuje model CsvInvoiceRecord z pełną listą pól struktury KT Soft. Poniższe pola są parsowane z pliku CSV, ale nie są jeszcze mapowane na strukturę KSeF Faktura:

•Daty: data_wplywu

•Kontrahent: kontrah_klucz, skrot_nazwy

Wspólne pola mapowane na KSeF (100% zgodne)

Oba pluginy identycznie mapują następujące pola na strukturę KSeF Faktura:

Pole

Mapowanie KSeF

numer

Fa.P_2

data_wyst

Fa.P_1 (via FakturaHelper.CreateInvoiceTemplate)

data_dost

Fa.Item

rodzaj

Fa.RodzajFaktury

waluta

Fa.KodWaluty

kurs

FaWiersz.KursWaluty (gdy waluta ≠ PLN i kurs ≠ 0)

nazwa

Podmiot2.DaneIdentyfikacyjne.Nazwa

nip

Podmiot2.DaneIdentyfikacyjne (NIP/PESEL/BrakID)

kraj

Podmiot2.Adres.KodKraju

adres

Podmiot2.Adres.AdresL2

miejscowosc + kod_poczt

Podmiot2.Adres.AdresL1

nabywca_ist

Podmiot2.JST

nabywca_gv

Podmiot2.GV

email

Podmiot2.DaneKontaktowe.Email

odbiorca_*

Podmiot3[].DaneIdentyfikacyjne/Adres/DaneKontaktowe (rola: odbiorca)

platnik_*

Podmiot3[].DaneIdentyfikacyjne/Adres/DaneKontaktowe (rola: płatnik)

nazwa_pozycji

FaWiersz.P_7

jm

FaWiersz.P_8A

ilosc

FaWiersz.P_8B

wartosc

FaWiersz.P_11 (netto) / FaWiersz.P_11A (brutto)

wartosc_vat

FaWiersz.P_11Vat

stawka_vat

FaWiersz.P_12

cena

FaWiersz.P_9A (netto) / FaWiersz.P_9B (brutto)

netto_brutto

określa tryb obliczeń (N = netto, B = brutto)

zaplacono

Fa.Platnosc.Zaplacono

termin_plat

Fa.Platnosc.TerminPlatnosci[].Termin

forma_plat

Fa.Platnosc.FormaPlatnosci

forma_plat_opis

Fa.Platnosc.PlatnoscInna + OpisPlatnosci

nr_dok_korygowanego

Fa.DaneFaKorygowanej[].NrFaKorygowanej (z NrKSeFN = 1)

nr_dok_korygowanego_ksef

Fa.NrFaKorygowany

przyczyna_korekty

Fa.PrzyczynaKorekty

data_dok_korygowanego

Fa.DaneFaKorygowanej[].DataWystFaKorygowanej

opis

Fa.DodatkowyOpis[] (Klucz = UWAGI)

mpp

Fa.Adnotacje.P_18A

tp

Fa.TP

fp

Fa.FP

gtu_01–gtu_13

FaWiersz.GTU (pierwsze aktywne)

WSTO_EE, IED, TT_D, I_42, I_63, B_SPV, B_SPV_DOSTAWA, B_MPV_PROWIZJA

FaWiersz.Procedura (pierwsze aktywne)

Role Podmiotu3 (TRolaPodmiotu3)

Tabela ról używana w polach odbiorca_rola i platnik_rola. Można podać wartość numeryczną lub nazwę tekstową.

Wartość

Nazwa tekstowa

Opis

1

faktor

Faktor

2

odbiorca

Odbiorca (podmiot upoważniony do odbioru faktury)

3

podmiot_pierwotny

Podmiot pierwotny — podmiot przejęty lub przekształcony, który dokonywał dostawy/świadczył usługę

4

dodatkowy_nabywca

Dodatkowy nabywca

5

podmiot_pierwotny

Wystawca faktury — podmiot wystawiający fakturę w imieniu podatnika

6

dokonujacy_platnosci

Dokonujący płatności — podmiot regulujący zobowiązanie w miejsce nabywcy

7

jst_wystawca

Jednostka samorządu terytorialnego — wystawca

8

jst_odbiorca

Jednostka samorządu terytorialnego — odbiorca

9

gv_wystawca

Członek grupy VAT — wystawca

10

gv_odbiorca

Członek grupy VAT — odbiorca

11

pracownik

Pracownik

Uwaga: Wartości tekstowe są porównywane bez uwzględniania wielkości liter. Dla wartości 2 i 6 obsługiwane są skrócone aliasy: odbiorca i platnik — zachowane dla kompatybilności wstecznej.

Konfiguracja pluginów

Plugin Excel

{

"SourcePath": "C:\\KSef\\Excel",

"CheckDuplicates": true

}

Parametr

Typ

Wymagany

Domyślna

Opis

SourcePath

string (path)

Tak

—

Ścieżka do katalogu z plikami .xlsx. Podkatalogi Processed/Failed tworzone automatycznie.

CheckDuplicates

boolean

Nie

true

Sprawdzanie duplikatów faktur w bazie danych

•Obsługiwany format: .xlsx (Excel 2007+)

•Arkusz: automatycznie wykrywany arkusz REJESTR lub pierwszy arkusz

•Przetwarzanie: transakcyjne (cały plik albo nic)

•Archiwizacja: Processed/ (sukces) lub Failed/ (błąd) z timestampem

Plugin CSV
 

{

"SourceDirectory": "C:\\KSef\\CSV",

"Delimiter": ";",

"HasHeader": true,

"Encoding": "UTF-8"

}

Parametr

Typ

Wymagany

Domyślna

Opis

SourceDirectory

string (path)

Tak

—

Ścieżka do katalogu z plikami .csv. Podkatalogi Processed/Error tworzone automatycznie.

Delimiter

string

Nie

;

Separator pól CSV (1 znak)

HasHeader

boolean

Nie

true

Czy pierwszy wiersz zawiera nagłówki kolumn

Encoding

string

Nie

UTF-8

Kodowanie pliku: UTF-8, Windows-1250, ISO-8859-2

•Obsługiwany format: .csv

•Przetwarzanie: per faktura (poszczególne faktury mogą się udać/nie udać niezależnie)

•Archiwizacja: Processed/ (sukces) lub Error/ (błąd) z timestampem

Przykładowe pliki

Przykład Excel (.xlsx)

numer

rodzaj

data_wyst

nazwa

nip

kraj

adres

miejscowosc

kod_poczt

waluta

nazwa_pozycji

stawka_vat

jm

ilosc

wartosc

wartosc_vat

FV/001/2025

VAT

2025-01-15

Firma ABC Sp. z o.o.

1234567890

PL

ul. Główna 1

Warszawa

00-001

PLN

Usługa konsultingowa

23

szt

10

1000.00

230.00

FV/001/2025








Usługa programistyczna

23

godz

20

2000.00

460.00

FV/002/2025

VAT

2025-01-16

Inny Klient

9876543210

PL

ul. Boczna 5

Kraków

30-001

PLN

Licencja oprogramowania

23

szt

1

5000.00

1150.00

Wiersze z numerem FV/001/2025 tworzą jedną fakturę z 2 pozycjami. Dane kontrahenta (nazwa, NIP, adres) pobierane z pierwszego wiersza.

Przykład CSV (.csv)

numer;rodzaj;data_wyst;nazwa;nip;kraj;adres;miejscowosc;kod_poczt;waluta;nazwa_pozycji;stawka_vat;jm;ilosc;wartosc;wartosc_vat
FV/001/2025;VAT;2025-01-15;Firma ABC Sp. z o.o.;1234567890;PL;ul. Główna 1;Warszawa;00-001;PLN;Usługa konsultingowa;23;szt;10;1000.00;230.00
FV/001/2025;;;;;;;;;;;Usługa programistyczna;23;godz;20;2000.00;460.00
FV/002/2025;VAT;2025-01-16;Inny Klient;9876543210;PL;ul. Boczna 5;Kraków;30-001;PLN;Licencja oprogramowania;23;szt;1;5000.00;1150.00