KSeF i KOD I: dlaczego skrót faktury w linku QR to SHA-256 w Base64URL, a nie hex ani „zwykłe” Base64
Link pod kodem QR na wizualizacji faktury z KSeF wygląda niewinnie: adres, NIP, data i ciąg znaków na końcu. Ten ostatni element psuje najwięcej integracji. Ktoś wkleja wynik sha256sum (hex), ktoś inny bierze invoiceHash
Link pod kodem QR na wizualizacji faktury z KSeF wygląda niewinnie: adres, NIP, data i ciąg znaków na końcu. Ten ostatni element psuje najwięcej integracji. Ktoś wkleja wynik sha256sum (hex), ktoś inny bierze invoiceHash z odpowiedzi API (zwykłe Base64 z +, / i =), a jeszcze ktoś liczy skrót z XML-a, który po drodze „ładnie sformatował” edytor. Link się generuje, QR się skanuje, a weryfikacja nie znajduje faktury.
Poniżej rozbieramy KOD I na części, liczymy skrót na przykładowym pliku i pokazujemy cztery najczęstsze pułapki.
Z czego składa się KOD I
Według dokumentacji technicznej KSeF 2.0 (plik kody-qr.md w repozytorium CIRFMF/ksef-api, dawniej ksef-docs; stan repozytorium z 17.11.2026, sprawdzone 22.11.2026) link do weryfikacji faktury składa się z:
- adresu środowiska (
https://qr-test.ksef.mf.gov.pl,https://qr-demo.ksef.mf.gov.pllub produkcyjniehttps://qr.ksef.mf.gov.pl) i ścieżki/invoice, - NIP-u sprzedawcy,
- daty wystawienia z pola
P_1w formacie DD-MM-RRRR, - skrótu SHA-256 pliku faktury w formacie Base64URL.
Przykład z dokumentacji:
https://qr-test.ksef.mf.gov.pl/invoice/1111111111/01-02-2026/UtQp9Gpc51y-u3xApZjIjgkpZ01js-J8KflSPW8WzIE
Ostatni segment ma 43 znaki. SHA-256 to zawsze 32 bajty: w hex daje to 64 znaki, w zwykłym Base64 44 znaki (z jednym = na końcu), a w Base64URL bez dopełnienia 43 znaki. Już sama długość mówi, który format wkleiłeś.
Strona Ministerstwa Finansów o kodach weryfikujących (ksef.podatki.gov.pl, sprawdzone 22.11.2026) nazywa ten element „wyróżnikiem faktury” i odsyła po szczegóły do specyfikacji API.
Przykład krok po kroku (dane ilustracyjne)
Weźmy celowo mały, fikcyjny plik faktura-demo.xml. To nie jest poprawna struktura FA(3), tylko 137 bajtów do policzenia skrótu (UTF-8, końce linii LF, znak nowej linii na końcu):
<?xml version="1.0" encoding="UTF-8"?>
<Faktura><P_1>2026-11-20</P_1><NIP>1111111111</NIP><Nazwa>Przykładowa Spółka</Nazwa></Faktura>
NIP 1111111111 to wartość testowa z dokumentacji, nie prawdziwa firma.
1. SHA-256 w hex (to wypisuje sha256sum):
5f2abe0658a2d01c58824d1756afdb1349ace4a75a2cb201b8c9d137d021dc84
2. Te same 32 bajty w zwykłym Base64 (taki format ma invoiceHash w API KSeF, które według changelogu używa wspólnego schematu Sha256HashBase64):
Xyq+Blii0BxYgk0XVq/bE0ms5KdaLLIBuMnRN9Ah3IQ=
3. Base64URL bez =: + zamieniamy na -, / na _, a dopełnienie usuwamy:
Xyq-Blii0BxYgk0XVq_bE0ms5KdaLLIBuMnRN9Ah3IQ
4. Data: w XML-u P_1 zapisujemy jako 2026-11-20 (format daty XML), a w linku musi być 20-11-2026.
Wynik (środowisko testowe):
https://qr-test.ksef.mf.gov.pl/invoice/1111111111/20-11-2026/Xyq-Blii0BxYgk0XVq_bE0ms5KdaLLIBuMnRN9Ah3IQ
Ten link pokazuje tylko budowę adresu. Fikcyjnego pliku nie ma w KSeF, więc weryfikacja niczego nie znajdzie.
Wszystkie trzy postacie skrótu policzyliśmy w Pythonie, OpenSSL i Node.js i dały identyczny wynik. Tak samo robi oficjalny klient C# (VerificationLinkService): dekoduje invoiceHash z Base64 do bajtów i koduje je ponownie jako Base64URL bez dopełnienia.
Jak sprawdzić to w przeglądarce (krótko)
Narzędzie: URL-Safe Base64 Encoder & Decoder (interfejs jest po angielsku, nie ma wersji polskiej).
- Kliknij Encode to Base64.
- W Character Set wybierz Hexadecimal. Przełącznik URL-Safe Format jest na tej stronie zawsze włączony.
- Wklej hex z
sha256sum. Przy włączonym Live Conversion wynik pojawi się od razu, w innym przypadku kliknij Convert. Potem Copy.
Dla naszego pliku wychodzi Xyq-Blii0BxYgk0XVq_bE0ms5KdaLLIBuMnRN9Ah3IQ. Możesz też przejść w drugą stronę: w trybie Decode Base64 z Character Set Hexadecimal wklej invoiceHash z API i porównaj bajty. Wszystko liczy się lokalnie w przeglądarce, ale i tak nie wklejaj tam produkcyjnych danych, jeśli polityka firmy tego zabrania.
Ujawnienie: to narzędzie pochodzi od Mind vs Drive, zespołu, który prowadzi ten blog.
Cztery pułapki, które dają „poprawnie wyglądający” zły link
1. Base64 z tekstu hex zamiast z bajtów. Jeśli zostawisz Character Set na UTF-8 i wkleisz hex, narzędzie (jak każdy koder) zakoduje 64 znaki tekstu, a nie 32 bajty skrótu. Wyjdzie 86-znakowy ciąg zaczynający się od NWYyYWJlMDY1OGEy…. Ten sam błąd robi sha256sum plik | base64, który dodatkowo koduje nazwę pliku.
2. Zwykłe Base64 w ścieżce URL. / w Xyq+Blii0BxYgk0XVq/bE0… dzieli segment ścieżki na dwa, + bywa zamieniany na spację, a = jest zbędny. Dlatego Base64URL.
3. Skrót z innych bajtów niż wysłany plik. Ten sam tekst z końcami linii CRLF (139 bajtów) daje LLl97LTeQGfJyBL-zAQZz-Mwfq4jTj-fmvOOJ6QpotA. Z BOM-em UTF-8 na początku (140 bajtów) wychodzi 13F9JB1illzH68F-wRAPJ_7qfePdgr7BXlLhV9GhTkI, a bez końcowego znaku nowej linii JVUkitWbiCu4BdvdBkJd-h_NV5XX3eYraAUhGe6Hl_I. Skrót liczy się z dokładnie tych bajtów, które trafiły do KSeF, przed szyfrowaniem i bez ponownej serializacji XML.
4. Data w złym formacie. 2026-11-20 albo 20.11.2026 zamiast 20-11-2026. To pole P_1, a nie data przyjęcia w KSeF.
Kod: od pliku do linku
OpenSSL (bez xxd, który nie wszędzie jest zainstalowany):
openssl dgst -sha256 -binary faktura-demo.xml | base64 | tr '+/' '-_' | tr -d '='
Python:
import base64, hashlib
def ksef_kod_i(xml_bytes: bytes, nip: str, p1_iso: str,
base="https://qr-test.ksef.mf.gov.pl") -> str:
digest = hashlib.sha256(xml_bytes).digest()
h = base64.urlsafe_b64encode(digest).rstrip(b"=").decode()
rrrr, mm, dd = p1_iso.split("-")
return f"{base}/invoice/{nip}/{dd}-{mm}-{rrrr}/{h}"
with open("faktura-demo.xml", "rb") as f:
print(ksef_kod_i(f.read(), "1111111111", "2026-11-20"))
Node.js (od wersji 15.7 digest obsługuje 'base64url'):
const { createHash } = require("node:crypto");
const fs = require("node:fs");
const h = createHash("sha256")
.update(fs.readFileSync("faktura-demo.xml"))
.digest("base64url"); // bez '=' na końcu
Masz już invoiceHash z API? Nie licz skrótu drugi raz. Zdekoduj Base64 do bajtów i zakoduj jako Base64URL: base64.urlsafe_b64encode(base64.b64decode(invoice_hash)).rstrip(b"=").
Szybki test przed wdrożeniem
- Segment skrótu ma 43 znaki i nie zawiera
+,/ani=. - Po zdekodowaniu wychodzi dokładnie 32 bajty.
- Data ma format DD-MM-RRRR i pochodzi z
P_1. - Skrót z linku zgadza się z
invoiceHashz API po konwersji Base64 → Base64URL.
Pamiętaj, że Base64URL to tylko zapis bajtów, nie szyfrowanie ani podpis. KOD I nie potwierdza autentyczności wystawcy. Do tego przy fakturach offline służy osobny KOD II z podpisem certyfikatem KSeF. Ten artykuł nie jest poradą podatkową ani prawną. Wiążąca jest aktualna dokumentacja Ministerstwa Finansów.
Źródła (sprawdzone 22.11.2026):
- Dokumentacja KSeF 2.0, kody QR: https://github.com/CIRFMF/ksef-api/blob/main/kody-qr.md
- Changelog API (schemat
Sha256HashBase64dlainvoiceHash): https://github.com/CIRFMF/ksef-api/blob/main/api-changelog.md - Oficjalny klient C#,
VerificationLinkService: https://github.com/CIRFMF/ksef-client-csharp - Kody weryfikujące QR, ksef.podatki.gov.pl: https://ksef.podatki.gov.pl/informacje-ogolne-ksef-20/kody-weryfikujace-qr/
- RFC 4648, §5 (Base64URL): https://www.rfc-editor.org/rfc/rfc4648.html#section-5
— The Mind vs Drive team
Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.