Wszystkie pojęcia KSeF w jednym miejscu.

Schemat FA(3) i pola faktury

Struktura pliku XML, który KSeF akceptuje. Walidator MF nie wybacza brakujących pól.

FA(3)#

schemat FA(3)

Aktualnie obowiązujący wariant schematu faktury ustrukturyzowanej. Zawiera ponad 300 pól, z których część jest obowiązkowa (NIP, kwoty, daty), część opcjonalna. Starsze warianty (FA(1), FA(2)) są odrzucane przez walidator KSeF. Więcej w artykule →

Nagłówek#

Naglowek

Sekcja XML zawierająca metadane dokumentu: kod formularza (FA), numer wariantu schematu, datę wytworzenia pliku oraz system, który go wygenerował. Wymagany w każdej fakturze FA(3).

Podmiot1 (sprzedawca)#

Sekcja z danymi wystawcy faktury: NIP, nazwa, adres, opcjonalnie e-mail i telefon. NIP musi być aktywny w bazie KSeF, w przeciwnym razie wysyłka się nie powiedzie.

Podmiot2 (nabywca)#

Sekcja z danymi kupującego. Dla podmiotu krajowego B2B obowiązkowy jest NIP. Dla nabywcy z UE potrzebny jest VAT-UE z prefiksem kraju. Faktury B2C (osoby fizyczne nieprowadzące działalności) nie podlegają obowiązkowi KSeF.

Fa (sekcja faktury)#

Sekcja zawierająca treść faktury: numer, daty, pozycje, kwoty netto/VAT/brutto, walutę, formę płatności. To największa i najbardziej złożona część schematu FA(3).

Numer referencyjny KSeF#

Unikalny identyfikator nadawany przez KSeF po przyjęciu faktury. Format: ciąg liczbowy zwracany w UPO. Stanowi prawny dowód, że faktura dotarła do systemu i została zaakceptowana.

Faktura korygująca#

Korekta uprzednio wystawionej faktury. W FA(3) ma osobny węzeł z odwołaniem do numeru referencyjnego pierwotnej faktury. Korekta zwiększająca i zmniejszająca podstawę VAT mają różne pola.

Faktura zaliczkowa#

Faktura wystawiana przed dostawą towaru lub wykonaniem usługi, dokumentująca otrzymanie zaliczki. W FA(3) ma dedykowane pola wskazujące powiązanie z fakturą końcową.

Tokeny, autoryzacja i uprawnienia

Jak biuro rachunkowe technicznie uzyskuje prawo do wysyłki faktur w imieniu klienta.

Token KSeF#

token autoryzacyjny

Ciąg znaków wydawany przez Ministerstwo Finansów konkretnemu podatnikowi. Token działa jak hasło aplikacyjne: pozwala dowolnemu systemowi zewnętrznemu (np. cockpitowi KSeF) wykonywać operacje w imieniu danego NIP, bez znajomości hasła do konta podatnika. Więcej w artykule →

Format tokenu#

Standardowy format: YYYYMMDD-EC-HEX-HEX-NN|nip-XXXXXXXXXX|HEX. Pierwszy człon zawiera datę wystawienia, drugi typ (EC = token osobowy), trzeci identyfikator, środkowa sekcja (po pionowej kresce) potwierdza, do jakiego NIP-u token jest powiązany.

Uprawnienia tokenu#

Każdy token ma określony zakres: wystawianie faktur, odbiór faktur, przeglądanie, zarządzanie uprawnieniami. Biuro rachunkowe potrzebuje minimum „wystawianie” i „przeglądanie”, aby wysyłać faktury i odczytywać UPO.

Właściciel (w kontekście NIP)#

Osoba, która zalogowała się do KSeF jako właściciel danego NIP (np. członek zarządu spółki, jednoosobowy przedsiębiorca). Tylko właściciel może wygenerować token i nadać uprawnienia innym osobom.

Portal Podatnika#

Strona Ministerstwa Finansów (ksef.podatki.gov.pl), na której podatnik loguje się, generuje tokeny, sprawdza historię faktur i zarządza uprawnieniami. Niezależna od cockpitów KSeF dostępnych na rynku.

Podpis kwalifikowany#

Elektroniczny podpis weryfikowany certyfikatem wydanym przez kwalifikowanego dostawcę usług zaufania. W KSeF używany do uwierzytelniania właściciela NIP. Alternatywą jest token wygenerowany w Portalu Podatnika.

Wysyłka i potwierdzenie

Co dzieje się od kliknięcia „Wyślij” do otrzymania UPO.

UPO#

Urzędowe Poświadczenie Odbioru

Dokument XML zwracany przez KSeF po przyjęciu faktury. Zawiera numer referencyjny KSeF, datę przyjęcia i podpis Ministerstwa Finansów. UPO jest dowodem doręczenia faktury i powinien być archiwizowany przez minimum 5 lat. Więcej w artykule →

