[Fakturownia - Baza wiedzy](https://pomoc.fakturownia.pl.md) / [KSeF](https://pomoc.fakturownia.pl/integracja-z-ksef.md)

# [Pola przekazywane z programu Fakturownia do KSeF zgodnie ze schemą FA 3](https://pomoc.fakturownia.pl/pola-przekazywane-z-programu-fakturownia-do-ksef-zgodnie-ze-schema-fa-3.md)

Przewodnik po polach faktury wysyłanych do Krajowego Systemu e-Faktur. Dowiedz się, które pola z Fakturowni trafiają do KSeF, gdzie je znaleźć w programie i jakie obowiązują limity.

Artykuł opisuje aktualne mapowanie w schemacie FA 3 — obowiązującym w KSeF 2.0. Starszy schemat FA 2 nie jest już używany.

Zaktualizowano: 5 maj 2026

---

## Podmiot1 – Sprzedawca

Dane sprzedawcy pobierane są z ustawień konta [**Ustawienia → Dane firmy**](https://app.fakturownia.pl/goto?after_url=departments). NIP musi być 10-cyfrowy z poprawną sumą kontrolną. Adres jest obowiązkowy. Dane kontaktowe i adres korespondencyjny są opcjonalne.

| Pole KSeF | Zmienna w Fakturowni | Lokalizacja w programie | Opis |
| --- | --- | --- | --- |
| PrefiksPodatnika | \`seller_tax_no\` | Ustawienia → Dane firmy → NIP | Dodawane automatycznie gdy NIP sprzedawcy zaczyna się od liter „PL" |
| NIP | \`seller_tax_no\` | Ustawienia → Dane firmy → NIP | 10-cyfrowy NIP. Spacje, myślniki i kropki są usuwane automatycznie. Poprawność sprawdzana sumą kontrolną|
| Nazwa | \`seller_name\` | Ustawienia → Dane firmy → Nazwa firmy | Pełna nazwa firmy sprzedawcy |
| KodKraju | \`seller_country\` | Ustawienia → Dane firmy → Kraj | Dwuliterowy kod kraju (ISO 3166); gdy puste — domyślnie PL |
| AdresL1 | \`seller_street\` | Ustawienia → Dane firmy → Ulica | Ulica wraz z numerem budynku - wymagane |
| AdresL2 | \`seller_post_code\` + \`seller_city\` | Ustawienia → Dane firmy → Kod pocztowy + Miasto | Łączone spacją. Pomijane gdy oba puste |
| AdresKoresp | \`seller_postal_address.street\` | Ustawienia → Dane firmy → Adres korespondencyjny | Opcjonalny adres korespondencyjny sprzedawcy |
| Email | \`seller_email\` | Ustawienia → Dane firmy → Email | Opcjonalne - można podać trzy adresy e-mail oddzielone przecinkiem |
| Telefon | \`seller_phone\` | Ustawienia → Dane firmy → Telefon | Opcjonalne - spacje, myślniki i nawiasy usuwane są automatycznie, maksymalnie 16 znaków |

---

## Podmiot2 – Kupujący

Dane nabywcy pobierane są z karty kontrahenta wybranego na fakturze [**Faktury → Nowa faktura → sekcja Nabywca**](https://app.fakturownia.pl/goto?after_url=invoices/new?kind=vat)

⚠️ Pole \`buyer_company\` (czy nabywca jest firmą) decyduje o tym, czy faktura zostanie automatycznie wysłana do KSeF. Zawsze je uzupełniaj.

ℹ️ Dane kontaktowe nabywcy (email i telefon) są celowo nieprzekazywane do KSeF ze względu na ochronę danych osobowych (RODO).

| Pole KSeF | Zmienna w Fakturowni | Lokalizacja w programie | Opis |
| --- | --- | --- | --- |
| NIP | \`buyer_tax_no\` | Faktura → Nabywca → NIP | Polski 10-cyfrowy NIP. Wymagane gdy nabywca jest firmą |
| KodUE + NrVatUE | \`buyer_tax_no\` (rodzaj: nip_ue) | Faktura → Nabywca → NIP/VAT UE | [Numer VAT UE — 2 pierwsze znaki to kod kraju (np. DE)](https://pomoc.fakturownia.pl/132690-jak-zmienic-typ-numeru-identyfikacyjnego-u-sprzedawcy-lub-kupujacego); stosowane gdy buyer_tax_no_kind = nip_ue |
| IDWew | \`buyer_tax_no\` (rodzaj: nip_with_id) | Faktura → Nabywca → NIP | Identyfikator wewnętrzny — NIP plus numer oddziału; format: 10 cyfr-5 znaków (np. 5252445767-00001) |
| KodKraju + NrID | \`buyer_tax_no\` (rodzaj: other, z prefiksem kraju) | Faktura → Nabywca → NIP | Dla identyfikatorów zagranicznych zaczynających się od kodu kraju z listy KSeF (np. US123456) |
| NrID | \`buyer_tax_no\` (rodzaj: other, bez prefiksu) | Faktura → Nabywca → NIP | Inny identyfikator zagraniczny bez prefiksu kraju |
| BrakID | — | Generowane automatycznie | Ustawiane na 1 gdy NIP nabywcy jest pusty (\`buyer_tax_no_kind = empty\`) (typowo osoba prywatna) |
| Nazwa | \`buyer_name\` | Faktura → Nabywca → Nazwa | Jeśli puste — system łączy imię i nazwisko automatycznie |
| KodKraju + Adres | \`buyer_country\`, \`buyer_street\`, \`buyer_post_code\`, \`buyer_city\` | Faktura → Nabywca → Kraj / Adres | Opcjonalne; generowane gdy podano ulicę lub miasto; domyślny kod kraju PL |
| AdresKoresp | \`buyer_postal_address.street\` | Faktura → Nabywca → Adres korespondencyjny | Opcjonalny adres do korespondencji |
| JST | \`buyer_jst\` | Faktura → Nabywca → JST | [Jednostka samorządu terytorialnego, wartość ](https://pomoc.fakturownia.pl/201969093-oznaczenia-jst-i-grupa-vat-po-stronie-nabywcy)1 = tak, 2 = nie |
| GV | \`buyer_gv\` | Faktura → Nabywca → Grupa VAT | [Członek grupy VAT, wartość 1 = tak, 2 = nie ](https://pomoc.fakturownia.pl/201969093-oznaczenia-jst-i-grupa-vat-po-stronie-nabywcy)|

---

## Podmiot3 – Odbiorca / Wystawca

Podmiot3 jest opcjonalny i może wystąpić wielokrotnie. Uzupełniany w sekcji **Faktura → Dodatkowe podmioty.**

ℹ️ Dane kontaktowe Podmiotu3 (email i telefon) są celowo nieprzekazywane do KSeF ze względu na ochronę danych osobowych (RODO).

| Pole KSeF | Zmienna w Fakturowni | Lokalizacja w programie | Opis |
| --- | --- | --- | --- |
| DaneIdentyfikacyjne | \`tax_no\`, \`name\` | Faktura → Dodatkowe podmioty → NIP / Nazwa | Analogicznie jak Podmiot2 — NIP polski, NIP UE, IDWew, NrID lub BrakID; plus nazwa lub imię i nazwisko |
| Adres | \`street\`, \`post_code\`, \`city\`, \`country\` | Faktura → Dodatkowe podmioty → Adres | Opcjonalne - generowane gdy podano ulicę lub miasto |
| Rola | \`role\` | Faktura → Dodatkowe podmioty → Rola | Kod roli z tabeli poniżej; gdy rola pusta — domyślnie kod 2 (Odbiorca) lub 5 (Wystawca) |
| RolaInna + OpisRoli | \`role_description\` | Faktura → Dodatkowe podmioty → Opis roli | Wymagane gdy rola = „Rola inna", maksymalnie 25 znaków |
| Udzial | \`participation\` | Faktura → Dodatkowe podmioty → Udział | Procentowy udział (do 6 miejsc po przecinku), tylko dla roli „Dodatkowy nabywca" |

### Dostępne role — Odbiorcy:

| Rola | Kod |
| --- | --- |
| Odbiorca | 2 (domyślny gdy rola pusta) |
| Dodatkowy nabywca | 4 |
| Dokonujący płatności | 6 |
| JST – odbiorca | 8 |
| Członek GV – odbiorca | 10 |
| Pracownik | 11 |
| Rola inna | własny opis w \`role_description\` (max 25 znaków) |

### Dostępne role — Wystawcy:

| Rola | Kod |
| --- | --- |
| Faktor | 1 |
| Podmiot pierwotny | 3 |
| Wystawca faktury | 5 (domyślny gdy rola pusta) |
| JST – wystawca | 7 |
| Członek GV – wystawca | 9 |
| Rola inna | własny opis w \`role_description\` (max 25 znaków) |

---

## Dane faktury (Fa)

Główne pola faktury uzupełniane w widoku wystawiania faktury.

| Pole KSeF | Zmienna w Fakturowni | Lokalizacja w programie | Opis |
| --- | --- | --- | --- |
| KodWaluty | \`currency\` | Faktura → Waluta | Format ISO 4217, np. PLN, EUR, USD |
| P_1 | \`issue_date\` | Faktura → Data wystawienia | Data wystawienia faktury, format RRRR-MM-DD |
| P_1M | \`place\` | Faktura → Miejsce wystawienia | Opcjonalne - generowane gdy pole place jest wypełnione |
| P_2 | \`number\` | Faktura → Numer faktury | Numer faktury nadawany przez system |
| WZ | \`warehouse_documents[].number\` | Faktura → Dokumenty magazynowe | Numery dokumentów WZ powiązanych z fakturą; może być wiele; tylko gdy kind = wz |
| P_6 | \`sell_date\` | Faktura → Data sprzedaży | Data sprzedaży lub wykonania usługi; wysyłana gdy różna od daty wystawienia |
| P_15 | \`price_gross\` | Faktura → Suma brutto | Suma brutto całej faktury; obliczane automatycznie z pozycji faktury |
| RodzajFaktury | \`kind\` | Faktura → Rodzaj faktury | Typ faktury w KSeF: VAT, ZAL, ROZ, KOR, KOR_ZAL, KOR_ROZ; patrz sekcja Rodzaje faktur |
| FP | \`issued_to_receipt\` | Faktura → Faktura do paragonu | [Wartość 1 gdy faktura wystawiana do paragonu fiskalnego](https://pomoc.fakturownia.pl/28323387-faktura-do-paragonu) |
| TP | \`procedure_designations\` | Faktura → Oznaczenia procedur | [Wartość 1 przekazywana, gdy zaznaczono procedurę „TP" (powiązania z nabywcą) ](https://pomoc.fakturownia.pl/10572023-oznaczenia-dotyczace-procedur)|
| WarunkiTransakcji → NrZamowienia | \`oid\` | Faktura → Numer zamówienia | Numer zamówienia z systemu klienta; wysyłany tylko gdy show_oid = true |
| Rozliczenie | \`settlement_positions\` | Faktura → Rozliczenie | Lista obciążeń i odliczeń (np. odsetki, kompensata); generowane gdy lista jest niepusta |

## Podsumowanie VAT (P_13 / P_14)

Kwoty obliczane automatycznie z pozycji faktury i grupowane według stawki VAT. Klient nie uzupełnia tych pól ręcznie. Dla faktur walutowych dołączane są równolegle kwoty VAT przeliczone na PLN (elementy z sufiksem W).

| Pole KSeF | Stawka / Procedura | Opis |
| --- | --- | --- |
| P_13_1 / P_14_1 | 22%, 23% | Wartość netto i kwota VAT według stawki podstawowej |
| P_14_1W | 22%, 23% | Kwota VAT przeliczona na PLN — tylko dla faktur walutowych |
| P_13_2 / P_14_2 | 7%, 8% | Pierwsza stawka obniżona |
| P_14_2W | 7%, 8% | Kwota VAT w PLN dla faktur walutowych |
| P_13_3 / P_14_3 | 5% | Druga stawka obniżona |
| P_14_3W | 5% | Kwota VAT w PLN dla faktur walutowych |
| P_13_5 / P_14_5 | OSS/MOSS | Sprzedaż w procedurze OSS (usługi transgraniczne B2C) |
| P_13_6_1 | 0% krajowa | Stawka 0% dla sprzedaży krajowej |
| P_13_6_2 | 0% WDT | Stawka 0% dla wewnątrzwspólnotowej dostawy towarów |
| P_13_6_3 | 0% eksport | Stawka 0% dla eksportu produktów poza UE |
| P_13_7 | zw | Sprzedaż zwolniona z VAT |
| P_13_8 | np (poza UE) | Niepodlegające opodatkowaniu — usługi zagraniczne poza UE |
| P_13_9 | np (UE) | Niepodlegające opodatkowaniu — usługi na terenie UE |
| P_13_10 | odwrotne obciążenie | Odwrotne obciążenie (nabywca krajowy) |
| P_13_11 | marża | Procedura marży — przekazywana wartość brutto |

---

## Adnotacje

Pola dotyczące szczególnych procedur VAT — uzupełniane w sekcji **Faktura → Adnotacje i procedury**.

| Pole KSeF | Zmienna w Fakturowni | Lokalizacja w programie | Opis |
| --- | --- | --- | --- |
| P_16 | \`cash_accounting\` | Faktura → Metoda kasowa | Metoda kasowa: wartość 1 = tak, 2 = nie. Dotyczy faktur \`vat_mp\` |
| P_18 | \`reverse_charge\` | Faktura → Odwrotne obciążenie | Odwrotne obciążenie, wartość  1 = tak, 2 = nie |
| P_18A | \`split_payment\` | Faktura → Podzielona płatność (MPP) | Mechanizm podzielonej płatności, wartość  1 = tak, 2 = nie |
| P_19 / P_19A / P_19B / P_19C | \`exempt_tax_kind\` | Faktura → Zwolnienie z VAT → Przyczyna zwolnienia | Wymagane gdy pozycja ma stawkę „zw", maksymalnie 256 znaków |
| P_PMarzy |	\`kind = vat_margin\` |	Faktura → Rodzaj faktury | Faktura w procedurze marży — wybierz rodzaj faktury VAT marża |
| P_PMarzy_2 | \`procedure_vat_margin\` | Faktura → Procedura marży → Biura podróży | Procedura marży dla biur podróży |
| P_PMarzy_3_1 | \`procedure_vat_margin\` | Faktura → Procedura marży → Towary używane | Procedura marży dla towarów używanych |
| P_PMarzy_3_2 | \`procedure_vat_margin\` | Faktura → Procedura marży → Dzieła sztuki | Procedura marży dla dzieł sztuki |
| P_PMarzy_3_3 | \`procedure_vat_margin\` | Faktura → Procedura marży → Antyki | Procedura marży dla przedmiotów kolekcjonerskich i antyków |

## Dozwolone wartości pola \`exempt_tax_kind\`:

| Wartość |
| --- |
| Zwolnienie ze względu na rodzaj prowadzonej działalności (art. 43 ust 1 ustawy o VAT) |
| Zwolnienie ze względu na nieprzekroczenie limitu obrotu (art. 113 ust 1 i 9 ustawy o VAT) |
| Zwolnienie na mocy rozporządzenia MF (art. 82 ust 3 ustawy o VAT) |
| Zwolnienie, o którym mowa w art. 132 ust 1 lub art. 135 ust 1 Dyrektywy 2006/112/WE |
| lub własny tekst opisujący podstawę zwolnienia |

## Pole \`np_tax_kind\` — wymagane gdy pozycje mają stawkę „np":

| Wartość | Opis |
| --- | --- |
| \`export_service\` | Dostawa towarów oraz świadczenie usług poza terytorium kraju |
| \`export_service_eu\` | Świadczenie usług, o których mowa w art. 100 ust. 1 pkt 4 ustawy |

---

## Pozycje faktury (FaWiersz)

Każda pozycja faktury mapowana jest na osobny element FaWiersz. Pomijane są pozycje typu \`text_separator\` i \`page_break\`. [Przy korektach generowane są dwa wiersze na pozycję: przed i po korekcie.](https://pomoc.fakturownia.pl/3540508-korekta-danych-na-fakturze)

ℹ️ Pozycje FaWiersz są pomijane dla faktur zaliczkowych (ZAL) i ich korekt (KOR_ZAL) — tam pozycje znajdują się w sekcji Zamówienie.

| Pole KSeF | Zmienna w Fakturowni | Lokalizacja w programie | Opis |
| --- | --- | --- | --- |
| NrWierszaFa | — | Generowane automatycznie | Numer kolejny od 1 |
| P_7 | \`name\` | Pozycja → Nazwa towaru / usługi | Maksymalnie 256 znaków |
| Indeks | \`code\` | Pozycja → Kod produktu | Maksymalnie 50 znaków |
| GTIN | \`additional_info\` (typ: GTIN) | Pozycja → Dodatkowy opis | Maksymalnie 20 znaków |
| PKWiU | \`additional_info\` (typ: PKWiU) | Pozycja → Dodatkowy opis | Maksymalnie 50 znaków |
| CN | \`additional_info\` (typ: CN) | Pozycja → Dodatkowy opis | Maksymalnie 50 znaków |
| PKOB | \`additional_info\` (typ: PKOB) | Pozycja → Dodatkowy opis | Maksymalnie 50 znaków |
| P_8A | \`quantity_unit\` | Pozycja → Jednostka miary | Domyślnie „brak" gdy pole puste |
| P_8B | \`quantity\` | Pozycja → Ilość | Do 6 miejsc po przecinku |
| P_9A | \`price_net\` | Pozycja → Cena jednostkowa netto | Nie dotyczy faktur do paragonu i VAT marża |
| P_9B | \`price_gross\` | Pozycja → Cena jednostkowa brutto | Stosowane dla faktur do paragonu i VAT marża |
| P_10 | \`price_net - price_net_with_discount\` | Pozycja → Rabat | Przekazywane tylko gdy \`show_discount=true\` i wartość rabatu > 0 |
| P_11 | \`total_price_net_with_discount\` | Pozycja → Wartość netto | Wartość netto po uwzględnieniu rabatu |
| P_11A | \`total_price_gross_with_discount\` | Pozycja → Wartość brutto | Stosowane dla faktur do paragonu i VAT marża |
| P_12 | \`tax\` | Pozycja → Stawka VAT | Akceptowane wartości: 23 / 8 / 5 / 0 / zw / np / oo i inne |
| P_12_XII	| \`tax\` | Pozycja → Stawka VAT	| Stawka procentowa dla procedury OSS/MOSS |
| GTU | \`gtu_codes[0]\` | Pozycja → Kod GTU | Przekazywany pierwszy kod GTU z listy przypisanej do pozycji |

---

## Płatność i rachunki bankowe

Dane płatności uzupełniane w sekcji Faktura → Płatność. Rachunki bankowe pobierane z[** Ustawienia → Rachunki bankowe**](https://pomoc.fakturownia.pl/54378800-dodawanie-numeru-rachunku-bankowego).

| Pole KSeF | Zmienna w Fakturowni | Lokalizacja w programie | Opis |
| --- | --- | --- | --- |
| Zaplacono | \`status = paid\` | Faktura → Status płatności | Wartość 1 gdy faktura opłacona w całości |
| DataZaplaty | \`paid_date\` | Faktura → Data zapłaty | Przekazywane gdy \`status = paid\` |
| ZnacznikZaplatyCzesciowej | \`status = partial\` | Faktura → Płatność częściowa | Wartość 1 gdy faktura częściowo opłacona |
| ZaplataCzesciowa → KwotaZaplatyCzesciowej |	\`paid\` |	Faktura → Kwota wpłacona	| Kwota wpłacona dotychczas przy płatności częściowej |
| ZaplataCzesciowa → DataZaplatyCzesciowej |	\`paid_date\` |	Faktura → Data zapłaty częściowej	| Data wpłaty częściowej; opcjonalne |
| TerminPlatnosci | \`payment_to\` | Faktura → Termin płatności | Przekazywane gdy \`payment_to_kind ≠ off\` |
| FormaPlatnosci | \`payment_type\` | Faktura → Forma płatności | gotówka=1, karta=2, czek=4, przelew=6 |
| PlatnoscInna | \`payment_type\` | Faktura → Forma płatności | Dla pozostałych form: PayPal, PayU, Barter, Weksel, Kompensata i inne |
| NrRB | \`bank_accounts[].formatted_number\` | Ustawienia → Rachunki bankowe → Numer rachunku | Maksymalnie 34 znaki, format IBAN |
| SWIFT | \`bank_accounts[].bank_swift\` | Ustawienia → Rachunki bankowe → SWIFT | Opcjonalne |
| NazwaBanku | \`bank_accounts[].bank_name\` | Ustawienia → Rachunki bankowe → Nazwa banku | Maksymalnie 256 znaków |
| Skonto | \`skonto_discount_date\` / \`skonto_discount_value\` | Faktura → Skonto | Przekazywane gdy \`skonto_active = true\` |

---

## Faktury korygujące

⚠️ Ważne ograniczenia: Korekta nie może zmieniać NIP-u sprzedawcy ani nabywcy. W KSeF nie można usunąć faktury — jedynym sposobem anulowania jest wystawienie korekty do zera.

| Pole KSeF | Zmienna w Fakturowni | Lokalizacja w programie | Opis |
| --- | --- | --- | --- |
| PrzyczynaKorekty | \`correction_reason\` | Korekta → Przyczyna korekty | Opcjonalne, maksymalnie 256 znaków |
| DataWystFaKorygowanej | \`invoice.issue_date\` | Pobierane automatycznie z faktury korygowanej | Data wystawienia faktury oryginalnej |
| NrFaKorygowanej | \`invoice.number\` | Pobierane automatycznie z faktury korygowanej | Numer faktury oryginalnej |
| NrKSeF / NrKSeFFaKorygowanej | \`invoice.gov_id\` | Pobierane automatycznie z faktury korygowanej | Numer KSeF faktury korygowanej, przekazywany gdy \`gov_id\` jest obecny |
| NrKSeFN | — | Ustawiane automatycznie | Ustawiane na 1 gdy faktura korygowana nie ma numeru KSeF |
| Podmiot1K |	\`invoice.seller_\*\`	| Pobierane automatycznie z faktury korygowanej	| Dane sprzedawcy z faktury pierwotnej; wysyłane gdy zmieniły się dane sprzedawcy |
| Podmiot2K |	\`invoice.buyer_\*\`	Pobierane automatycznie z faktury korygowanej |	Dane nabywcy z faktury pierwotnej; wysyłane gdy zmieniły się dane nabywcy |
| P_15ZK |	\`invoice.paid\` / \`price_gross - paid\`	| Pobierane automatycznie |	Tylko dla KOR_ZAL i KOR_ROZ; dla KOR_ZAL — kwota zapłaconej zaliczki; dla KOR_ROZ — kwota pozostała po zaliczkach |
| FaWiersz — wartość PRZED korektą | \`positions[].correction_before\` | Pozycja korekty → wartość przed korektą | Stan pozycji przed korektą (StanPrzed=1) |
| FaWiersz — wartość PO korekcie | \`positions[].correction_after\` | Pozycja korekty → wartość po korekcie | Stan pozycji po korekcie |

Mapowanie rodzaju korekty na RodzajFaktury w KSeF:
 
| Sytuacja |	RodzajFaktury w KSeF |
| -- | -- |
| Korekta faktury zaliczkowej (oryginał: advance)	| KOR_ZAL |
| Korekta faktury rozliczeniowej (oryginał: final) |	KOR_ROZ |
| Korekta zwykłej faktury (inny rodzaj oryginału)	| KOR |


## Faktury zaliczkowe i rozliczeniowe

Dotyczy faktur typu ZAL (zaliczkowa) i ROZ (rozliczeniowa/końcowa).

### Faktura rozliczeniowa (ROZ):

| Pole KSeF | Zmienna w Fakturowni | Lokalizacja w programie | Opis |
| --- | --- | --- | --- |
| NrKSeFFaZaliczkowej | \`my_advances_full[].gov_id\` | Pobierane z powiązanej faktury zaliczkowej | Numer KSeF powiązanej zaliczki, gdy \`gov_id\` zaliczki jest obecny |
| NrFaZaliczkowej | \`my_advances_full[].number\` | Pobierane z powiązanej faktury zaliczkowej | Numer faktury zaliczkowej, gdy \`gov_id\` zaliczki nie istnieje |

### Zamówienie powiązane (ZAL):

| Pole KSeF | Zmienna w Fakturowni | Lokalizacja w programie | Opis |
| --- | --- | --- | --- |
| WartoscZamowienia | \`estimate.price_gross\` | Powiązane zamówienie → Wartość brutto | Wartość brutto całego zamówienia |
| P_7Z | \`estimate.positions[].name\` | Zamówienie → Pozycja → Nazwa | Nazwa pozycji z zamówienia |
| IndeksZ |	\`estimate.positions[].code\` |	Zamówienie → Pozycja → Kod produktu |	Maksymalnie 50 znaków |
| GTINZ / PKWiUZ / CNZ / PKOBZ |	\`additional_info\` |	Zamówienie → Pozycja → Dodatkowy opis	| Dodatkowe oznaczenie produktu (GTIN, PKWiU, CN lub PKOB) |
| P_8AZ / P_8BZ | \`quantity_unit\` / \`quantity\` | Zamówienie → Pozycja → Jednostka / Ilość | Domyślnie „szt." gdy jednostka pusta |
| P_9AZ | \`price_net\` | Zamówienie → Pozycja → Cena netto | Cena jednostkowa netto pozycji zamówienia |
| P_11NettoZ / P_11VatZ | \`total_price_net\` / \`total_price_tax\` | Zamówienie → Pozycja → Wartość netto / VAT | Wartość netto i kwota VAT pozycji zamówienia |
| P_12Z	tax	| Zamówienie → Pozycja → Stawka VAT |	Stawka VAT (np. 23, zw, np) |
| P_12Z_XII |	\`tax\`	| Zamówienie → Pozycja → Stawka VAT	 | Stawka procentowa dla procedury OSS/MOSS |
| GTUZ |	\`gtu_codes[0]\`	| Zamówienie → Pozycja → Kod GTU |	Przekazywany pierwszy kod GTU z listy |


## Stopka i DodatkowyOpis

Stopka generowana tylko gdy wypełnione jest pole BDO lub opis stopki.

| Pole KSeF | Zmienna w Fakturowni | Lokalizacja w programie | Opis |
| --- | --- | --- | --- |
| StopkaFaktury | \`description_footer\` | Faktura → Stopka / Uwagi końcowe | Białe znaki normalizowane, maksymalnie 3500 znaków |
| BDO | \`seller_bdo_no\` | Ustawienia → Dane firmy → Numer BDO | [Numer rejestrowy BDO sprzedawcy](https://pomoc.fakturownia.pl/58636650-dodawanie-na-stale-numeru-bdo-na-fakturze) |
| Faktura do proformy | \`proforma_number\` | Faktura → Numer proformy | Przekazywane gdy pole \`proforma_number\` jest wypełnione |
| Faktura do paragonu | \`receipt_number\` | Faktura → Numer paragonu | Przekazywane gdy pole \`receipt_number\` jest wypełnione |
| Uwagi | \`descriptions[].content\` | Faktura → Uwagi / Opis | [Maksymalnie 256 znaków przy wysyłce do KSeF ](https://pomoc.fakturownia.pl/202881655-dodatkowe-uwagi-na-fakturze-ksef-pola-klucz-i-wartosc)|
| Opis pozycji | \`positions[].description\` | Pozycja → Opis pozycji | Maksymalnie 256 znaków, przekazywany osobno dla każdego wiersza |

---

## Rodzaje faktur

Rodzaj faktury w KSeF ustalany jest automatycznie na podstawie pola Rodzaj w Fakturowni.

| Rodzaj w Fakturowni | Rodzaj w KSeF | Opis |
| --- | --- | --- |
| \`vat\`, \`vat_mp\`, \`vat_margin\`, \`wdt\`, \`export_products\` | VAT | Faktura VAT (w tym kasowa, marża, WDT, eksport) |
| \`advance\` | ZAL | Faktura zaliczkowa |
| \`final\` | ROZ | Faktura rozliczeniowa (końcowa) |
| \`correction\` z VAT | KOR | Korekta faktury VAT |
| \`correction\` z \`advance\` | KOR_ZAL | Korekta faktury zaliczkowej |
| \`correction\` z \`final\` | KOR_ROZ | Korekta faktury rozliczeniowej |

⚠️ Nieobsługiwane typy: \`proforma\`, \`estimate\` i \`receipt\` nie są wysyłane do KSeF — przy próbie wysyłki otrzymają status \`not_applicable\`.

---

## Pola NIE przesyłane do KSeF

Poniższe pola istnieją w Fakturowni, ale są pomijane podczas wysyłki:

|** Pole w Fakturowni **|** Zmienna **|** Powód pominięcia **| 
| --- | --- | --- | 
| Notatki prywatne | \`private_notes\` | Brak odpowiednika w schemacie KSeF |
| Uwagi nabywcy | \`buyer_note\` | Brak odpowiednika w schemacie KSeF |
| Uwagi sprzedawcy | \`seller_note\` | Brak odpowiednika w schemacie KSeF | 
| Notatka wewnętrzna | \`internal_note\` | Brak odpowiednika w schemacie KSeF | 
| [Numer zamówienia](https://pomoc.fakturownia.pl/909095-numer-zamowienia-na-fakturze) | \`oid\` (bez \`show_oid\`) | Wymaga flagi \`show_oid=true\` | 
| Dział | \`department_name\` | Nie mapowane | 
| Kategoria | \`category\` | Nie mapowane | 
| Osoba kontaktowa sprzedawcy | \`seller_person\` | Nie mapowane | 
| Osoba kontaktowa nabywcy | \`buyer_person\` | Nie mapowane | 
| Język faktury | \`lang\` | KSeF nie obsługuje wielojęzyczności |
| Email i telefon nabywcy	| \`buyer_email\`, \`buyer_phone\`	| Celowo pomijane — ochrona danych osobowych (RODO) |
| Email i telefon Podmiotu3	| \`email\`, \`phone\`	| Celowo pomijane — ochrona danych osobowych (RODO) |
| Kurs waluty w pozycjach |	\`KursWaluty\` |	Mapowanie zawieszone |
| Drugi i trzeci kod GTU	| \`gtu_codes[1]\`, \`gtu_codes[2]\` |	Wysyłany tylko pierwszy kod z listy gtu_codes |
| Linia tekstowa | position.kind = \`text_separator\` | Brak odpowiednika w schemacie KSeF |
| Dodatkowy opis odbiorcy |  \`recipients.note\` | Brak odpowiednika w schemacie KSeF |
| Dodatkowy opis wystawcy | \`issuers.note\` | Brak odpowiednika w schemacie KSeF |

---

## Pola statusu KSeF (gov_\\\*)

Po wysyłce faktury do KSeF system uzupełnia poniższe pola widoczne w widoku faktury.

| Pole | Lokalizacja w programie | Opis |
| --- | --- | --- |
| \`gov_status\` | Faktura → Status KSeF | Aktualny status wysyłki — patrz tabela wartości poniżej |
| \`gov_id\` | Faktura → Numer KSeF | Unikalny numer KSeF w formacie NIP-DATA-ID, np. \`5252445767-20260201-ABC123\` |
| \`gov_send_date\` | Faktura → Data wysyłki do KSeF | Data i czas wysyłki faktury do KSeF |
| \`gov_sell_date\` | Faktura → Data sprzedaży w KSeF | Data sprzedaży zarejestrowana w KSeF |
| \`gov_error_messages\` | Faktura → Błędy KSeF | Lista błędów walidacji lub wysyłki; \`null\` gdy brak błędów |
| \`gov_verification_link\` | — | Link do weryfikacji faktury w portalu KSeF, używany do generowania kodu QR na wydruku |
| \`gov_corrected_invoice_number\` | Faktura korygująca → Numer KSeF oryginału | Numer KSeF korygowanej faktury, tylko dla korekt |

### Możliwe wartości \`gov_status\`:

| Wartość | Opis |
| --- | --- |
| \`ok\` | Wysłana pomyślnie do KSeF |
| \`processing\` | W trakcie przetwarzania / w kolejce |
| \`send_error\` | Błąd wysyłki — szczegóły w \`gov_error_messages\` |
| \`server_error\` | Błąd serwera KSeF, spróbuj ponownie później |
| \`not_applicable\` | Faktura nie kwalifikuje się do KSeF (np. proforma) |
| \`not_connected\` | KSeF nie jest połączony z kontem |
| \`null\` | Faktura nie była jeszcze wysyłana do KSeF |
| \`demo_ok\` | Wysłana pomyślnie (tryb demo) |
| \`demo_processing\` | W trakcie przetwarzania (tryb demo) |
| \`demo_send_error\` | Błąd wysyłki (tryb demo) |

---

## Rodzaj identyfikatora podatkowego (tax_no_kind)

Pole \`buyer_tax_no_kind\` / \`seller_tax_no_kind\` określa typ numeru identyfikacyjnego.

| Wartość | Opis | Przykład |
| --- | --- | --- |
| \*(puste, domyślne)\* | Polski NIP, 10 cyfr | \`5252445767\` |
| \`nip_ue\` | Numer VAT UE dla firm z Unii Europejskiej | \`DE123456789\` |
| \`other\` | Inny numer identyfikacyjny dla firm spoza UE | \`CHE123456789\` |
| \`empty\` | Brak numeru identyfikacyjnego; pole \`tax_no\` musi być puste | — |
| \`nip_with_id\` | NIP z wewnętrznym ID oddziału | \`5252445767-00001\` |

ℹ️ Gdy \`buyer_tax_no_kind = empty\`, pole \`buyer_tax_no\` nie jest wymagane nawet dla firm. Pozwala to wystawić fakturę dla podmiotu zagranicznego bez europejskiego numeru VAT.

---

## Ograniczenia długości pól

Przekroczenie poniższych limitów spowoduje błąd walidacji i zablokuje wysyłkę do KSeF.

| Pole | Zmienna | Limit |
| --- | --- | --- |
| Nazwa pozycji | \`name\` | 256 znaków |
| Opis pozycji | \`positions[].description\` | 256 znaków |
| Uwagi | \`descriptions[].content\` | 256 znaków |
| Stopka faktury | \`description_footer\` | 3500 znaków |
| Przyczyna korekty | \`correction_reason\` | 256 znaków |
| Podstawa zwolnienia | \`exempt_tax_kind\` | 256 znaków |
| Opis roli podmiotu | \`role_description\` | 25 znaków |
| Telefon | \`buyer_phone\`, \`seller_phone\` | 16 znaków |
| Email | \`buyer_email\`, \`seller_email\` | 255 znaków |
| Kod produktu / Indeks | \`code\` | 50 znaków |
| GTIN | \`additional_info\` (typ: GTIN) | 20 znaków |
| PKWiU / CN / PKOB | \`additional_info\` | 50 znaków |
| Numer rachunku bankowego | \`NrRB\` | 34 znaki (IBAN) |
| Nazwa banku | \`NazwaBanku\` | 256 znaków |

---

## Ważne zasady operacyjne

**Blokada edycji po wysyłce**

Po nadaniu numeru KSeF (\`gov_id\`) faktura jest zablokowana do edycji i usunięcia. Wszelkie zmiany wymagają wystawienia faktury korygującej.

**Wysyłka e-maila do klienta**

Gdy KSeF jest aktywny, wysyłka faktury e-mailem do nabywcy będącego firmą jest możliwa dopiero po nadaniu numeru KSeF (\`gov_status = ok\`). Próba wysyłki wcześniej zwróci błąd.

## Tryb OFFLINE24

Jeśli data wystawienia faktury (\`issue_date\`) jest wcześniejsza niż dzisiejsza data, system automatycznie traktuje fakturę jako wystawioną w trybie OFFLINE24. Na dokumencie pojawią się dwa kody QR. Faktura zostanie dosłana do KSeF z odpowiednim oznaczeniem.

⚠️ [Tryb OFFLINE24 nie jest przeznaczony do regularnego fakturowania z datą wsteczną.](https://pomoc.fakturownia.pl/200860128-tryby-awaryjne-offline-i-offline24)

## Automatyczna wysyłka — tryby

Konfiguracja w **Ustawienia → KSeF → Automatyczna wysyłka**:

| Tryb | Opis |
| --- | --- |
| Wyłączona | Wysyłka wyłącznie ręczna |
| Tylko polskie firmy | Faktury z \`buyer_company=true\` i \`buyer_country=PL\` |
| Wszystkie firmy | Faktury z \`buyer_company=true\` niezależnie od kraju |
| Wszystkie dokumenty | Faktury dla firm i osób prywatnych |

## Najczęstsze błędy walidacji

| Komunikat błędu | Przyczyna | Rozwiązanie |
| --- | --- | --- |
| „NIP nabywcy — nie może być puste" | Brak \`buyer_tax_no\` dla nabywcy będącego firmą | Dodaj NIP lub ustaw \`buyer_tax_no_kind = empty\` |
| „Telefon — pole za długie" | \`buyer_phone\` lub \`seller_phone\` powyżej 16 znaków | Skróć numer telefonu do 16 znaków |
| „Podstawa zwolnienia — nie może być puste" | Pozycja ma stawkę „zw" bez wypełnionego \`exempt_tax_kind\` | Uzupełnij pole \`exempt_tax_kind\` odpowiednią podstawą prawną |
| „Nazwa pozycji — pole za długie" | \`positions[].name\` powyżej 256 znaków | Skróć nazwę pozycji do 256 znaków |
| „Nie można korygować NIP" | Próba zmiany NIP sprzedawcy lub nabywcy w korekcie | NIP nie może być zmieniony korektą — wymagana nowa faktura |

---

Zaktualizowano: 5 maj 2026