Kody QR na fakturach KSeF

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 (Ustawa o KSeF). To jedyny gwarant, że PDF odpowiada wystawionej fakturze, nie jest sfabrykowany.

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

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

• 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

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

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

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: ksef-qr.ts.

Flow:

1. Po wystawieniu faktury i otrzymaniu NrKSeF z API KSeF.
2. Numify liczy 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

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. ksef-qr.ts, funkcja generateKsefQr.

Typowe problemy

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

• 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

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 nie drukuje QR do momentu nadania NrKSeF — wizualizacja PDF trafia do odbiorcy dopiero po synchronizacji z KSeF i regeneracji dokumentu z poprawnym kodem QR.