[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: 25 marzec 2026

---

## Podmiot1 – Sprzedawca

Dane sprzedawcy pobierane są z ustawień konta [**Ustawienia → Dane firmy**](https://app.fakturownia.pl/goto?after_url=departments). Wszystkie pola tej sekcji są wymagane przez KSeF.

| Pole KSeF | Zmienna w Fakturowni | Lokalizacja w programie | Opis |
| --- | --- | --- | --- |
| PrefiksPodatnika | \`seller_tax_no\` | Ustawienia → Dane firmy → NIP | Dodawane automatycznie gdy NIP zaczyna się od „PL" |
| NIP | \`seller_tax_no\` | Ustawienia → Dane firmy → NIP | Znaki niebędące cyframi są usuwane automatycznie |
| Nazwa | \`seller_name\` | Ustawienia → Dane firmy → Nazwa firmy | Pełna nazwa firmy sprzedawcy |
| KodKraju | \`seller_country\` | Ustawienia → Dane firmy → Kraj | Kod kraju ISO 3166, domyślnie PL |
| AdresL1 | \`seller_street\` | Ustawienia → Dane firmy → Ulica | Ulica i numer |
| AdresL2 | \`seller_post_code\` + \`seller_city\` | Ustawienia → Dane firmy → Kod pocztowy + Miasto | Łączone spacją |
| AdresKoresp → AdresL1 | \`seller_postal_address.street\` | Ustawienia → Dane firmy → Adres korespondencyjny | Opcjonalny adres korespondencyjny sprzedawcy |
| Email | \`seller_email\` | Ustawienia → Dane firmy → Email | Opcjonalne |
| Telefon | \`seller_phone\` | Ustawienia → Dane firmy → Telefon | Opcjonalne, 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.

| Pole KSeF | Zmienna w Fakturowni | Lokalizacja w programie | Opis |
| --- | --- | --- | --- |
| NIP | \`buyer_tax_no\` | Faktura → Nabywca → NIP | Format 10 cyfr (NIP polski). Wymagane gdy nabywca jest firmą |
| KodUE + NrVatUE | \`buyer_tax_no\` | Faktura → Nabywca → NIP/VAT UE | [Stosowane gdy \`buyer_tax_no_kind = nip_ue\` (firma z UE](https://pomoc.fakturownia.pl/132690-jak-zmienic-typ-numeru-identyfikacyjnego-u-sprzedawcy-lub-kupujacego)) |
| BrakID | — | Generowane automatycznie | Ustawiane na 1 gdy NIP nabywcy jest pusty (\`buyer_tax_no_kind = empty\`) |
| Nazwa | \`buyer_name\` | Faktura → Nabywca → Nazwa | Jeśli puste — system łączy imię i nazwisko automatycznie |
| KodKraju | \`buyer_country\` | Faktura → Nabywca → Kraj | Kod kraju ISO 3166, domyślnie PL |
| AdresL1 | \`buyer_street\` | Faktura → Nabywca → Ulica | Opcjonalne |
| AdresL2 | \`buyer_post_code\` + \`buyer_city\` | Faktura → Nabywca → Kod pocztowy + Miasto | Łączone spacją |
| Email | \`buyer_email\` | Faktura → Nabywca → Email | Opcjonalne |
| Telefon | \`buyer_phone\` | Faktura → Nabywca → Telefon | Opcjonalne, maksymalnie 16 znaków |
| JST | \`buyer_jst\` | Faktura → Nabywca → JST | [Jednostka samorządu terytorialnego, wartość 1 lub 2](https://pomoc.fakturownia.pl/201969093-oznaczenia-jst-i-grupa-vat-po-stronie-nabywcy) |
| GV | \`buyer_gv\` | Faktura → Nabywca → Grupa VAT | Członek grupy VAT, wartość 1 lub 2 |

---

## Podmiot3 – Odbiorca / Wystawca

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

| 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 lub brak ID |
| Adres | \`street\`, \`post_code\`, \`city\`, \`country\` | Faktura → Dodatkowe podmioty → Adres | Opcjonalne |
| Email / Telefon | \`email\`, \`phone\` | Faktura → Dodatkowe podmioty → Dane kontaktowe | Opcjonalne |
| Rola | \`role\` | Faktura → Dodatkowe podmioty → Rola | Kod roli — patrz tabela poniżej |
| 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ł, tylko dla roli „Dodatkowy nabywca" |

### Dostępne role — Odbiorcy:

| Rola | Kod |
| --- | --- |
| Odbiorca | 2 |
| 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 |
| 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 |
| P_2 | \`number\` | Faktura → Numer faktury | Numer faktury nadawany przez system |
| WZ | \`warehouse_documents[].number\` | Faktura → Dokumenty magazynowe | Tylko dla faktur WZ, może być wiele dokumentów |
| P_6 | \`sell_date\` | Faktura → Data sprzedaży | Data wykonania usługi lub dostarczenia towaru |
| P_15 | \`price_gross\` | Faktura → Suma brutto | Obliczane automatycznie z pozycji faktury |
| RodzajFaktury | \`kind\` | Faktura → Rodzaj faktury | Patrz sekcja Rodzaje faktur |
| FP | \`issued_to_receipt\` | Faktura → Faktura do paragonu | Wartość 1 gdy faktura wystawiana do paragonu |
| TP | \`procedure_designations\` | Faktura → Oznaczenia procedur | Przekazywane gdy lista oznaczeń zawiera „TP" |

---

## 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.

| 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_13_3 / P_14_3 | 5% | Druga stawka obniżona |
| 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: 1 = tak, 2 = nie. Dotyczy faktur \`vat_mp\` |
| P_18 | \`reverse_charge\` | Faktura → Odwrotne obciążenie | Odwrotne obciążenie, wartość 1 lub 2 |
| P_18A | \`split_payment\` | Faktura → Podzielona płatność (MPP) | Mechanizm podzielonej płatności, wartość 1 lub 2 |
| 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_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)

| 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ść | Format z 4 miejscami 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 |
| 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 |
| 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 |
| 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 |

---

## 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 |
| 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 |

---

## 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 | \`description\` | 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 | \`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 |

---

## 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 na fakturze | \`description\` | 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: marzec 2026