KSeF

KSeF (Krajowy System e-Faktur) to centralny system Ministerstwa Finansów, przez który podatnicy VAT w Polsce wystawiają i otrzymują faktury ustrukturyzowane. Obowiązkowy od 1 lutego 2026 r. dla dużych podatników i od 1 kwietnia 2026 r. dla pozostałych — obecnie obowiązuje dla wszystkich spółek z o.o. zarejestrowanych jako czynni podatnicy VAT.

Obowiązek w pigułce

Ustawa o VAT, art. 106ga ust. 1: podatnicy są obowiązani wystawiać faktury ustrukturyzowane przy użyciu KSeF. Faktura wystawiona poza KSeF po 1 kwietnia 2026 r. to faktura wadliwa — nie daje nabywcy prawa do odliczenia VAT naliczonego.

Wyjątki (Ustawa o VAT, art. 106ga ust. 2):

• Faktury dla osób fizycznych nieprowadzących działalności gospodarczej (B2C) — wystawiasz zwykłą fakturę / paragon.
• Faktury wystawione przez podatnika bez siedziby w Polsce (lub bez stałego miejsca prowadzenia działalności uczestniczącego w dostawie).
• Faktury w procedurach szczególnych (OSS / IOSS — sprzedaż konsumencka UE, usługi elektroniczne).
• Podatnicy zwolnieni z art. 113a (sprzedaż poniżej progu przez podatnika z siedzibą w innym państwie UE).

Dla typowej spółki z o.o. prowadzącej działalność B2B w Polsce wszystkie faktury sprzedaży i zakupu przechodzą przez KSeF.

Architektura — co robi Numify

Integracja KSeF w Numify ma trzy warstwy:

1. ksef-api.ts (src/lib/services/ksef-api.ts21 ✓) — niskopoziomowe wywołania REST API Ministerstwa Finansów: autoryzacja, sesja, wysyłka, odbiór, status.
2. ksef-service.ts (src/lib/services/ksef-service.ts40 ✓) — warstwa aplikacji: zarządzanie danymi uwierzytelniającymi, synchronizacja z lokalną bazą, powiązanie z fakturami Numify.
3. ksef-fa3-generator.ts / ksef-fa3-parser.ts (src/lib/services/ksef-fa3-generator.ts35 ✓ / src/lib/services/ksef-fa3-parser.ts29 ✓) — konwersja między modelem faktury Numify a schemą FA(3) (Ustawa o VAT, art. 106nda ust. 1).
4. ksef-qr.ts (src/lib/services/ksef-qr.ts11 ✓) — generowanie kodów QR na wydrukach faktur (wymagane, gdy faktura z KSeF jest udostępniana poza KSeF, np. drukowana dla nabywcy).

Przepływ danych — cztery ścieżki

A. Sprzedaż: wystawienie faktury przez Numify → KSeF

1. Użytkownik wystawia fakturę w Numify (faktury).
2. Numify konwertuje fakturę do FA(3) XML (ksef-fa3-generator.ts).
3. sendInvoiceToKsef wysyła XML do KSeF przez aktywną sesję (ksefReferenceNumber → status processing → ok / failed).
4. KSeF zwraca numer KSeF (unikalny identyfikator faktury w systemie).
5. Numify zapisuje numer KSeF przy fakturze; od tego momentu faktura jest „w KSeF".

Data wystawienia (Ustawa o VAT, art. 106nda ust. 10) to data wskazana przez podatnika na fakturze (data wystawienia), a nie data przydzielenia numeru KSeF — ma to znaczenie przy księgowaniu.

B. Zakup: synchronizacja faktur otrzymanych

1. syncReceivedInvoices(companyId) odpytuje KSeF o nowe faktury, gdzie nabywcą jest spółka (po NIP).
2. Dla każdej nowej faktury Numify:
   • Pobiera XML (downloadInvoice),
   • Parsuje FA(3) do modelu Numify (ksef-fa3-parser.ts),
   • Tworzy wpis w tabeli faktur otrzymanych z flagą source = 'ksef',
   • Próbuje dopasować do dokumentu (jeśli nabywca już przetworzył PDF tej samej faktury).
3. Użytkownik widzi nowe faktury w liście z banerem „Pobrane z KSeF".

