---
title: "Kody QR na fakturach KSeF"
description: "Obowiązek umieszczenia kodu QR KSeF na wizualizacjach PDF faktury — format URL weryfikacji, biblioteka generowania, weryfikacja po stronie odbiorcy."
url: https://numifyai.com/docs/zgodnosc-z-prawem/ksef/kody-qr
review_status: internal
updated: 2026-04-16
---


Faktura ustrukturyzowana w KSeF może być dodatkowo przedstawiona w
postaci **wizualizacji PDF** — np. wysłana klientowi e-mailem dla
wygody. Taka wizualizacja **musi zawierać kod QR** umożliwiający
weryfikację faktury w KSeF (<LegalRef act="KSEF" />). To jedyny
gwarant, że PDF odpowiada wystawionej fakturze, nie jest sfabrykowany.

<ComplianceDisclaimer />

## Kiedy QR jest wymagany [#kiedy-qr-jest-wymagany]

Kod QR musi być umieszczony, jeśli wystawca udostępnia fakturę w formie
innej niż sam XML z KSeF — w praktyce:

* PDF wysłany klientowi e-mailem „dla wygody".
* Wydruk papierowy (np. do teczki księgowej, audytu).
* Faktura wyświetlana w panelu klienta / portalu samoobsługowym.

QR **nie jest potrzebny** wewnątrz samego KSeF — tam faktura jest
identyfikowana przez `NrKSeF` i nie ma postaci PDF.

## Format kodu [#format-kodu]

QR zawiera URL w następującym formacie:

```
https://ksef.mf.gov.pl/web/verify/{NrKSeF}/{Hash}
```

Gdzie:

* `{NrKSeF}` — globalny identyfikator nadany przez KSeF.
* `{Hash}` — **SHA-256 treści XML FA(3) faktury** (hex), obliczany
  z identycznego bajt-za-bajtem XML, który został przesłany do KSeF.
  Hash zapobiega podmianie PDF-a — jeżeli ktoś zmieni treść XML,
  hash się nie zgodzi i strona weryfikacyjna MF pokaże niezgodność.

### Przykład [#przykład]

* `NrKSeF`: `1234567890-20260416-ABCDEF12-34`
* Hash XML: `a3f1b...` (64 znaki hex)
* QR URL:
  `https://ksef.mf.gov.pl/web/verify/1234567890-20260416-ABCDEF12-34/a3f1b...`

Skanowanie kodu prowadzi bezpośrednio na stronę weryfikacyjną KSeF,
gdzie można zobaczyć oryginalną treść faktury oraz potwierdzenie,
że przekazany hash zgadza się z zarejestrowaną wersją XML.

## Umiejscowienie na fakturze [#umiejscowienie-na-fakturze]

Rekomendowane (nie sztywno wymagane ustawą, ale przyjęte przez MF):

* **Prawy górny róg pierwszej strony** — obok numeru faktury.
* Minimalny rozmiar: **2×2 cm** (przy standardowej rozdzielczości
  druku 300 DPI).
* Poziom korekcji błędów: minimum `M` (rekomendowane `Q`).

Numify umieszcza QR kod w prawym górnym rogu w szablonie PDF faktury.
Szczegóły generowania wizualizacji zostaną udokumentowane w sekcji
Dla deweloperów (Phase 7).

## Weryfikacja po stronie odbiorcy [#weryfikacja-po-stronie-odbiorcy]

Odbiorca faktury może zeskanować QR smartfonem — prowadzi to do
strony MF:

```
https://ksef.mf.gov.pl/web/verify/1234567890-20260416-ABCDEF12-34/a3f1b2c4...
```

(64-znakowy hash na końcu to SHA-256 treści XML FA(3)). Strona pokazuje:

* Wystawcę (NIP + nazwa).
* Nabywcę (NIP + nazwa).
* Datę wystawienia.
* Łączną kwotę netto / VAT / brutto.
* Status: `Poprawna` (przyjęta przez KSeF) lub `Anulowana` (jeśli
  faktura została skorygowana zerującą fakturą korygującą).

Dzięki temu odbiorca ma pewność, że PDF nie jest podrobiony — może
porównać dane z PDF-u z danymi na stronie MF.

## Generowanie QR w Numify [#generowanie-qr-w-numify]

Numify generuje QR lokalnie, bez zewnętrznych zależności od serwisów
online — to ważne z punktu widzenia RODO i wydajności. Implementacja:
<ServiceRef path="src/lib/services/ksef-qr.ts">ksef-qr.ts</ServiceRef>.

Flow:

1. Po wystawieniu faktury i otrzymaniu `NrKSeF` z API KSeF.
2. Numify liczy &#x2A;*SHA-256 XML-a FA(3)** używając `node:crypto`
   (dokładnie tej samej treści XML, która została wysłana do KSeF).
3. Numify buduje URL weryfikacyjny
   `https://ksef.mf.gov.pl/web/verify/{NrKSeF}/{Hash}`.
4. Koduje URL jako SVG (wektorowa reprezentacja QR).
5. Wstawia SVG do wizualizacji PDF faktury.

Biblioteka QR — własna minimalna implementacja (bez zależności od
`qrcode-generator` i podobnych) — poziom korekcji `Q`, wersja dobierana
automatycznie do długości danych.

## Testowy URL [#testowy-url]

W środowisku testowym KSeF URL ma ten sam kształt, ale używa
hosta `ksef-test.mf.gov.pl`:

```
https://ksef-test.mf.gov.pl/web/verify/{NrKSeF}/{Hash}
```

Numify wybiera środowisko na podstawie zmiennej `KSEF_ENV`
(`production` lub `test`, domyślnie `test`) — zob.
<ServiceRef path="src/lib/services/ksef-qr.ts">ksef-qr.ts</ServiceRef>,
funkcja `generateKsefQr`.

## Typowe problemy [#typowe-problemy]

### QR się nie skanuje [#qr-się-nie-skanuje]

Przyczyny:

* **Zbyt mały rozmiar** — minimum 2×2 cm na drukowanej fakturze.
* **Niski poziom korekcji błędów** — użyj `Q` lub `H` jeśli PDF jest
  kserowany / skanowany.
* **Niska rozdzielczość PDF** — generuj SVG, nie rastrowany PNG.

### QR prowadzi do błędu 404 na stronie MF [#qr-prowadzi-do-błędu-404-na-stronie-mf]

* `NrKSeF` błędnie wygenerowany (brak kontrolnej, błędny format).
* Faktura została anulowana — wtedy strona pokaże status `Anulowana`,
  ale URL działa.

### QR w trybie Offline24 [#qr-w-trybie-offline24]

W trybie Offline24 faktura ma jeszcze tymczasowy, lokalny numer —
`NrKSeF` zostanie nadany dopiero po przesłaniu do KSeF. Do tego
momentu QR powinien prowadzić do placeholder'a lub być pominięty.

Numify w Offline24 &#x2A;*nie drukuje QR do momentu nadania `NrKSeF`** —
wizualizacja PDF trafia do odbiorcy dopiero po synchronizacji z KSeF
i regeneracji dokumentu z poprawnym kodem QR.

<ChangeHistory>
  <ChangeEntry date="2026-04-16" act="Phase 2">
    Pierwsza wersja — zagregowana z `_legacy/KSEF-REFERENCE.md` oraz
    implementacji `ksef-qr.ts`.
  </ChangeEntry>
</ChangeHistory>