KSeF OFFLINE w integracji ERP: jak rozdzielić procedurę, lifecycle faktury i status API

KSeF OFFLINE w integracji ERP: jak rozdzielić procedurę, lifecycle faktury i status API

Stan na 29 września 2026 r.

Jeżeli integracja KSeF traktuje OFFLINE jako kolejny przypadek błędu wysyłki, zaczyna mieszać procesy, które podlegają innym regułom. Retry odpowiada na pytanie, co zrobić z nieudaną operacją komunikacyjną. Offline24, niedostępność i tryb awaryjny określają natomiast kontekst wystawienia dokumentu, termin jego późniejszego przesłania oraz zasady udostępnienia go odbiorcy.

To rozróżnienie ma bezpośredni wpływ na model danych. Jedno pole offline=true, sent=false albo status ERROR nie wystarczy do sterowania terminami, obsługą kodów QR, wydaniem dokumentu i recovery.

Praktycznym modelem integracji jest rozdzielenie co najmniej trzech informacji:

1. procedury, w której dokument jest obsługiwany,

2. lokalnego lifecycle faktury,

3. rzeczywistego trybu i wyniku po stronie KSeF.

Nie jest to state machine narzucona przez Ministerstwo Finansów. To rekomendacja architektoniczna wynikająca z reguł prawnych i technicznych KSeF.

OFFLINE w API i procedura offline to nie to samo

Dokumentacja KSeF rozróżnia dwa techniczne tryby wysyłki: ONLINE i OFFLINE. Z technicznego trybu OFFLINE korzystają natomiast różne procedury: offline24, niedostępność KSeF i tryb awaryjny. Różnią się przesłanką zastosowania i terminem późniejszego przesłania faktury.

Awaria całkowita jest odrębnym przypadkiem. Nie należy jej traktować jako kolejnego wariantu offlineMode z dłuższym terminem wysyłki. Dokumentów objętych regułami awarii całkowitej nie przesyła się później do KSeF.

Źródłem terminów są ustawa o VAT i oficjalne materiały Ministerstwa Finansów dotyczące poszczególnych procedur.

Nazwa offline24 może być myląca z perspektywy implementacji. Termin nie oznacza stałych 24 godzin. Regułą jest przesłanie niezwłocznie, nie później niż następnego dnia roboczego po dniu wystawienia.

Jeżeli aplikacja zapisze wyłącznie:

offline = true
created_at = ...

to po restarcie nadal nie będzie wiadomo, dlaczego dokument jest offline, według jakiej reguły policzono jego deadline oraz czy późniejsze oficjalne zdarzenie KSeF powinno zmienić dalszą obsługę.

Timeout API nie oznacza oficjalnej awarii KSeF

Timeout, błąd transportowy albo odpowiedź 5xx opisują wynik konkretnej komunikacji między aplikacją a KSeF. Nie dowodzą same w sobie, że rozpoczęła się formalna niedostępność albo awaria systemu.

Przepisy wiążą niedostępność i awarię z oficjalnymi komunikatami. CIRFMF udostępnia również Latarnię KSeF, która pozwala odczytywać takie zdarzenia programowo, między innymi w kategoriach:

MAINTENANCE
FAILURE
TOTAL_FAILURE

Integracja może więc rozdzielić dwa źródła informacji:

health_check / HTTP
    -> czy konkretna operacja komunikacyjna się udała?

official KSeF event
    -> jaki jest oficjalny kontekst dostępności systemu?

Jeżeli POST do KSeF zakończy się timeoutem, a nie ma oficjalnie ogłoszonej awarii, system nie powinien na tej podstawie sam zmieniać procedure_context na FAILURE.

Organizacja może w takim przypadku zastosować offline24, jeżeli jej proces przewiduje wykorzystanie tej procedury. To jednak inna decyzja niż stwierdzenie, że KSeF znajduje się w oficjalnym trybie awaryjnym.

Integracja z Latarnią jest rekomendacją implementacyjną, nie obowiązkiem ustawowym. Jeżeli system korzysta z oficjalnego źródła zdarzeń programowo, warto zachować także pochodzenie informacji użytej do wyznaczenia procedury i terminu:

procedure_context
procedure_source
procedure_event_id
procedure_started_at
procedure_ended_at
submission_due_at
deadline_rule

Nazwy tych pól są przykładem lokalnego modelu. KSeF nie definiuje takiego kontraktu danych.

