---
title: "KSeF"
description: "Integracja z Krajowym Systemem e-Faktur (KSeF) — zapis tokena API, otwieranie i zamykanie sesji, synchronizacja faktur otrzymanych oraz wysyłanie faktur wystawionych w schemacie FA(3). Obowiązkowy KSeF od 1 kwietnia 2026 r. dla podatników VAT czynnych z siedzibą w Polsce."
url: https://numifyai.com/docs/korzystanie-z-numify/ksef
review_status: numify-source
updated: 2026-04-17
---


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

<ComplianceDisclaimer />

{/* SCREENSHOT: ekran /ksef — karta statusu sesji (aktywna / nieaktywna), sekcja tokenu, przycisk Synchronizuj faktury, tabela otrzymanych faktur KSeF */}

## Obowiązek w pigułce [#obowiązek-w-pigułce]

<LegalRef act="VAT" art="106ga" paragraph="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** (<LegalRef act="VAT" art="106ga" paragraph="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 [#architektura--co-robi-numify]

Integracja KSeF w Numify ma trzy warstwy:

1. **`ksef-api.ts`** (<ServiceRef path="src/lib/services/ksef-api.ts" tests="21" />) — niskopoziomowe wywołania REST API Ministerstwa Finansów: autoryzacja, sesja, wysyłka, odbiór, status.
2. **`ksef-service.ts`** (<ServiceRef path="src/lib/services/ksef-service.ts" tests="40" />) — 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`** (<ServiceRef path="src/lib/services/ksef-fa3-generator.ts" tests="35" /> / <ServiceRef path="src/lib/services/ksef-fa3-parser.ts" tests="29" />) — konwersja między modelem faktury Numify a schemą &#x2A;*FA(3)** (<LegalRef act="VAT" art="106nda" paragraph="1" />).
4. **`ksef-qr.ts`** (<ServiceRef path="src/lib/services/ksef-qr.ts" tests="11" />) — 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 [#przepływ-danych--cztery-ścieżki]

### A. Sprzedaż: wystawienie faktury przez Numify → KSeF [#a-sprzedaż-wystawienie-faktury-przez-numify--ksef]

1. Użytkownik wystawia fakturę w Numify (<FeatureRef slug="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 (<LegalRef act="VAT" art="106nda" paragraph="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 [#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 <FeatureRef slug="dokumenty">dokumentu</FeatureRef> (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 [#c-status-wysłanej-faktury]

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

| Status       | Znaczenie                                       |
| ------------ | ----------------------------------------------- |
| `pending`    | Faktura wysłana, oczekuje na przetworzenie      |
| `processing` | KSeF walidację schematu FA(3)                   |
| `ok`         | Faktura zaakceptowana, numer KSeF przydzielony  |
| `failed`     | Odrzucona — Numify przechowuje kod błędu i opis |

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

### D. Kod QR dla wersji drukowanej / PDF [#d-kod-qr-dla-wersji-drukowanej--pdf]

<LegalRef act="VAT" art="106nda" paragraph="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 [#konfiguracja-w-numify]

{/* SCREENSHOT: sekcja konfiguracji — pole tokenu API, przycisk Otwórz sesję, status sesji z datą ważności */}

### 1. Token uwierzytelniający [#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 [#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 [#3-zamykanie-sesji]

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

## Workflow — pierwsze uruchomienie [#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 [#korekty-faktur-ksef]

<LegalRef act="VAT" art="106nda" paragraph="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 [#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
(<LegalRef act="VAT" art="106nda" paragraph="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 (<LegalRef act="VAT" art="106nda" paragraph="6" />).

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

## Bezpieczeństwo tokenu [#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 [#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 [#księgowanie-faktur-ksef]

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

* **Sprzedaż** — zapis w dzienniku: <AccountRef code="201" /> (Wn) / <AccountRef code="700" /> (Ma) + VAT na <AccountRef code="220" /> (Ma).
* **Zakup** — zapis w dzienniku: <AccountRef code="400" /> (Wn) + <AccountRef code="220" /> VAT naliczony (Wn) / <AccountRef code="202" /> (Ma).

Patrz szczegółowo: <FeatureRef slug="faktury" />.

## Powiązania [#powiązania]

* <FeatureRef slug="faktury">Faktury</FeatureRef> — integracja KSeF działa automatycznie w tle; użytkownik wystawia fakturę, Numify wysyła do KSeF.
* <FeatureRef slug="dokumenty">Dokumenty</FeatureRef> — faktury pobrane z KSeF są dopasowywane do dokumentów PDF/IMG, jeśli nabywca już przetworzył wizualną wersję.
* <FeatureRef slug="vat-register">Rejestr VAT</FeatureRef> — wszystkie faktury KSeF trafiają do rejestru VAT automatycznie.
* <FeatureRef slug="exports">Eksporty</FeatureRef> — JPK\_V7 agreguje faktury z rejestru VAT bez względu na źródło (KSeF / ręczne / import).