KSeF API tryb offline – wykrywanie w odpowiedziach

KSeF API 2.0 umożliwia wystawianie faktur w trybie offline. Wykrywanie trybu offline w odpowiedziach API jest ważne dla prawidłowej obsługi faktur wystawionych poza systemem KSeF.

Wykrywanie trybu offline w KSeF API

Tryb offline w KSeF pozwala na wystawianie faktur poza systemem KSeF (np. przy niedostępności lub awarii KSeF, albo dobrowolnie w trybie offline24), a przesłanie faktury do KSeF następuje później, w ustawowo określonym terminie.

System KSeF sam wykrywa i oznacza tryb wystawienia faktury w metadanych zwracanych przez API - pole invoicingMode przyjmuje wartość Online lub Offline. Nawet faktura przesłana z parametrem offlineMode: false może zostać automatycznie oznaczona jako offline, jeśli data wystawienia (pole P_1) jest wcześniejsza niż data przyjęcia faktury do przetwarzania (invoicingDate).

Różnice między trybem online a offline dotyczą przede wszystkim momentu przesłania faktury do KSeF i sposobu nadania numeru KSeF: w trybie online numer nadawany jest natychmiast po przyjęciu faktury, a w trybie offline faktura jest wystawiana i udostępniana kontrahentowi wcześniej (z kodami QR), a numer KSeF nadawany jest dopiero po jej późniejszym przesłaniu do systemu.

Instrukcja krok po kroku

1. Sprawdź pole invoicingMode w metadanych

Odpowiedzi API zwracające metadane faktury (np. POST /invoices/query/metadata) zawierają pole invoicingMode, które przyjmuje wartość Online lub Offline. To pole jest wiarygodnym wskaźnikiem trybu wystawienia faktury ustalonym przez system KSeF.

2. Porównaj P_1 (datę wystawienia) z datą przyjęcia faktury

System KSeF ustala tryb automatycznie, porównując datę wystawienia (pole P_1 struktury FA(3)) z datą przyjęcia faktury do przetwarzania (invoicingDate). Jeśli dzień z P_1 jest wcześniejszy niż dzień invoicingDate, faktura zostaje oznaczona jako offline, nawet gdy przesłano ją z parametrem offlineMode: false.

3. Uwzględnij różnicę między sesją interaktywną a wsadową

Dla sesji wsadowej invoicingDate to moment otwarcia sesji (dateCreated z GET /sessions/{referenceNumber}); dla sesji interaktywnej to moment przesłania konkretnej faktury. Ta różnica wpływa na to, kiedy faktura wysłana blisko północy zostanie zakwalifikowana jako offline.

Najczęstsze problemy i rozwiązania

Jak wykryć tryb offline w odpowiedzi?

Sprawdź pole invoicingMode w metadanych faktury zwracanych przez API - przyjmuje ono wartość Online lub Offline i jest ustalane automatycznie przez system KSeF na podstawie porównania daty wystawienia (P_1) z datą przyjęcia faktury do przetwarzania (invoicingDate).

Różnice między online a offline

Faktury online otrzymują numer KSeF natychmiast po przesłaniu i przyjęciu przez system. Faktury offline są wystawiane i udostępniane kontrahentowi wcześniej (z kodami QR umożliwiającymi weryfikację), a numer KSeF nadawany jest dopiero po ich późniejszym przesłaniu do KSeF, w terminie zależnym od konkretnego trybu (offline24, offline z powodu niedostępności systemu, tryb awaryjny).

offlineMode: false, a faktura mimo to oznaczona jako offline

To oczekiwane zachowanie: nawet przy offlineMode: false system KSeF porównuje dzień z pola P_1 (data wystawienia) z dniem invoicingDate (moment przyjęcia faktury - dla sesji wsadowej to otwarcie sesji, dla interaktywnej moment przesłania faktury). Jeśli P_1 przypada na wcześniejszy dzień kalendarzowy, faktura zostaje automatycznie oznaczona jako offline w polu invoicingMode.

Pole P_1 a data wystawienia faktury

P_1 to pole struktury logicznej FA(3) zawierające datę wystawienia faktury - nie jest to samodzielny wskaźnik trybu offline, lecz jeden z dwóch elementów porównania (obok invoicingDate), na podstawie którego system KSeF automatycznie ustala tryb wystawienia w polu invoicingMode.

Pole invoicingMode w metadanych

Metadane faktury zwracane przez API (np. w odpowiedzi POST /invoices/query/metadata) zawierają pole invoicingMode o wartości Online lub Offline. To pole - a nie parametr żądania offlineMode - jest wiarygodnym źródłem informacji o faktycznie ustalonym trybie faktury.

Różnice między trybem online a offline

Faktury online otrzymują numer KSeF natychmiast po przyjęciu przez system. Faktury offline (offline24, offline z powodu niedostępności KSeF lub tryb awaryjny) są wystawiane i udostępniane kontrahentowi wcześniej wraz z kodami QR (KOD I do weryfikacji w KSeF, KOD II potwierdzający tożsamość wystawcy), a numer KSeF nadawany jest dopiero po ich późniejszym przesłaniu do systemu, w terminie zależnym od konkretnego trybu.

FAQ

Jak wykryć tryb offline w odpowiedzi KSeF API?

Sprawdź pole invoicingMode w metadanych faktury (wartość Online lub Offline). System KSeF ustala tę wartość automatycznie, porównując datę wystawienia (pole P_1) z datą przyjęcia faktury do przetwarzania (invoicingDate) - niezależnie od tego, jaki parametr offlineMode ustawiono przy wysyłce.

Czym różni się tryb online od offline?

Faktury online otrzymują numer KSeF natychmiast po przyjęciu przez system. Faktury offline są wystawiane i udostępniane kontrahentowi wcześniej (z kodami QR), a numer KSeF nadawany jest dopiero po ich późniejszym przesłaniu do KSeF, w terminie zależnym od trybu (offline24, offline z powodu niedostępności KSeF lub tryb awaryjny).

Powiązane tematy

Przydatne serwisy

Status i komunikaty

API i narzędzia

Pierwsza grupa – status systemu KSeF i komunikaty techniczne Ministerstwa Finansów, druga – narzędzia do integracji z KSeF i walidacji faktur.