E-Invoice Finder
Menu
Kraje Oprogramowanie Terminy Przewodniki Checker Sprawdź obowiązek
ENFRDEPLNL
Polska · test wdrożenia Offline24

KSeF Offline24: kody QR i pakiet testów ERP

Przetestuj Offline24 w ERP: dwa kody QR, certyfikat typu 2, hash faktury, kolejkę, terminy wysyłki i dowody wznowienia.

Praktyczne podsumowanie:
  • Zakres odbioru powinien objąć XML, podpisywane adresy oraz zachowanie dokumentu przed i po nadaniu numeru KSeF.
  • Najpoważniejsze ryzyko wdrożeniowe to rozjazd bajtów pliku między wyliczeniem skrótu, wysyłką i późniejszą wizualizacją.
  • Najpierw przeprowadź jeden kontrolowany przebieg na środowisku testowym, zachowując znaczniki czasu i wyniki skanowania.
Sprawdź raport gotowościŹródła oficjalne
Ostatnia aktualizacja: 4 sierpnia 2026Źródła oficjalneJasne podsumowanieInformacja praktyczna, nie porada prawna
Priorytet dla źródeł oficjalnych
Widoczne daty weryfikacji
Darmowy checker bez rejestracji

Co warto wiedzieć

Przewodnik

1. Ustal, kiedy stosować Offline24 i kiedy potrzebne są dwa kody

Oficjalnie każdy podatnik może wybrać Offline24, także przy trudnościach z Internetem lub siecią transmisyjną. Nie należy jednak oznaczać w ERP tego trybu jako urzędowej niedostępności, awarii ani awarii całkowitej KSeF — są to odrębne zdarzenia i mają inne skutki. Właściciel procesu podatkowego powinien zatwierdzić regułę wyboru trybu, a właściciel produktu przełożyć ją na jednoznaczny status dokumentu. Dwa kody dotyczą szczególnego przypadku: faktura offline jest udostępniana poza KSeF przed jej przesłaniem nabywcy objętemu art. 106gb ust. 4, np. konsumentowi, kontrahentowi zagranicznemu lub nabywcy bez NIP. KOD I ma etykietę OFFLINE, a KOD II — CERTYFIKAT. Krajowy podatnik VAT zwykle odbiera fakturę przez KSeF, więc nie wolno automatycznie dodawać pary kodów do każdej faktury Offline24. Kryterium odbioru: macierz odbiorców daje oczekiwany kanał i zestaw kodów dla co najmniej pięciu profili, bez przypadku, w którym sam wybór Offline24 wymusza dwa kody. Typowy błąd to utożsamienie trybu podatnika z komunikatem o awarii systemu.

Przewodnik

2. Zamroź dane FA(3), P_1 i bajty XML przed obliczeniem skrótu

Wymóg oficjalny: faktura musi być wystawiona elektronicznie w obowiązującej strukturze logicznej — od 1 lutego 2026 r. FA(3) — a datą wystawienia jest wartość pola P_1. Kod nie zastępuje faktury ustrukturyzowanej; PDF lub inna wizualizacja jest tylko jej czytelną reprezentacją. Zespół integracji powinien walidować XML względem schemy, NIP sprzedawcy i P_1 przed przygotowaniem adresów. Zalecana kontrola techniczna: serializować dokument deterministycznie, zachować dokładny plik bajtowy i z niego liczyć SHA-256, kodowany następnie jako Base64URL. Nie jest to dodatkowy ustawowy etap testowy, lecz sposób ograniczenia ryzyka, że kosmetyczna ponowna serializacja zmieni hash. Właściciel: architekt integracji; ryzyko: hash w kodzie prowadzi do innych danych niż plik wysłany. Kryterium: dziesięć powtórzeń generacji dla tych samych danych daje identyczne bajty, skrót i adres, a zmiana jednego pola biznesowego zmienia skrót i jest wykrywana przed publikacją wizualizacji.

Przewodnik

3. Zaimplementuj KOD I: dostęp i weryfikacja danych faktury

