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. 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 |
| `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
⚠️ 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); 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ść 1 = tak, 2 = nie |
| GV | `buyer_gv` | Faktura → Nabywca → Grupa VAT | Członek grupy VAT, wartość 1 = tak, 2 = nie |
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 |
| TP | `procedure_designations` | Faktura → Oznaczenia procedur | Wartość 1 przekazywana, gdy zaznaczono procedurę „TP” (powiązania z nabywcą) |
| 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.
ℹ️ 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.
| 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 |
| 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 |
| 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 | `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 |
| `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ą.
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