Sesja interaktywna#

Tryb wysyłki, w którym klient KSeF wysyła pojedynczą fakturę i czeka na natychmiastową odpowiedź (sukces lub błąd walidacji). Używany przez Portal Podatnika MF i większość pojedynczych integracji.

Sesja wsadowa#

Tryb wysyłki paczki faktur (do 10 000 plików w jednym ZIP). Klient KSeF otrzymuje numer sesji, a wynik (UPO lub lista błędów) pojawia się asynchronicznie po przetworzeniu. Wykorzystywany przez biura rachunkowe wysyłające setki faktur miesięcznie. Więcej w artykule →

Tryb offline (offline FA(3))#

Awaryjny tryb wystawiania faktur, gdy KSeF jest niedostępny (planowane okna serwisowe lub awaria). Faktury wystawione offline muszą zostać retroaktywnie wgrane do KSeF po przywróceniu dostępu, w terminie określonym w komunikacie MF.

Walidacja FA(3)#

Sprawdzenie pliku XML pod kątem zgodności ze schematem FA(3): obecność wszystkich obowiązkowych pól, poprawne typy danych, zgodne typy NIP, poprawna struktura węzłów. Walidator MF odrzuca faktury z brakującymi lub nieprawidłowymi polami. Więcej w artykule →

Środowiska i kanały

Środowisko produkcyjne#

Faktyczny KSeF, w którym wysyłki mają moc prawną. Adres API: ksef.podatki.gov.pl. Tokeny wygenerowane w Portalu Podatnika działają tylko tutaj.

Środowisko testowe#

Niezależna instancja KSeF (ksef-test.mf.gov.pl) służąca do testowania integracji. Faktury wysyłane tutaj nie mają mocy prawnej. Tokeny testowe są generowane osobno przez Uwierzytelnienie testowe na portalu.

Biała Lista VAT#

Wyszukiwarka czynnych podatników VAT prowadzona przez Ministerstwo Finansów (podatki.gov.pl/wykaz-podatnikow-vat-wyszukiwarka). Przed wysyłką faktury warto sprawdzić, czy NIP nabywcy figuruje na Białej Liście jako aktywny.

JPK_VAT#

Jednolity Plik Kontrolny dla podatku VAT. Inny obowiązek raportowy niż KSeF: JPK_VAT to comiesięczna agregacja faktur do urzędu skarbowego, a KSeF to bieżąca rejestracja każdej faktury w momencie wystawienia.

Statusy i najczęstsze błędy

Kody, które najczęściej widzisz w odpowiedziach API KSeF.

Status 200 — sukces#

Faktura została przyjęta przez KSeF. Wraz z odpowiedzią zwracany jest numer referencyjny i UPO.

Status 400 — błąd walidacji#

Plik FA(3) nie przeszedł walidacji schematu. W odpowiedzi zwracana jest lista konkretnych pól, które są nieprawidłowe lub brakujące. Faktura nie jest zarejestrowana w KSeF. Więcej w artykule →

Status 401 — autoryzacja#

Token jest nieprawidłowy, wygasł lub nie ma odpowiednich uprawnień. Najczęściej oznacza, że klient wygenerował token bez uprawnienia „wystawianie” lub token wygasł między wystawieniem a wysyłką. Więcej w artykule →

Status 450 — token nieprawidłowy w kontekście NIP#

Token nie pasuje do NIP-u, w imieniu którego próbujemy wystawić fakturę. Najczęstsza przyczyna: użycie tokenu klienta A do wysyłki faktury klienta B.

Compliance i RODO

Aspekty prawne, które dotyczą biur rachunkowych przekazujących dane klientów do narzędzi KSeF.

Art. 28 RODO#

Artykuł rozporządzenia o ochronie danych osobowych regulujący relację administrator-procesor. Każde biuro rachunkowe korzystające z zewnętrznego cockpitu KSeF musi mieć z dostawcą zawartą umowę powierzenia zgodną z art. 28.

Umowa powierzenia (DPA)#

Umowa powierzenia przetwarzania danych osobowych. Określa zakres danych, cel przetwarzania, czas, listę subprocesorów, prawa do audytu i obowiązek powiadomienia o naruszeniu w 24 godziny.

Kary za niewystawienie faktury w KSeF#

Stan prawny na kwiecień 2026 r.: ustawa przewiduje karę pieniężną do 100% kwoty VAT wykazanego na fakturze wystawionej poza KSeF, nie mniej niż 1 000 zł za każdą fakturę. Aktualne brzmienie sprawdź w ustawie o VAT na gov.pl/web/finanse. Niniejszy zapis nie stanowi porady podatkowej.

Archiwizacja UPO#

Obowiązek przechowywania UPO przez minimum 5 lat licząc od końca roku kalendarzowego, w którym wystawiono fakturę. UPO musi być dostępne w postaci elektronicznej dla organów kontroli.