KOD I powstaje lokalnie z bazowego adresu weryfikacji właściwego środowiska, daty P_1, NIP sprzedawcy oraz skrótu SHA-256 pliku faktury zapisanego jako Base64URL. Przed wysłaniem do KSeF grafika otrzymuje czytelną etykietę OFFLINE. Jej funkcją jest zapewnienie dostępu do faktury i sprawdzenie zgodności danych, nie potwierdzenie tożsamości wystawcy. Programista powinien budować adres z jawnie typowanych elementów, bez pobierania daty z zegara systemowego zamiast P_1 i bez hashowania PDF. Produkcyjnym hostem jest qr.ksef.mf.gov.pl; test i demo mają oddzielne hosty. Zalecana bramka CI odrzuca host niezgodny z profilem wdrożenia. Właściciel: zespół ERP; błędy: standardowy Base64 zamiast Base64URL, niewłaściwy NIP, zmiana XML po wyliczeniu hasha. Kryterium: skaner odczytuje link, test referencyjny potwierdza wszystkie składniki, a negatywne próby z innym P_1, NIP i skrótem nie przechodzą porównania.

Przewodnik

4. Zaimplementuj KOD II z certyfikatem typu 2 i ochroną klucza

KOD II ma etykietę CERTYFIKAT i pozwala zweryfikować tożsamość wystawcy oraz autentyczność powiązania. Adres obejmuje typ i wartość identyfikatora kontekstu, NIP sprzedawcy, numer seryjny certyfikatu, ten sam hash faktury i podpis kryptograficzny wykonany aktywnym kluczem prywatnym certyfikatu KSeF typu 2 Offline. Certyfikat typu 1 do uwierzytelniania nie może wygenerować KODU II. Oficjalne parametry i algorytm należy implementować zgodnie z dokumentacją techniczną, bez własnych skrótów formatu. Zalecane kontrole: klucz pozostaje w chronionym magazynie, usługa podpisująca ma minimalne uprawnienia, a log zawiera identyfikator operacji zamiast sekretu. Właściciel: bezpieczeństwo aplikacyjne wraz z integracją; ryzyka: użycie nieaktywnego certyfikatu, błędny kontekst lub wyciek klucza. Kryterium: poprawny kod przechodzi weryfikację, manipulacja hashem lub podpisem kończy się odmową, typ 1 jest blokowany przed podpisaniem, a test nie ujawnia materiału kluczowego w logach.

Przewodnik

5. Uruchom macierz end-to-end na realistycznym przykładzie

Przykład: spółka z polskim NIP wystawia 4 sierpnia o 16:40 fakturę FA(3) dla zagranicznego nabywcy bez NIP, udostępnia ją przed wysyłką i wybiera Offline24 z powodu słabego łącza. ERP zamraża XML, wpisuje 4 sierpnia w P_1, liczy hash, tworzy KOD I i podpisuje KOD II certyfikatem typu 2, po czym zapisuje dokument w kolejce z offlineMode:true. Tester skanuje oba kody z ekranu i wydruku, a po odzyskaniu łączności system wysyła dokładnie te same bajty. Macierz powinna wariantować odbiorcę krajowego i zagranicznego, kanał przed wysyłką i po niej, granicę dnia roboczego, aktywny i niewłaściwy certyfikat, zmianę XML, brak sieci oraz odpowiedź odrzucającą. Zalecenie testowe, nie wymóg ustawowy: dla każdego wariantu zapisać oczekiwany stan, kody, termin, żądanie API i wynik. Właściciel: QA integracyjne. Kryterium: wszystkie ścieżki wysokiego ryzyka mają wynik pass/fail, właściciela defektu i odtwarzalny artefakt, a żadna wizualizacja nie jest traktowana jako plik FA(3).

Przewodnik

6. Dopnij kolejkę, termin, idempotencję i uzgodnienie

W Offline24 fakturę należy przesłać do KSeF bez zwłoki, najpóźniej następnego dnia roboczego po wystawieniu, aby uzyskała numer KSeF. Zgłoszenie API używa offlineMode:true. Wyjątek: jeśli przed przesłaniem wystąpi oficjalnie ogłoszona awaria KSeF, termin zmienia się na siedem dni roboczych od jej zakończenia; przy awarii całkowitej faktury nie wysyła się później. Logika terminów musi więc rozróżniać tryb wybrany przez podatnika i urzędowy stan systemu. Zalecane kontrole operacyjne: trwała kolejka, klucz idempotencji, ponowienia z narastającym odstępem, kalendarz dni roboczych, alarm przed terminem oraz uzgodnienie hash–status–numer KSeF. Właściciel: operacje integracji; ryzyka: duplikat, pominięcie lub błędne przesunięcie terminu. Kryterium: restart usługi nie gubi pozycji ani nie tworzy drugiego dokumentu, symulacja północy i święta daje prawidłowy termin, a każda zaakceptowana pozycja ma numer KSeF i zamknięty ślad uzgodnienia.