Samo submission_due_at również nie powinno być pozbawione kontekstu. Jeżeli system zachowa wyłącznie gotowy timestamp, później trudniej ustalić, według której reguły został obliczony i czy powinien zostać zmieniony po kolejnym oficjalnym zdarzeniu.

Dokument OFFLINE ma lifecycle jeszcze przed wysłaniem do KSeF

W przypadku OFFLINE dokument nie zaczyna istnieć dopiero po skutecznym POST do API. Data wystawienia może wynikać z P_1, zanim faktura otrzyma numer KSeF. Oficjalne przykłady SDK pokazują również scenariusz, w którym XML, jego hash i wymagane kody QR są przygotowywane lokalnie, a dokument jest przechowywany do późniejszej wysyłki.

Przykładowy model:

AXIS A: PROCEDURE

ONLINE
OFFLINE24
MAINTENANCE
FAILURE
TOTAL_FAILURE

Niezależnie od niego:

AXIS B: DOCUMENT

PREPARED
    ↓
ISSUED_LOCAL
    ↓
DELIVERY_READY
    ↓
DELIVERED_OR_CONFIRMED
    ↓
QUEUED_FOR_KSEF
    ↓
SUBMISSION_STARTED
    ↓
KSEF_PROCESSING
    ↓
KSEF_ACCEPTED

Dla odrzuceń mogą pojawić się dalsze stany, ale nie każde odrzucenie powinno automatycznie prowadzić do korekty technicznej:

KSEF_REJECTED
    ↓
technical_correction_eligible?
    ├─ YES -> TECHNICAL_CORRECTION_PENDING
    └─ NO  -> OTHER_RECOVERY_REQUIRED

To model referencyjny CAJVO, nie oficjalna state machine KSeF. Konkretne nazwy stanów zależą od ERP, middleware i podziału odpowiedzialności między systemami.

Istotna jest niezależność obu osi. Faktura może znajdować się lokalnie w DELIVERED_OR_CONFIRMED, a równocześnie podlegać procedurze OFFLINE24. Późniejsze oficjalne zdarzenie może zmienić regułę terminu bez cofania dokumentu do wcześniejszego stanu lifecycle.

Co warto utrwalić przed pierwszym wysłaniem

Lokalny rekord powinien pozwalać odtworzyć zarówno dokument, jak i reguły, według których był obsługiwany.

Przykładowy zakres:

Nie jest to lista pól wymagana przez ustawę. To przykładowy kontrakt danych dla systemu, który ma przetrwać restart, obsłużyć terminy i później uzgodnić lokalny rekord ze stanem KSeF.

Delivery faktury i potwierdzenie transakcji to dwa różne elementy procesu

Status offline nie wystarcza do określenia, co można przekazać nabywcy przed nadaniem numeru KSeF.

Model powinien rozdzielać co najmniej:

invoice_delivery_route:
  KSEF
  OUTSIDE_KSEF

od niezależnej informacji:

transaction_confirmation_issued:
  true / false

Potwierdzenie transakcji nie jest alternatywnym kanałem dostarczenia faktury. Nie jest też fakturą.

Offline24 i niedostępność KSeF

W odpowiednich przypadkach, gdy faktura OFFLINE jest udostępniana poza KSeF przed nadaniem numeru KSeF odbiorcy objętemu regułami art. 106gb ust. 4, wizualizacja dokumentu wymaga właściwych oznaczeń, w tym dwóch kodów:

• KOD I, oznaczony OFFLINE,

• KOD II, oznaczony CERTYFIKAT.

Nie oznacza to, że każda faktura wystawiona w OFFLINE zawsze wymaga dwóch kodów QR.

Dla krajowego podatnika posiadającego NIP, który ma otrzymać fakturę przez KSeF, przed nadaniem numeru KSeF można natomiast wydać potwierdzenie transakcji. Nie należy modelować go jako faktury przekazanej OUTSIDE_KSEF.

Potwierdzenie transakcji samo zawiera dwa kody QR lub odpowiadające im linki służące do weryfikacji i dostępu zgodnie z regułami MF. Nie oznacza się ich jednak napisami OFFLINE i CERTYFIKAT, które dotyczą odpowiednich kodów na wizualizacji faktury OFFLINE.

Stan kodów potwierdzenia transakcji powinien więc być przechowywany oddzielnie od stanu kodów QR właściwych dla faktury.

Tryb awaryjny