Synchronizacja jest ręczna (przycisk „Synchronizuj") — planowana jest obsługa automatycznego pollingu (updatePollSettings już istnieje, ale scheduler nie jest jeszcze włączony).

C. Status wysłanej faktury

Po wysłaniu faktury do KSeF status (refreshInvoiceKsefStatus) przechodzi przez stany:

W przypadku failed faktura nie jest uznawana za wystawioną prawnie — wymaga korekty i ponownego wysłania.

D. Kod QR dla wersji drukowanej / PDF

Ustawa o VAT, art. 106nda ust. 6 wymaga, aby faktura z KSeF udostępniana poza KSeF (np. w PDF dla nabywcy) była oznaczona kodem QR umożliwiającym weryfikację autentyczności. Numify generuje kod przez ksef-qr.ts i umieszcza na PDF faktury.

Konfiguracja w Numify

1. Token uwierzytelniający

Spółka uzyskuje token KSeF w e-Urzędzie Skarbowym (profil zaufany lub podpis kwalifikowany członka zarządu). Token daje Numify uprawnienia do wystawiania faktur w imieniu spółki.

• saveCredentials(companyId, token) — zapisuje zaszyfrowany token w bazie.
• Token nigdy nie jest zwracany w API Numify — tylko używany wewnętrznie do negocjacji sesji.

2. Otwieranie sesji

• openSession(companyId) — wywołuje KSeF, pobiera challenge, szyfruje token, otrzymuje sessionToken ważny 2 godziny.
• Numify trzyma sessionToken w pamięci / bazie, odświeża przy potrzebie.

3. Zamykanie sesji

• closeSession(companyId, userId) — ręczne zakończenie sesji (np. przy zmianie tokenu).

Workflow — pierwsze uruchomienie

1. W e-Urzędzie Skarbowym — wygeneruj token KSeF dla swojej spółki (uprawnienia: wystawianie i odbiór faktur).
2. W Numify — wklej token na /ksef i zapisz.
3. Otwórz sesję (przycisk „Otwórz sesję" lub automatyczne otwarcie przy pierwszym użyciu).
4. Synchronizuj faktury otrzymane — pierwszy raz ściągnie wszystkie faktury od momentu rozpoczęcia obowiązywania KSeF dla spółki.
5. Wystaw testowo fakturę w Numify → zostanie automatycznie wysłana do KSeF.
6. Zweryfikuj numer KSeF na fakturze w liście — powinien pojawić się w ciągu kilkudziesięciu sekund.

Korekty faktur KSeF

Ustawa o VAT, art. 106nda ust. 12: faktura korygująca fakturę wystawioną w KSeF jest także wystawiana w KSeF po przydzieleniu numeru identyfikującego fakturze pierwotnej. Numify tworzy fakturę korygującą, pobiera numer KSeF pierwotnej z bazy i wysyła korektę jako osobny dokument FA(3) z odwołaniem.

Awarie KSeF i tryb offline

Ustawa przewiduje tryb awaryjny — gdy KSeF jest niedostępny, podatnik wystawia fakturę poza KSeF (w postaci elektronicznej zgodnie ze wzorem) i ma obowiązek przesłać ją do KSeF nie później niż następnego dnia roboczego po dniu jej wystawienia (Ustawa o VAT, art. 106nda ust. 2).

Numify w stanie niedostępności KSeF:

• Zapisuje fakturę lokalnie z flagą pending,
• Dodaje zadanie retry do kolejki (obecnie: ręczne, planowane: automatyczne via BullMQ),
• Pozwala wydrukować fakturę z kodem QR offline (Ustawa o VAT, art. 106nda ust. 6).

Po odzyskaniu łączności Numify automatycznie ponowi próbę wysłania.

Bezpieczeństwo tokenu

• Token jest szyfrowany przed zapisem do bazy — klucz szyfrowania w zmiennej środowiskowej (nie w kodzie).
• Token nie pojawia się w logach, w odpowiedziach API Eden ani w zrzutach błędów.
• Rotacja tokenu: usuń stary z bazy (saveCredentials z nowym tokenem), sesja zostanie zamknięta przy następnym wywołaniu.

Zakres obecnej implementacji — co jest, a czego nie ma

Jest:

• ✅ Autoryzacja tokenem, zarządzanie sesją (2 h TTL).
• ✅ Wysyłanie faktur sprzedaży w schemacie FA(3).
• ✅ Synchronizacja faktur otrzymanych (po NIP nabywcy).
• ✅ Kody QR na wydrukach faktur.
• ✅ Korekty faktur KSeF.

W planach / brak pełnego pokrycia:

• ⏳ Automatyczny polling faktur otrzymanych (harmonogram).
• ⏳ Faktury zaliczkowe i faktury WDT ze specjalnym oznaczeniem.
• ⏳ Obsługa pełnej palety komunikatów błędów KSeF (obecnie: podstawowe kody).
• ⏳ Uprawnienia wielu użytkowników do KSeF (obecnie: jedno konto tokena per spółka).

Księgowanie faktur KSeF

Faktury KSeF (sprzedaż i zakup) są księgowane identycznie jak faktury „klasyczne":

• Sprzedaż — zapis w dzienniku: 201 (Wn) / 700 (Ma) + VAT na 220 (Ma).
• Zakup — zapis w dzienniku: 400 (Wn) + 220 VAT naliczony (Wn) / 202 (Ma).

Patrz szczegółowo: faktury.

Powiązania

• Faktury — integracja KSeF działa automatycznie w tle; użytkownik wystawia fakturę, Numify wysyła do KSeF.
• Dokumenty — faktury pobrane z KSeF są dopasowywane do dokumentów PDF/IMG, jeśli nabywca już przetworzył wizualną wersję.
• Rejestr VAT — wszystkie faktury KSeF trafiają do rejestru VAT automatycznie.
• Eksporty — JPK_V7 agreguje faktury z rejestru VAT bez względu na źródło (KSeF / ręczne / import).