KSeF 2.0 — klient Krajowego Systemu e-Faktur

Co potrafi (TL;DR)

Wbudowany klient Krajowego Systemu e-Faktur (KSeF 2.0) obsługuje pełny cykl e-faktury w schemacie FA(3) (kodSystemowy="FA (3)", wersjaSchemy="1-0E"): wysyłkę faktur z modułu fakturowania w sesji online lub wsadowej, pobieranie e-faktur sprzedażowych i zakupowych dla pojedynczego podmiotu albo wszystkich klientów biura naraz (z równoległym przetwarzaniem firm), wizualizację (HTML/PDF), automatyczne rozpoznawanie księgowania oraz logowanie certyfikatem MF lub tokenem. Obsługiwane trzy środowiska — produkcja, demo i test — plus monitorowanie dostępności KSeF przez „Latarnię" MF.

Pobieranie e-faktur z KSeF

Pobieranie uruchamia się pod węzłem „e-Faktury" w drzewie nawigacji programu. Dostępne są dwie operacje:

• „Pobierz dla podmiotu" — pobiera nowe e-faktury tylko dla aktualnie wskazanego klienta. Podmiot musi mieć wpisany certyfikat dostępowy lub token, albo (w wersji dla biur rachunkowych) wskazane upoważnione biuro z certyfikatem.
• „Pobierz wszystko" — uruchamia pobieranie kolejno dla wszystkich aktywnych klientów. Pomijani są klienci archiwalni i z wstrzymaną usługą; gdy klient nie ma własnego certyfikatu, program automatycznie próbuje certyfikatu biura.

Pobieranie odbywa się w trybie wsadowym — program ściąga paczki metadanych z paginacją, pobiera treść XML każdej nowej faktury i zapisuje ją z metadanymi (numer KSeF, daty wystawienia/przyjęcia/nadania numeru/trwałego zapisu, kwoty, sprzedawca, nabywca, podmiot upoważniony, podmioty trzecie). Faktura już obecna w bazie (po numerze KSeF w ramach firmy) jest pomijana. Zachowywany jest punkt kontynuacji umożliwiający wznowienie od miejsca przerwania.

Równoległe pobieranie wielu podmiotów dostępne w trybie „Pobierz wszystko" przez peryferyjny proces uruchamiany z parametrem --max-parallel-clients N — domyślnie 1, maksymalnie 10. Każdy klient pobierany niezależnie.

Logi importu w %PUBLIC%\Documents\TaxMachine\KSeFK\logs\ plus rejestr operacji w bazie (typ operacji, stan, postęp, numer KSeF ostatniej faktury, ewentualne błędy i log przebiegu).

Limiter czasowy: „Pobierz wszystko" nie częściej niż co 15 minut; analogiczne ograniczenie per klient zapobiega dublowaniu.

Automatyczne rozpoznawanie po wejściu na listę e-faktur — w tle przetwarzane są pozycje jeszcze nierozpoznane. Pozycje już rozpoznane nigdy nie są nadpisywane automatycznie.

Wysyłanie e-faktur do KSeF

Wysyłka z modułu fakturowania dwoma drogami:

• z okna edycji faktury — przycisk „Wyślij" na zakładce „eFaktura" (sesja online: numer KSeF dostępny praktycznie natychmiast),
• wsadowo z listy — zaznaczenie wielu faktur i „Wyślij faktury" (online) lub „Wyślij faktury wsadowo" (sesja wsadowa). Jedna sesja = mniej wywołań API.

Przed wysyłką generowany jest XML zgodny z FA(3). Walidacja schemy wykrywa błędy blokujące (pokazywane do poprawy) oraz mniej krytyczne ostrzeżenia z opcją zignorowania.

Po przyjęciu KSeF zwraca numer referencyjny sesji i numer elementu faktury; program odpytuje status (150 = przetwarzanie, 200 = przyjęta) i pobiera UPO zawierające numer KSeF (35 znaków, walidowane wyrażeniem regularnym). „Pobierz potwierdzenia" pobiera brakujące UPO dla wcześniej wysłanych faktur.

Limity wbudowane: sesja online 30 faktur/min, 180/godz. Sesja wsadowa bez tych limitów (numer KSeF dostępny później).