W czasie oficjalnej awarii faktura jest udostępniana nabywcy w sposób uzgodniony z nim, zgodnie z regułami właściwymi dla trybu awaryjnego. Sposobu przekazania nie należy sprowadzać do tej samej ścieżki, która obowiązuje przy standardowym odbiorze faktury przez KSeF.

Jeżeli w danym scenariuszu stosowane jest również potwierdzenie transakcji, nadal pozostaje ono osobnym dokumentem, a nie substytutem samej faktury.

Awaria całkowita

Awaria całkowita stanowi jeszcze inny branch. Dokumenty wystawiane w tym okresie funkcjonują poza zwykłym mechanizmem KSeF i nie wymagają kodów QR KSeF.

Dlatego prawidłowy model delivery nie powinien zakładać:

offline = true
-> wygeneruj zawsze dwa QR
-> wyślij zawsze PDF klientowi

Decyzja zależy od procedury, kategorii odbiorcy, sposobu udostępnienia oraz momentu w lifecycle dokumentu.

Certyfikat Offline jest potrzebny do KOD II, nie do uwierzytelnienia w API

KOD II wykorzystuje certyfikat KSeF typu Offline. Certyfikat tego typu pełni inną funkcję niż certyfikat Authentication.

Jeżeli system ma wygenerować KOD II w czasie, gdy nie ma dostępu do KSeF, aktywny certyfikat typu Offline oraz odpowiadający mu klucz prywatny muszą być dostępne wcześniej.

Oficjalne testy E2E klientów C# i Java pokazują taki workflow:

1. certyfikat typu Offline i klucz są dostępne przed rozpoczęciem pracy bez dostępu do KSeF,

2. aplikacja lokalnie przygotowuje XML faktury,

3. zapisuje dokument przeznaczony do późniejszej wysyłki,

4. oblicza hash,

5. generuje wymagane kody QR.

Wniosek dotyczy możliwości lokalnego wygenerowania KOD II. Nie oznacza, że wcześniejsze pozyskanie certyfikatu Offline jest warunkiem każdej operacji wykonywanej w procedurze OFFLINE.

Certyfikat Offline nie zastępuje także mechanizmu uwierzytelnienia w API i nie powinien być traktowany jako certyfikat służący do późniejszego zalogowania się lub wysłania faktury do KSeF.

offlineMode:false nie gwarantuje końcowego trybu Online

Intencja aplikacji podczas wysyłki i rzeczywista klasyfikacja dokumentu w KSeF to dwie różne informacje.

Dokumentacja techniczna przewiduje automatyczne określenie trybu OFFLINE. Faktura przesłana z offlineMode:false może zostać zaklasyfikowana przez KSeF jako OFFLINE, jeżeli kalendarzowa data issueDate, wynikająca z P_1, jest wcześniejsza niż invoicingDate.

Dla sesji interaktywnej invoicingDate odpowiada momentowi przesłania faktury. Dla sesji wsadowej odpowiada momentowi otwarcia sesji.

Przykład dla sesji interaktywnej:

P_1 = 2026-09-28
send = 2026-09-29 00:00:01
offlineMode = false

W takim układzie KSeF może zaklasyfikować dokument jako OFFLINE.

Dlatego lokalny model powinien rozdzielać:

requested_offline_mode
actual_ksef_mode

Pierwsza wartość opisuje żądanie aplikacji. Druga powinna zostać uzgodniona później z rezultatem po stronie KSeF.

Aktualna specyfikacja UPO przewiduje informację TrybWysylki o wartości Online albo Offline.

Bez takiego reconciliation system może utrzymywać lokalnie informację „wysłano online”, mimo że KSeF sklasyfikował dokument inaczej.

Deadline może zmienić się po wystawieniu dokumentu

Termin przesłania nie zawsze można policzyć raz przy wystawieniu i traktować jako niezmienny.

Późniejsze oficjalne zdarzenie KSeF może zmienić dalsze zasady postępowania z dokumentem.

Offline24 przechodzi w oficjalną awarię

Jeżeli faktura została wystawiona w offline24, nie została jeszcze przesłana do KSeF, a przed upływem właściwego terminu zostanie oficjalnie ogłoszona awaria, zastosowanie znajdują reguły przewidziane dla awarii.

Logika:

due_at = next_business_day(issue_date)

nie może być więc jedynym źródłem decyzji do końca lifecycle dokumentu.

Niedostępność przechodzi w awarię

Jeżeli awaria zostanie ogłoszona przed upływem terminu wynikającego z niedostępności, dalsze zasady terminu przechodzą na reguły właściwe dla awarii.

