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.
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 lub średnikiem | |
| 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.
UWAGA! Pole buyer_company (czy nabywca jest firmą) decyduje o tym, czy faktura zostanie automatycznie wysłana do KSeF. Zawsze je uzupełniaj.
WSKAZÓWKA! 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 cyfr; pierwsze 10 cyfr jest sprawdzane sumą kontrolną NIP (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.
WSKAZÓWKA! 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, VAT 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 |
| KursWaluty | exchange_currency_rate | Faktura → Kurs waluty | Kurs waluty obcej zastosowany na fakturze. Przekazywany tylko dla faktur w walucie innej niż PLN. Do 6 miejsc po przecinku. |
| 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 |
| P_6 | sell_date | Faktura → Data sprzedaży | Data sprzedaży lub wykonania usługi; wysyłana zawsze, gdy data sprzedaży jest uzupełniona |
| 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ą) |
| Rozliczenie | settlement_positions | Faktura → Rozliczenie | Lista obciążeń i odliczeń (np. odsetki, kompensata); generowane, gdy lista jest niepusta |
Warunki transakcji
Sekcja opcjonalna, uzupełniana w formularzu faktury w sekcji Warunki transakcji (widoczna po rozwinięciu „Zobacz więcej opcji” lub — jeśli została włączona domyślnie w ustawieniach konta — od razu na formularzu).
Numer zamówienia z pola oid (dawne pole „Numer zamówienia”, przekazywane tylko przy show_oid = true) działa nadal ze względu na zgodność wsteczną.
| Pole KSeF | Zmienna w Fakturowni | Lokalizacja w programie | Opis |
|---|---|---|---|
| WarunkiDostawy | delivery_terms | Faktura → Warunki transakcji → Warunki dostawy | Kod Incoterms (EXW, FCA, CPT, CIP, DAP, DPU, DDP) lub własny opis po wybraniu „Inne…”. Tekst, maksymalnie 256 znaków. |
| KursUmowny | agreed_exchange_rate | Faktura → Warunki transakcji → Kurs i waluta umowna | Kurs uzgodniony przez strony transakcji (do 6 miejsc po przecinku). Wysyłany tylko razem z walutą umowną. |
| WalutaUmowna | agreed_currency | Faktura → Warunki transakcji → Kurs i waluta umowna | Waluta uzgodniona (ISO 4217); nie może być PLN. Wysyłana tylko razem z kursem umownym. |
| PodmiotPosredniczacy | intermediary_entity | Faktura → Warunki transakcji → Podmiot pośredniczący | Udział podmiotu pośredniczącego w transakcji trójstronnej (art. 22 ust. 2d ustawy o VAT). Wysyłane, gdy zaznaczone. |
| Umowy (NrUmowy, DataUmowy) | transaction_contracts (contract_number, contract_date) | Faktura → Warunki transakcji → Umowy | Lista umów; każdy wiersz wymaga numeru lub daty. Do 100 umów, numer umowy maksymalnie 256 znaków. |
| Zamówienia (NrZamowienia, DataZamowienia) | transaction_orders (order_number, order_date) | Faktura → Warunki transakcji → Zamówienia | Lista zamówień; każdy wiersz wymaga numeru lub daty. Do 100 zamówień, numer maksymalnie 256 znaków. Zastępuje dawne pojedyncze pole „Numer zamówienia” (oid). |
| NrPartiiTowaru | transaction_batches (batch_number) | Faktura → Warunki transakcji → Numery partii towaru | Lista numerów partii towaru; każdy jako osobny wpis. Do 1000 partii, numer maksymalnie 256 znaków. |
WAŻNE! Cała sekcja jest wysyłana do KSeF tylko wtedy, gdy jest w niej jakakolwiek treść. Odznaczenie głównego pola Warunki transakcji i zapisanie dokumentu powoduje usunięcie wszystkich powyższych pól i list — również przez API (PUT z "transaction_terms_enabled": false).
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
- 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.
WSKAZÓWKA! 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, VAT marża ani faktur liczonych od kwoty brutto |
| P_9B | price_gross | Pozycja → Cena jednostkowa brutto | Stosowane dla faktur do paragonu, VAT marża oraz faktur liczonych od kwoty brutto |
| 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 |
| OpisRachunku | bank_accounts[].account_description | Ustawienia → Rachunki bankowe → Opis rachunku | Pole opcjonalne. Przekazywane obok numeru IBAN. Można tu wpisać np. walutę konta (PLN, EUR) lub adres banku. |
| Skonto | skonto_discount_date / skonto_discount_value | Faktura → Skonto | Przekazywane, gdy skonto_active = true |
Faktury korygujące
UWAGA! 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 → Dodatkowe uwagi na dole strony | 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 |
UWAGA! 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) |
| Drugi i trzeci kod GTU | gtu_codes[1], gtu_codes[2] | Wysyłany tylko pierwszy kod z listy gtu_codes |
| 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 |
WSKAZÓWKA! 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.
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 |