Przewodnik

7. Odbierz skanowanie, renderowanie, środowiska i dostępność

Grafiki kodów powinny odpowiadać ISO/IEC 18004:2024. Jeżeli format dostarczenia faktury nie przenosi grafiki, link lub grafika oraz właściwa etykieta mogą zostać przekazane osobno wraz z fakturą. Testuj nie tylko idealny PDF: druk biurowy, ekran telefonu, skalowanie, kontrast, margines, kompresję i kilka popularnych skanerów. Etykiety OFFLINE i CERTYFIKAT muszą pozostać widoczne i nie mogą być zamienione. Oddzielne sekrety, konfiguracje i hosty dla testu, demo i produkcji powinny uniemożliwiać przypadkowe mieszanie środowisk. Po przyjęciu faktury i nadaniu numeru KSeF późniejsza wizualizacja poza KSeF zawiera jeden KOD I opisany tym numerem, a nie wcześniejszą parę. Właściciel: QA kanałów dokumentowych; kryterium: 100% próbek w zatwierdzonym zestawie urządzeń skanuje właściwy adres, automatyczny test blokuje obcy host, tekstowa alternatywa zawiera link i etykietę, a regeneracja po akceptacji pokazuje jeden właściwie opisany kod.

Przewodnik

8. Przetestuj odrzucenie, korektę techniczną i wznowienie

Odrzucenie z powodu technicznego błędu walidacji nie daje prawa do zmiany treści biznesowej pod pozorem naprawy. Udokumentowany mechanizm korekty technicznej może powiązać poprawiony technicznie plik z hashem odrzuconego oryginału; zespół powinien stosować go wyłącznie w granicach oficjalnej specyfikacji. Zachowaj odpowiedź KSeF, oryginalny plik i hash, poprawiony plik, relację między nimi oraz decyzję osoby odpowiedzialnej. Osobna reguła: faktura korygująca dotycząca oryginału wystawionego w Offline24 powinna zaczekać, aż oryginał otrzyma numer KSeF. Właściciel: podatkowy właściciel procesu i support L2; ryzyka: cicha zmiana kwoty, utrata powiązania lub wysłanie korekty za wcześnie. Kryterium: test odrzucenia pozostawia pełny ślad, kontrola różnic ujawnia zmianę biznesową i ją blokuje, wznowienie jest idempotentne, a korekta merytoryczna nie opuszcza kolejki przed zapisaniem numeru oryginału.

Przewodnik

9. Wybierz dostawcę, zbierz dowody i zaplanuj kolejne kroki

Dostawca powinien pokazać działający przepływ, a nie tylko deklarację zgodności: deterministyczny XML i hash, oba kody przed wysyłką w właściwym przypadku, jeden kod po nadaniu numeru, podpis typu 2, separację środowisk, kolejkę, idempotencję, uzgodnienie i kontrolowane odrzucenie. Zapytaj, kto aktualizuje schemę FA(3), reguły adresów i kalendarz oraz jaki jest czas usunięcia błędu krytycznego. Pakiet dowodowy powinien zawierać wersje komponentów, przypadki testowe, próbki bez danych wrażliwych, wyniki skanów, logi statusów, dowody ochrony klucza, raport uzgodnienia, listę ryzyk i podpisy właścicieli. Są to rekomendowane kontrole wdrożeniowe, nie katalog obowiązków ustawowych. Decyzję go/no-go podejmują wspólnie właściciele podatkowy, technologiczny i bezpieczeństwa. Mierzalna bramka: zero otwartych defektów krytycznych, 100% zaliczonych scenariuszy obowiązkowych, przypisany monitoring terminów i zaakceptowana procedura powrotu. Następnie wykonaj pilotaż na ograniczonej grupie kontrahentów i przegląd dowodów po pierwszym cyklu. Materiał ma charakter praktyczny, nie stanowi porady prawnej ani podatkowej.

Lista kontrolna

Rozdziel w modelu stanów Offline24 od urzędowej niedostępności, awarii i awarii całkowitej.