System powinien więc reagować na zmianę oficjalnego kontekstu, a nie wyłącznie czekać na timestamp wyznaczony podczas pierwszej klasyfikacji dokumentu.

Offline24 przechodzi w awarię całkowitą

Jeżeli faktura została wystawiona w offline24, ale nie została jeszcze przesłana do KSeF, a następnie zostanie ogłoszona awaria całkowita obejmująca ten przypadek, obowiązek późniejszego przesłania dokumentu do KSeF odpada.

Nie należy pozostawiać takiej faktury w kolejce jako dokumentu oczekującego bezterminowo na wznowienie API.

Niedostępność przechodzi w awarię całkowitą

Analogiczny problem dotyczy dokumentu wystawionego podczas oficjalnej niedostępności, który nadal oczekuje na przesłanie.

Jeżeli przed jego wysłaniem wystąpi awaria całkowita i zgodnie z właściwymi przepisami dokument zostanie objęty tym scenariuszem, nie jest później dosyłany do KSeF.

Tryb awaryjny przechodzi w awarię całkowitą

Jeżeli awaria całkowita zostanie ogłoszona w trakcie trwającej awarii KSeF, faktury objęte właściwą regułą awarii całkowitej nie przechodzą po jej zakończeniu do zwykłego procesu późniejszego dosłania.

To inna sytuacja niż samo wydłużenie deadline.

Dokumenty wystawiane już podczas awarii całkowitej

Osobną kategorię stanowią faktury wystawiane bezpośrednio w czasie awarii całkowitej.

Mogą mieć postać papierową lub elektroniczną, nie wymagają zachowania struktury FA(3), nie wymagają kodów QR KSeF i nie są później przesyłane do KSeF.

TOTAL_FAILURE nie powinno więc być implementowane jako szczególny typ kolejki retry.

Korekta techniczna nie jest automatycznym skutkiem każdego odrzucenia

Biznesowa faktura korygująca i korekta techniczna odrzuconej faktury OFFLINE są dwoma różnymi procesami.

W przypadku pierwotnej faktury wystawionej w OFFLINE biznesową fakturę korygującą wystawia się po nadaniu fakturze pierwotnej numeru KSeF.

Osobno dokumentacja techniczna przewiduje korektę techniczną dla określonych przypadków odrzucenia faktury OFFLINE z przyczyn technicznych.

Nie należy jednak modelować:

KSEF_REJECTED
-> TECHNICAL_CORRECTION_PENDING

jako automatycznego przejścia.

Najpierw trzeba ustalić, czy dokument kwalifikuje się do tego mechanizmu:

KSEF_REJECTED
    ↓
technical_correction_eligible?

Korekta techniczna:

• dotyczy odrzucenia z przyczyn technicznych objętych tym mechanizmem,

• nie służy do zmiany biznesowej treści faktury,

• nie powinna być używana do poprawiania kwot, pozycji handlowych ani innych zmian wymagających właściwej faktury korygującej,

• nie obejmuje przypadków, w których problem dotyczy braku wymaganych uprawnień podmiotów występujących na fakturze,

• jest przesyłana w sesji interaktywnej.

Model recovery powinien zatem umożliwiać co najmniej dwa wyjścia:

KSEF_REJECTED
    ↓
technical_correction_eligible?
    ├─ YES -> TECHNICAL_CORRECTION_PENDING
    └─ NO  -> OTHER_RECOVERY_REQUIRED

Dopiero w pierwszym przypadku korekta techniczna jest właściwą ścieżką.

Gdzie kończy się główny lifecycle OFFLINE

Po wysłaniu faktury i rozpoczęciu jej przetwarzania przez KSeF problem zmienia charakter.

Do tego momentu integracja musi wiedzieć między innymi:

• w jakiej procedurze znajduje się dokument,

• dlaczego tę procedurę zastosowano,

• z jakiego źródła pochodzi informacja o oficjalnym zdarzeniu,

• jaki termin przesłania obowiązuje,

• czy późniejsze zdarzenie zmieniło pierwotny deadline,

• w jaki sposób faktura została lub ma zostać przekazana nabywcy,

• czy wydano potwierdzenie transakcji,

• jakie kody QR odnoszą się do faktury, a jakie do potwierdzenia,

• jaki dokładnie payload ma zostać przesłany,

• z jakim offlineMode wykonano wysyłkę,

• jaki tryb rzeczywiście przypisał KSeF.