Tryb offline24 (awaria KSeF): prefiks OFF na fakturze, dwa kody QR (drugi podpisany certyfikatem sprzedawcy), faktura przekazywana do KSeF po przywróceniu systemu. Tryb offline z certyfikatem (Typ 2) NIE jest wspierany — program używa wyłącznie certyfikatów Typu 1 („Uwierzytelnienie w systemie KSeF").

Schemat FA(3)

Klient generuje i parsuje dokumenty w wariancie FA(3) wersja 1-0E (KodFormularza="FA", kodSystemowy="FA (3)", wersjaSchemy="1-0E", WariantFormularza="3", namespace http://crd.gov.pl/wzor/2025/06/25/13775/).

Obsługiwane sekcje podmiotów: Podmiot1 (sprzedawca), Podmiot1K (poprzednik prawny przy korektach — art. 106j ust. 2 pkt 3), Podmiot2 (nabywca), Podmiot3 (wiele wystąpień, każdy z rolą), PodmiotUpoważniony (jedna sekcja z rolą).

Role podmiotów trzecich (11 wartości):

Kod	Rola
1	Faktor
2	Odbiorca (jednostka wewnętrzna nabywcy)
3	Podmiot pierwotny (przejęty/przekształcony — dostawca/usługodawca)
4	Dodatkowy nabywca
5	Wystawca faktury (w imieniu podatnika)
6	Dokonujący płatności w miejsce nabywcy
7	Jednostka samorządu terytorialnego — wystawca
8	Jednostka samorządu terytorialnego — odbiorca
9	Członek grupy VAT — wystawca
10	Członek grupy VAT — odbiorca
11	Pracownik

Role podmiotu upoważnionego (3 wartości):

Kod	Rola	Podstawa prawna
1	Organ egzekucyjny	art. 106c pkt 1 ustawy o VAT
2	Komornik sądowy	art. 106c pkt 2 ustawy o VAT
3	Przedstawiciel podatkowy	art. 18a–18d ustawy o VAT

Rodzaje faktur w FA(3) (kody w XML):

Kod	Typ
VAT	Faktura podstawowa
ZAL	Faktura zaliczkowa (art. 106f ust. 4)
ROZ	Faktura rozliczeniowa / końcowa (art. 106f ust. 3)
UPR	Faktura uproszczona (art. 106e ust. 5 pkt 3)
KOR	Faktura korygująca
KOR_ZAL	Korekta faktury zaliczkowej
KOR_ROZ	Korekta faktury rozliczeniowej

Dodatkowo w metadanych pobranych e-faktur mogą występować typy z innych schematów MF (VAT_PEF, VAT_PEF_SP, KOR_PEF, VAT_RR, KOR_VAT_RR), ale program generuje fakturę wyłącznie w FA(3).

Typy korekty: 1 — w dacie ujęcia pierwotnej; 2 — w dacie wystawienia korekty; 3 — w dacie innej (różne daty per pozycja).

Stawki VAT (14 wartości): 23, 22, 8, 7, 5, 4, 3, 0 KR, 0 WDT, 0 EX, zw, oo, np I, np II.

Kody krajów UE (28 kodów): AT, BE, BG, CY, CZ, DE, DK, EE, EL (Grecja), ES, FI, FR, HR, HU, IE, IT, LT, LU, LV, MT, NL, PL, PT, RO, SE, SI, SK oraz XI (Irlandia Północna — odrębny kod dla transakcji towarowych po Brexicie).

Waluty — pełna lista zgodna z ISO 4217.

Wizualizacja e-faktury

Podgląd otwiera dedykowany formularz oparty na WebView2 (silnik Edge Chromium). HTML generowany jest z FA(3); w ribbonie: „Generuj PDF", „Wczytaj HTML", „Zapisz HTML", „Drukuj bezpośrednio", „Podgląd wydruku". Wydruk PDF przez WebView2 z konfigurowalnymi marginesami i rozmiarem strony. Wydruk wsadowy obsługiwany dla zaznaczonej grupy e-faktur.

Tryb compact (aktualizacje wiosna 2026) — podgląd po prawej w drzewie dokumentów oraz w oknie edycji dokumentu księgowego pokazuje tylko informacje istotne dla księgowego (bez kursu waluty, P_9B, P_10, akcyzy itp.). Pełne szczegóły w dedykowanym oknie podglądu.

Ostrzeżenia widoczne na wizualizacji:

• data sprzedaży pogrubiona ciemnoczerwona gdy różni się od daty wystawienia;
• data sprzedaży pozycji (P_6A) jako osobny wiersz pod pozycją;
• wnioskowana data sprzedaży (gdy na poziomie faktury brak — z pozycji albo z okresu fakturowania) z dopiskiem „(wyznaczona z pozycji P_6A)" lub „(okres rozliczeniowy)";
• baner ostrzegawczy dla różnych miesięcy sprzedaży pozycji z listą pozycji do ręcznego rozstrzygnięcia.

Wydruk PDF zachowuje datę sprzedaży pozycji, ale pomija ostrzeżenia i wewnętrzne wyliczenia.

Automatyczne księgowanie e-faktur

Program automatycznie ustala parametry księgowania nowo pobranej e-faktury:

• Data sprzedaży z pozycji (P_6A) — gdy na poziomie faktury brak P_6, pobierana jest najwcześniejsza P_6A; dla faktur okresowych daty z okresu fakturowania.
• Kurs waluty — z dnia poprzedzającego datę sprzedaży (a nie wystawienia), gdy data sprzedaży jest wcześniejsza. Wyliczane są wartości netto, VAT i brutto w PLN.
• Przepisywanie Dziennika i Schematu KR — program szuka poprzednich e-faktur lub zaksięgowanych dokumentów tego kontrahenta i przepisuje: dziennik, schemat księgowania, kolumnę KPiR, stawkę ryczałtu, rejestr VAT, opis, rodzaj kosztu pojazdu.
• Rozpoznawanie kosztów pojazdów — analiza pozycji pod kątem leasingu, OC/AC, nabycia pojazdu, paliwa/eksploatacji, z ograniczeniami odliczenia VAT (50/100%) i zaliczenia w koszty (75/100%) dla pojazdów osobowych. Nieodliczalny VAT trafia w koszty.
• Lista ostrzeżeń rozpoznawania — pokazywana w UI po rozpoznaniu, pomaga zweryfikować decyzje programu.

Faktury zaliczkowe: podatek dochodowy nie jest księgowany, zerowane są daty PD oraz pola KPiR/ryczałtu. Zaliczka trafia tylko do rejestru VAT (zakup lub sprzedaż wg strony) — nie jest jeszcze kosztem ani przychodem podatkowym.

Faktury rozliczeniowe (ROZ): dla faktury końcowej księgowana wartość liczona jest z pełnych netto pozycji (a nie z P_13_*, które dla ROZ zawiera kwoty po odjęciu zaliczek). Gdy XML ma tylko P_11A (brutto pozycji) bez P_11 — netto wyliczane jest z brutto i stawki VAT. VAT idzie nadal z różnicy po zaliczkach, a do księgi przychodów trafia pełna wartość pozycji (art. 14 ust. 1 ustawy o PIT).

Dwa poziomy rozpoznawania: domyślnie odświeżane są tylko pozycje jeszcze nierozpoznane — bezpiecznie wywoływane przed każdym księgowaniem i przy wejściu na listę. Drugi poziom (opt-in) odświeża również rozpoznane, ale niezmieniane ręcznie — przycisk „Ponownie rozpoznaj e-faktury" w oknie księgowania, do użycia po aktualizacji programu.

Bulk-edit z ribbona („Przełącz księgowanie", „Przełącz kolumnę KPiR", „Przełącz stawkę ryczałtu", „Przełącz okres księgowania", „Zastosuj do wszystkich e-faktur kontrahenta") gwarantuje rozpoznanie przed zmianą — działa również na fakturach nigdy nierozpoznanych.

„Księguj e-faktury do KR" — księgowanie partii e-faktur z przypisanym schematem KR; faktury bez schematu pomijane i raportowane. Program wybiera kandydatów na zadany okres (rok/miesiąc), opcjonalnie z zaległymi zakupowymi z poprzednich miesięcy (domyślnie 3 miesiące wstecz).

Certyfikaty i tokeny

Klient przyjmuje certyfikaty KSeF generowane w Aplikacji Podatnika MF z przeznaczeniem „Uwierzytelnienie w systemie KSeF" (Typ 1). Certyfikat to dwa pliki: klucz prywatny (.key) + klucz publiczny (.crt); program łączy je w PEM zapisywany w bazie per podmiot.

Wczytanie w oknie edycji firmy, zakładka „KSeF 2.0":

• Hasło — z Aplikacji Podatnika (15–32 znaki, wielka/mała litera, cyfra, znak specjalny). Błędne hasło → błąd OpenSSL.
• Weryfikacja certyfikatu/tokena — przycisk próbuje otworzyć sesję KSeF; sukces = dane poprawne.
• Podgląd informacji o certyfikacie — pola wystawcy, podmiotu, daty ważności (certyfikat KSeF ważny 2 lata).

Tokeny dostępowe — łatwiejsze (wkleja się w pole „Token"), ale obowiązują tylko do końca 2026 r. Token jest przypisany do konkretnego podmiotu — nie da się logować tokenem biura do konta klienta. Dla biur zalecane certyfikaty.

Wczytanie certyfikatu z innym przeznaczeniem niż „Uwierzytelnienie w systemie KSeF" kończy się błędem „brak uprawnień" (kod 21301) mimo poprawnego hasła. Limit MF: 6 certyfikatów / miesiąc / kontekst.

W wersji dla biur rachunkowych program automatycznie próbuje certyfikatu biura, gdy klient nie ma własnego — sesja otwierana certyfikatem biura w kontekście NIP klienta.

Środowiska

Klient obsługuje trzy środowiska KSeF:

Środowisko	Aplikacja Podatnika
Produkcja	https://ap.ksef.mf.gov.pl/web/
Demo (przedprodukcyjne)	https://ap-demo.ksef.mf.gov.pl/web/
Test	https://ap-test.ksef.mf.gov.pl/web/

Wybór środowiska — w konfiguracji programu (per firma) albo argumentem --env PROD|DEMO|TEST do peryferyjnych narzędzi KSeF (KSeFC.exe/KSeFD.exe). Domyślne: produkcja. Każde środowisko ma niezależne uprawnienia, certyfikaty i bazę faktur.

Monitorowanie dostępności KSeF — klient „Latarnia" odpytuje publiczne API MF (https://api-latarnia.ksef.mf.gov.pl dla produkcji, https://api-latarnia-test.ksef.mf.gov.pl dla testu); zwracane są komunikaty (kategorie FAILURE, TOTAL_FAILURE, MAINTENANCE) i statusy (AVAILABLE, MAINTENANCE, FAILURE, TOTAL_FAILURE). Wynik w pasku statusu okna głównego — pozwala sprawdzić sensowność wysyłki przed uruchomieniem. „Latarnia" to oddzielne narzędzie monitorujące udostępnione przez Ministerstwo Finansów.

Wspierane wersje i standardy

• Schemat FA(3) wersja 1-0E (atrybut wersjaSchemy), namespace http://crd.gov.pl/wzor/2025/06/25/13775/ (wzór opublikowany 25 czerwca 2025 r.).
• Klient zna również nagłówki FA(2), ale produkcyjna wysyłka odbywa się wyłącznie w FA(3).
• Pole SystemInfo nagłówka deklaruje wystawcę jako https://taxmachine.pl.
• Numer KSeF: 35 znaków, walidowany wyrażeniem regularnym.
• Obowiązek KSeF: 1 lutego 2026 (sprzedaż > 200 mln zł w 2024); 1 kwietnia 2026 — wszyscy pozostali; do 31 grudnia 2026 wyjątek dla mikrofaktur ≤ 10 000 zł/miesiąc B2B.

Ograniczenia

• Wymagane Windows 64-bit dla pełnej funkcjonalności KSeF — peryferyjne narzędzia KSeF działają w środowisku .NET 10 / Windows 64-bit. Program główny istnieje też w wersji 32-bit, ale nowe komponenty KSeF wymagają wersji 64-bit.
• Tryb offline z certyfikatem podatnika (Typ 2) NIE jest obsługiwany. Wspierane wyłącznie certyfikaty Typu 1 („Uwierzytelnienie w systemie KSeF") oraz tokeny. Tryb offline24 awaryjny działa (prefiks OFF, dwa kody QR), ale uwierzytelnienie nadal wymaga certyfikatu Typu 1.
• Dodatkowi nabywcy — schemat FA(3) dopuszcza wielu (rola 4), ale UI obecnie obsługuje jednego nabywcę + odbiorcę i płatnika.
• WarunkiTransakcji — element schemy nie jest jeszcze udostępniony w UI.
• Załączniki — element Zalacznik w FA(3) służy do danych ustrukturyzowanych, nie do plików PDF/JPG/XLS. Pliki binarne — poza KSeF.
• Limity API KSeF narzucone przez MF (z pliku WarościOgraniczeń.txt w katalogu programu): wysyłka pojedynczej faktury 1/60 min, inicjacja sesji online 1/60 min, inicjacja/zamknięcie sesji wsadowej 1/60 min, upload paczki wsadowej 2/60 min, zapytania o metadane 20/10 min, błędne wywołania 10/10 min.
• Program respektuje także własne, łagodniejsze limity wewnętrzne (np. ok. 16 pobrań/min, 64/godz dla treści faktur), tak aby nie wyczerpywać limitów MF przy intensywnym imporcie u biur rachunkowych.
• Sesja interaktywna ≤ 1 MB treści faktury; większe — sesją wsadową (kompresja i fragmentacja zip).

Integracja z resztą programu

• Moduł fakturowania — faktury wystawione w programie są źródłem dla generatora FA(3) (wypełnia węzły Faktura/Podmiot1/Podmiot2/Podmiot3/Fa). Status wysyłki i numer KSeF wracają na fakturę. Korekty referują poprzednią e-fakturę przez numer KSeF faktury korygowanej.
• Księgowość uproszczona (KPiR / ryczałt / rejestry VAT) — e-faktura zawiera komplet pól księgowania: dziennik, schemat KR, rejestr VAT (do dwóch rejestrów), kolumny KPiR (do trzech), stawki ryczałtu, wartości KPiR i ryczałtu, daty VAT i PD, flagi „Księguj", „Księguj VAT", „Księguj podatek dochodowy", oznaczenie PIT kasowy.
• Księgi rachunkowe (KR) — dziennik + schemat księgowania sterują automatycznym księgowaniem przez resolver KR.
• JPK — numer KSeF propagowany do JPK_V7 (oraz JPK_KR, JPK_FA). Pola Off, DI, BFK w oknie edycji dokumentu mapują nowe oznaczenia KSeF w JPK_V7(3).
• Środki trwałe — zakup ŚT z e-faktury automatycznie tworzy dowód zakupu w module ŚT.
• Pojazdy — e-faktura łączy się z ewidencją pojazdów: pojazd, rodzaj kosztu, procent odliczenia VAT, procent zaliczenia w koszty.
• Portal akceptacji e-faktur — pobrane e-faktury udostępniane klientom biur do akceptacji/wykluczenia pozycji (akceptacja, data zatwierdzenia, imię i nazwisko zatwierdzającego, uwagi klienta, pozycje wyłączone z księgowania).
• Opcjonalne AI — możliwość wzbogacenia rozpoznania księgowania sugestiami modelu LLM (data odczytu, data wysyłki, odpowiedź modelu).

Powiązane

• KSeF 2.0 — poradnik dla użytkownika — kompletna pomoc: pierwsze uruchomienie, uprawnienia, certyfikaty, FAQ.
• Fakturowanie i magazyn — moduł wystawiania faktur, źródło danych dla wysyłki KSeF.
• Portal akceptacji e-faktur — dla biur rachunkowych i ich klientów.
• Księgi rachunkowe — automatyczne księgowanie e-faktur przez schematy KR.
• Pobieranie e-faktur — instrukcja krok po kroku
• Wysyłanie e-faktur — instrukcja krok po kroku
• Księgowanie e-faktur
• Certyfikaty i tokeny KSeF
• Stawki VAT w FA(3)
• Wersje TaxMachine — który wariant programu zawiera klienta KSeF.