Zweryfikuj FA(3), P_1 i NIP, a następnie zamroź dokładne bajty XML przed obliczeniem SHA-256.

Generuj KOD I z bazowego adresu właściwego środowiska i etykietuj go OFFLINE przed wysyłką.

Twórz KOD II wyłącznie aktywnym certyfikatem typu 2 i chroń jego klucz prywatny.

Dodawaj dwa kody tylko wtedy, gdy faktura jest udostępniana poza KSeF przed przesłaniem właściwemu odbiorcy.

Wyślij zachowany plik z offlineMode:true i kontroluj termin następnego dnia roboczego.

Przetestuj trwałość kolejki, idempotencję, ponowienia, kalendarz i uzgodnienie numeru KSeF.

Skanuj kody z każdego wspieranego kanału oraz automatycznie blokuj mieszanie hostów środowisk.

Zachowaj artefakty odrzucenia i blokuj techniczną naprawę, która zmienia treść biznesową.

Nie wysyłaj korekty do oryginału Offline24, dopóki oryginał nie otrzyma numeru KSeF.

Najczęstsze pytania

Czy każda faktura wystawiona w Offline24 musi mieć dwa kody QR?

Nie. Para KOD I i KOD II jest potrzebna przed wysłaniem, gdy faktura offline jest udostępniana poza KSeF odbiorcy objętemu art. 106gb ust. 4, np. konsumentowi, nabywcy zagranicznemu lub bez NIP. Krajowy podatnik VAT zwykle odbiera dokument przez KSeF.

Co sprawdzają KOD I i KOD II?

KOD I, oznaczony przed wysłaniem jako OFFLINE, zapewnia dostęp do faktury i weryfikację jej danych poprzez hash pliku. KOD II, oznaczony CERTYFIKAT, służy do potwierdzenia tożsamości wystawcy i autentyczności dzięki podpisowi kluczem certyfikatu typu 2.

Czy certyfikat typu 1 wystarczy do utworzenia KODU II?

Nie. KOD II wymaga aktywnego certyfikatu KSeF typu 2 Offline oraz odpowiadającego mu klucza prywatnego. Typ 1 służy uwierzytelnianiu i nie może być użyty do wygenerowania tego kodu.

Z czego budowany jest KOD I?

Lokalnie z bazowego adresu weryfikacji właściwego środowiska, daty wystawienia z P_1, NIP sprzedawcy i skrótu SHA-256 pliku faktury zakodowanego jako Base64URL. Hash powinien dotyczyć dokładnego XML wysyłanego do KSeF, nie wizualizacji PDF.

Jaki kod umieścić na wizualizacji po nadaniu numeru KSeF?

Po przyjęciu dokumentu późniejsza wizualizacja przekazywana poza KSeF zawiera jeden KOD I opisany nadanym numerem KSeF. Nie należy odtwarzać przedwysyłkowej pary OFFLINE i CERTYFIKAT.

Do kiedy trzeba wysłać fakturę z Offline24?

Bez zbędnej zwłoki, najpóźniej następnego dnia roboczego po wystawieniu. Jeśli przed przesłaniem wystąpi oficjalnie ogłoszona awaria, termin wynosi siedem dni roboczych od jej zakończenia; przy awarii całkowitej dokumentu nie przesyła się później.

Jak sprawdzić, że kolejka offline nie tworzy duplikatów?

W testach przerwij transmisję przed i po przyjęciu żądania, zrestartuj usługę i powtórz operację z tym samym kluczem idempotencji. Odbiór powinien wykazać jedną pozycję biznesową, zachowany hash, jednoznaczny status oraz jeden uzgodniony numer KSeF.

Czy po technicznym odrzuceniu można poprawić treść faktury?

Mechanizm korekty technicznej służy naprawie problemu walidacyjnego i może wiązać poprawiony plik z hashem odrzuconego oryginału. Nie jest podstawą do zmiany treści biznesowej; takie różnice należy wykrywać, blokować i obsługiwać właściwym procesem.

Kluczowe przepisy, formaty i pojęcia

Komisja EuropejskaEN 16931Dyrektywa 2014/55/UEustrukturyzowana faktura elektronicznaKSeF Offline24: kody QR i pakiet testów ERPPolska

Czytaj dalej

Źródła oficjalne

Priorytetowo traktujemy oficjalne źródła rządowe i UE, gdy są dostępne, oraz pokazujemy daty weryfikacji.