Dalsze statusy przetwarzania, polling, retry po submission i obsługa duplikatów stanowią osobny obszar integracji.

W tym miejscu model OFFLINE powinien przejść do standardowego procesu obsługi statusów KSeF zamiast powielać drugą state machine dla tych samych zdarzeń.

Powiązany materiał CAJVO: „KSeF przyjął fakturę, ale jej nie przetworzył. Jak obsłużyć statusy, retry i duplikaty”.

Rozdzielenie obu obszarów pozwala uniknąć modelu, w którym wartości:

OFFLINE
ERROR
SENT
PROCESSING
FAILURE

trafiają do jednego enumu, mimo że opisują różne właściwości procesu.

Checklista testów przed wdrożeniem OFFLINE na produkcję

Test standardowej ścieżki nie wystarcza. Przed uruchomieniem produkcyjnym warto sprawdzić co najmniej następujące scenariusze:

• offline24 zastosowane bez oficjalnej awarii KSeF,

• rozpoczęcie i zakończenie oficjalnej niedostępności,

• rozpoczęcie i zakończenie oficjalnej awarii,

• timeout lokalnego połączenia bez oficjalnego FAILURE,

• przejście offline24 do oficjalnej awarii przed wysłaniem dokumentu,

• przejście niedostępności do awarii,

• przejście offline24 do awarii całkowitej,

• przejście niedostępności do awarii całkowitej,

• awaria całkowita ogłoszona w trakcie trybu awaryjnego,

• faktura wystawiana bezpośrednio podczas awarii całkowitej,

• restart aplikacji z dokumentami oczekującymi lokalnie na wysyłkę,

• ponowne wyliczenie terminu po zmianie oficjalnego zdarzenia,

• brak dostępnego certyfikatu Offline, gdy potrzebne jest lokalne wygenerowanie KOD II,

• obsługa odbiorcy, któremu faktura jest przekazywana poza KSeF,

• obsługa krajowego nabywcy z NIP otrzymującego fakturę przez KSeF,

• wygenerowanie potwierdzenia transakcji jako dokumentu odrębnego od faktury,

• oddzielna obsługa QR faktury i QR potwierdzenia transakcji,

• wysyłka na granicy dnia i automatyczna klasyfikacja OFFLINE,

• techniczne odrzucenie kwalifikujące się do korekty technicznej,

• odrzucenie, które nie kwalifikuje się do korekty technicznej,

• przesłanie korekty technicznej w sesji interaktywnej,

• próba biznesowej korekty pierwotnej faktury OFFLINE przed nadaniem jej numeru KSeF,

• uzgodnienie numeru KSeF, UPO i rzeczywistego TrybWysylki,

• przekazanie zaakceptowanego dokumentu do standardowego procesu obsługi statusów KSeF.

Model powinien dać się odtworzyć po restarcie systemu

Przy projektowaniu OFFLINE samo pytanie „czy faktura została wysłana?” nie opisuje wystarczająco procesu.

Po restarcie system powinien pozwolić ustalić:

Jaka procedura dotyczy dokumentu?
Dlaczego została zastosowana?
Z jakiego źródła pochodzi ta informacja?
Według jakiej reguły policzono termin?
Czy późniejsze oficjalne zdarzenie zmieniło termin?
Jaki dokładnie dokument został wystawiony?
Co i w jaki sposób otrzymał nabywca?
Czy wydano potwierdzenie transakcji?
Jakie kody QR wygenerowano dla faktury?
Jakie kody wygenerowano dla potwierdzenia?
Czy KOD II można wygenerować z dostępnym certyfikatem Offline?
Jaki tryb zażądała aplikacja podczas wysyłki?
Jaki tryb rzeczywiście przypisał KSeF?
Czy faktura ma już numer KSeF?
Czy odrzucenie kwalifikuje się do korekty technicznej?

Jeżeli odpowiedzi na te pytania zależą od jednego pola offline albo od historii logów HTTP, model miesza informacje należące do różnych warstw procesu.

Rozdzielenie procedure_context, lokalnego lifecycle, delivery i późniejszego reconciliation ze stanem KSeF nie jest wymaganym przez MF schematem bazy danych. Pozwala jednak odwzorować reguły, które działają niezależnie: poszczególne procedury mają różne terminy, oficjalny status systemu ma własne źródło, sposób przekazania dokumentu zależy od odbiorcy i procedury, a rzeczywisty tryb dokumentu może różnić się od flagi wysłanej przez aplikację.