Kod QR na fakturze KSeF – KOD I i KOD II: z czego się składa i jak go wygenerować
Kod QR KSeF to zakodowany link do faktury w KSeF: adres qr.ksef.mf.gov.pl, NIP sprzedawcy, data wystawienia z pola P_1 i skrót SHA-256 pliku XML. Nanosisz go na każdą fakturę ustrukturyzowaną przekazywaną lub używaną poza KSeF, a pod nim numer KSeF albo napis „OFFLINE”. Faktura offline wydana przed wysyłką dostaje drugi kod, z napisem „CERTYFIKAT”.
Spis treści
Kod QR KSeF to graficzna postać linku do faktury w Krajowym Systemie e-Faktur: adres https://qr.ksef.mf.gov.pl/invoice, NIP sprzedawcy, data wystawienia z pola P_1 i skrót SHA-256 pliku XML. Program sprzedawcy nanosi go na każdą fakturę ustrukturyzowaną przekazywaną lub używaną poza KSeF – tak stanowi art. 106gb ust. 5 ustawy o VAT.
Poniżej rozbieramy kod na części: co jest w linku, jaki napis dać pod kodem, jak go wygenerować we własnym programie i co najczęściej psuje weryfikację. Certyfikat do drugiego kodu omawiamy w tekście certyfikat offline KSeF, a dokument z dwoma kodami wydawany przy kasie – w tekście potwierdzenie transakcji.
Kiedy faktura musi mieć kod QR?
Przepis art. 106gb ust. 5 wymienia dwie sytuacje:
- udostępniasz fakturę poza KSeF nabywcy z art. 106gb ust. 4 – np. firmie zagranicznej, konsumentowi albo podmiotowi bez NIP,
- używasz faktury poza KSeF w inny sposób – drukujesz ją, wysyłasz PDF mailem, przekazujesz dalej.
Drugi przypadek nie dotyczy tylko sprzedawcy. Według ust. 5a kod nanosi też „podmiot inny niż podatnik”, który używa faktury poza KSeF. MF wyjaśnia, że wydruk faktury z KSeF może być dokumentem księgowym, jeśli ma kod QR z numerem KSeF (FAQ KSeF 2.0, sekcja „KSeF w JST”, pyt. 40). Więcej: czy faktury z KSeF trzeba drukować.
Kodu nie potrzebujesz, gdy faktura krąży tylko w KSeF, bo krajowy nabywca z NIP odbiera ją w systemie. Nie ma go też faktura wystawiona całkowicie poza KSeF – w limicie 10 000 zł do końca 2026 r., w czasie awarii całkowitej czy konsumencka na papierze – bo nie ma do czego linkować. Konsumentowi lub nabywcy bez NIP, który chce odebrać fakturę przez KSeF, możesz dać sam kod z danymi do jej zidentyfikowania, bez wydruku (art. 106gb ust. 6).
KOD I i KOD II – czym się różnią?
| Cecha | KOD I | KOD II |
|---|---|---|
| Zadanie | dostęp do faktury w KSeF i weryfikacja jej danych | potwierdzenie, kto wystawił fakturę offline i czy miał do tego prawo |
| Kiedy go dajesz | na każdej fakturze używanej poza KSeF, online i offline | tylko na fakturze offline (offline24, niedostępność, tryb awaryjny) wydanej poza KSeF przed wysyłką |
| Ścieżka w linku | /invoice |
/certificate |
| Składniki | NIP sprzedawcy, data z P_1, skrót pliku |
typ i wartość identyfikatora kontekstu, NIP sprzedawcy, numer seryjny certyfikatu, skrót pliku, podpis |
| Napis pod kodem | numer KSeF albo „OFFLINE” | „CERTYFIKAT” |
| Certyfikat KSeF | niepotrzebny | konieczny, typu 2 (offline) |
| Podstawa | art. 106gb ust. 5; § 9 ust. 1 i 3 rozporządzenia | art. 106nda ust. 6 pkt 2 i ust. 7; § 9 ust. 10 rozporządzenia |
Żadnego kodu nie zamawiasz w KSeF. Program generuje oba lokalnie, z danych wystawionej faktury (cz. II pkt 5.4).
Z czego składa się link w kodzie QR?
KOD I to zwykły adres internetowy o stałym układzie. Dla faktury z 17 listopada 2026 r. wygląda tak:
https://qr.ksef.mf.gov.pl/invoice/1111111111/17-11-2026/bF2vSxZ717I2miD7LYVkqd3j-R-95YJhaOyuGC-U_7Y
| Element | Skąd go wziąć | Format |
|---|---|---|
| adres | środowisko, do którego wysyłasz fakturę | produkcja qr.ksef.mf.gov.pl, test qr-test.ksef.mf.gov.pl, demo qr-demo.ksef.mf.gov.pl |
| ścieżka | stała | /invoice |
| NIP sprzedawcy | Podmiot1, także przy samofakturowaniu |
10 cyfr, jak w pliku |
| data | pole P_1; w korekcie – P_1 faktury korygującej |
DD-MM-RRRR, np. 17-11-2026 |
| skrót | SHA-256 z bajtów pliku XML | Base64URL, 43 znaki |
Skrót to „wyróżnik faktury” z § 2 pkt 6 rozporządzenia w sprawie korzystania z KSeF: ciąg wyliczony z 256-bitowego skrótu pliku XML, algorytmem z rodziny SHA-2 (cz. II pkt 5.4.3). Dokumentacja API wymaga zapisu Base64URL, więc znaki + i / zamieniasz na - i _, a końcowe = usuwasz. Ten sam skrót w zwykłym Base64 – bF2vSxZ717I2miD7LYVkqd3j+R+95YJhaOyuGC+U/7Y= – do linku się nie nadaje, bo ukośnik rozbiłby ścieżkę adresu.
Numeru KSeF w linku nie ma. Drukujesz go pod kodem – czym jest i gdzie go znaleźć, wyjaśniamy w tekście numer KSeF.
Co dochodzi w KOD II?
Link zaczyna się od https://qr.ksef.mf.gov.pl/certificate. Dalej są kolejno: typ identyfikatora kontekstu (Nip, InternalId, NipVatUe lub PeppolId), jego wartość, NIP sprzedawcy, numer seryjny certyfikatu, skrót pliku i podpis. Podpisujesz ciąg bez https://, od nazwy hosta do skrótu włącznie, kluczem prywatnym certyfikatu typu 2. Dokumentacja dopuszcza RSASSA-PSS z SHA-256 (klucz co najmniej 2048 bitów) albo ECDSA na krzywej P-256 – dla ECDSA zaleca format IEEE P1363, krótszy i o stałej długości. Podpis także zapisujesz w Base64URL.
Jaki napis umieścić pod kodem QR?
- Numer KSeF – pod KOD I, gdy faktura już go ma: faktura online i offline dosłana do KSeF (§ 9 ust. 1 pkt 2 rozporządzenia).
- „OFFLINE” – pod KOD I, dopóki numeru nie ma (§ 9 ust. 3). Dokumentacja API każe użyć tego napisu także przy fakturze online, która wyjątkowo czeka na numer, np. przy dużym obciążeniu systemu.
- „CERTYFIKAT” – pod KOD II (§ 9 ust. 10 pkt 2).
Gdy faktura offline dostanie numer, na kolejnej wizualizacji wystarczy jeden kod z numerem KSeF (FAQ, sekcja „Tryby offline i kody QR”, pyt. 9). Sam link w KOD I zostaje taki sam, bo NIP, data i skrót się nie zmieniają – to nasz wniosek z budowy linku.
Gdy fakturę przekazujesz jako same dane, np. przez EDI, i nie ma gdzie nanieść kodu, wysyłasz razem z nią osobny link albo obrazek kodu z właściwym napisem (§ 9 ust. 8 rozporządzenia, cz. II pkt 5.4.4).
Jak wygenerować kod QR KSeF we własnym programie?
- Zapisz ostateczny plik XML faktury zgodny ze schematem FA(3), w UTF-8 bez znaku BOM. Od tej chwili go nie zmieniaj.
- Policz SHA-256 z bajtów tego pliku. To ta sama wartość, którą program podaje przy wysyłce w polu
invoiceHash(tam w zwykłym Base64). Nie bierzencryptedInvoiceHash– to skrót pliku zaszyfrowanego. - Przekoduj skrót na Base64URL.
- Odczytaj
P_1i zamień na DD-MM-RRRR, a NIP weź zPodmiot1. - Złóż link z adresem środowiska, do którego wysyłasz fakturę.
- Zakoduj link jako kod QR zgodny z normą ISO/IEC 18004:2024 (§ 9 ust. 9 rozporządzenia).
- Dopisz pod kodem numer KSeF albo „OFFLINE”.
W pseudokodzie:
skrot = base64url(sha256(bajty_wyslanego_pliku_xml)) // bez znaków "=" na końcu
data = P_1 w formacie DD-MM-RRRR
link = "https://qr.ksef.mf.gov.pl/invoice/" + NIP_sprzedawcy + "/" + data + "/" + skrot
MF nie określa minimalnego rozmiaru kodu ani poziomu korekcji błędów – przepisy i dokumentacja odsyłają tylko do normy. Naszym zdaniem warto sprawdzić skanowanie telefonem na prawdziwym wydruku, zwłaszcza z drukarki termicznej. Gotowe metody do budowy linków i obrazków kodów mają oficjalne biblioteki MF: dla C# i dla Javy.
A w aplikacjach MF?
Nic nie liczysz sam. Według MF fakturę oznaczysz kodem także w bezpłatnych aplikacjach ministerstwa (cz. II pkt 5.4), a z Aplikacji Podatnika i z aplikacji mobilnej pobierzesz ją jako PDF. Podręcznik Aplikacji Mobilnej KSeF pokazuje fakturę offline zapisaną w telefonie, opatrzoną parą kodów QR (pkt 6.12.1). Zanim wyślesz PDF klientowi, sprawdź, czy ma kod i numer pod nim. Kod QR z „wizytówki” w aplikacji mobilnej to coś innego – zawiera dane twojej firmy, żeby sprzedawca wczytał je jako dane nabywcy (pkt 6.7).
Co widzi osoba, która zeskanuje kod?
KOD I otwiera stronę KSeF z informacją, czy faktura jest w systemie, i z jej podstawowymi danymi: numerem KSeF, NIP sprzedawcy, datą wystawienia, skrótem, datą nadania numeru, typem schemy i trybem (ONLINE lub OFFLINE). System informuje też, czy plik zapisany w KSeF to ten sam dokument, z którego powstał link (cz. II pkt 5.5). Żeby pobrać fakturę, trzeba wpisać jej numer, identyfikator nabywcy i kwotę należności ogółem. Po kilku błędnych próbach z rzędu KSeF czasowo blokuje pobranie, a blokada obejmuje skrót tej faktury. Krok po kroku: jak odebrać fakturę w KSeF.
KOD II zwraca wynik kontroli certyfikatu: jego istnienie i ważność, poprawność podpisu oraz uprawnienie posiadacza do fakturowania w imieniu sprzedawcy. Danych osobowych strona nie ujawnia (cz. II pkt 5.6).
Jakie błędy psują kod QR?
| Błąd | Skutek | Poprawka |
|---|---|---|
| skrót z innego pliku niż wysłany: zapisanego ponownie, sformatowanego, z BOM, z PDF albo z pliku zaszyfrowanego | KSeF nie znajduje faktury albo pokazuje niezgodność dokumentu | licz skrót z bajtów wysłanego XML |
| data w formacie RRRR-MM-DD lub z kropkami | link nie prowadzi do faktury | DD-MM-RRRR z myślnikami |
data wysłania lub nadania numeru zamiast P_1 |
link nie prowadzi do faktury | zawsze data z P_1 |
| skrót w Base64 zamiast Base64URL | link nie prowadzi do faktury | zamień + i /, usuń = |
adres qr-test lub qr-demo na fakturze produkcyjnej |
nabywca szuka faktury w środowisku testowym | qr.ksef.mf.gov.pl |
| NIP nabywcy zamiast sprzedawcy, np. przy samofakturowaniu | link nie prowadzi do faktury | NIP z Podmiot1 |
| „OFFLINE” na wizualizacji faktury, która ma już numer | kod działa, ale nabywca nie widzi numeru | wydaj wizualizację z numerem KSeF |
Skutki w kolumnie środkowej to nasza ocena wynikająca z budowy linku – MF nie publikuje listy komunikatów strony weryfikacji.
Najczęstsze pytania
Czy każda faktura w KSeF musi mieć kod QR?
Nie. Kod jest potrzebny, gdy przekazujesz fakturę poza KSeF albo używasz jej poza systemem – jako PDF, wydruk czy załącznik e-maila. Faktura, którą krajowy nabywca z NIP odbiera tylko w KSeF, kodu nie wymaga, a faktura wystawiona całkowicie poza KSeF w ogóle go nie ma.
Jak wygenerować kod QR KSeF?
Program liczy skrót SHA-256 pliku XML wysłanego do KSeF, zapisuje go w Base64URL i składa link: qr.ksef.mf.gov.pl/invoice, NIP sprzedawcy, data z P_1 w formacie DD-MM-RRRR i skrót. Link koduje jako QR zgodny z normą ISO/IEC 18004:2024, a pod kodem dopisuje numer KSeF.
Co jest napisane pod kodem QR na fakturze KSeF?
Pod pierwszym kodem numer KSeF faktury, a zanim faktura go dostanie – napis OFFLINE. Pod drugim kodem, który ma tylko faktura offline wydana poza KSeF przed wysyłką, napis CERTYFIKAT.
Czy kod QR zawiera numer KSeF?
Nie. Link w kodzie tworzą NIP sprzedawcy, data z pola P_1 i skrót pliku. Numer KSeF drukuje się pod kodem, a system pokazuje go też po zeskanowaniu.
Dlaczego po zeskanowaniu kodu KSeF nie znajduje faktury?
Najczęściej faktura offline nie została jeszcze wysłana albo program policzył skrót z innego pliku niż wysłany, użył złego formatu daty lub adresu środowiska testowego. W tych trzech ostatnich przypadkach kod trzeba wygenerować od nowa.
Źródła
- Ustawa o VAT, tekst jedn. Dz.U. 2026 poz. 1263, art. 106gb ust. 3–6 i art. 106nda ust. 6–8
- Rozporządzenie MFiG w sprawie korzystania z KSeF, Dz.U. 2025 poz. 1815 ze zm., § 2 pkt 6, § 7 i § 9
- Podręcznik KSeF 2.0 cz. II (MF, 06.08.2026), pkt 5.3–5.7
- CIRFMF/ksef-api, „Kody weryfikujące QR” – środowiska, budowa linków KOD I i KOD II, algorytmy podpisu
- FAQ KSeF 2.0 (MF) – sekcja „Tryby offline i kody QR”, pyt. 6–10; „Wystawianie i otrzymywanie faktur”, pyt. 34; „KSeF w Jednostkach Samorządu Terytorialnego”, pyt. 40
- Podręcznik użytkownika Aplikacji Mobilnej KSeF, wersja 2.4.0 (29.10.2026), pkt 6.7 i 6.12.1
Artykuł ma charakter informacyjny i nie stanowi porady podatkowej. W konkretnej sprawie skonsultuj się z księgowym lub doradcą podatkowym.