Faktury Offline w KSeF: Praktyczny przewodnik dla deweloperów

Faktury offline w Krajowym Systemie e-Faktur (KSeF) to faktury ustrukturyzowane, które mogą być wystawiane i przekazywane nabywcy bez natychmiastowego przesyłania ich do centralnego systemu. Rozwiązanie to zostało zaprojektowane w celu zapewnienia ciągłości fakturowania w sytuacjach, gdy dostęp do KSeF jest niemożliwy lub utrudniony, na przykład podczas planowanych prac serwisowych systemu (tryb offline z powodu niedostępności) lub z powodu problemów z połączeniem internetowym po stronie podatnika (tryb offline24). Faktury takie muszą być zgodne z obowiązującą strukturą logiczną (schematem XSD) i oznaczone specjalnymi kodami QR, a następnie przesłane do KSeF w określonym terminie, aby zostały w pełni uznane w obrocie prawnym.

Awaria, brak internetu, a klient czeka na fakturę. Co teraz?

Wyobraź sobie scenariusz: Twoja aplikacja działa w restauracji. Jest sobota, środek lunchu, a KSeF ogłasza przerwę techniczną. Albo gorzej – w biurze klienta pada internet. Kolejka rośnie, a Ty dostajesz gorący telefon: „Nasza aplikacja nie wystawia faktur! Co mamy robić?”. Brzmi znajomo? To właśnie problem, który rozwiązują tryby offline w KSeF.

Od 1 lutego 2026 roku, kiedy KSeF stanie się obowiązkowy dla większości firm, nie będziesz mógł po prostu powiedzieć „proszę poczekać, aż system wstanie”. Twoja aplikacja musi być na to gotowa. Ministerstwo Finansów przewidziało dwie ścieżki awaryjne, które każdy deweloper powinien zaimplementować: tryb offline z powodu niedostępności KSeF oraz tryb offline24.

Dwa tryby offline – diabeł tkwi w szczegółach

Choć nazwy brzmią podobnie, te dwa tryby służą do czegoś innego i mają różne zasady. Zrozumienie ich jest kluczowe, aby Twoja integracja była niezawodna.

Jak widać, tryb offline24 to Twoja codzienna siatka bezpieczeństwa. To elastyczne narzędzie, które pozwala Twojej aplikacji działać autonomicznie i wysłać fakturę do KSeF później. Z kolei tryb offline z powodu niedostępności to plan B na wypadek, gdyby sam KSeF miał problemy.

Wymagania techniczne: Kody QR i Certyfikaty – czyli co musisz zaimplementować

Niezależnie od trybu, faktura wystawiona offline musi spełniać określone wymogi techniczne, aby była ważna. Najważniejsze z nich to:

1. Struktura logiczna FA(3): Faktura musi być wygenerowana jako plik XML zgodny z najnowszą strukturą logiczną (od 1 lutego 2026 będzie to FA(3)). Twoja aplikacja musi być w stanie tworzyć takie pliki lokalnie.

2. Dwa kody QR: Jeśli faktura jest przekazywana nabywcy poza KSeF (np. mailem jako PDF), musi zawierać dwa kody QR:

   • Kod QR „OFFLINE”: Pozwala na weryfikację danych i późniejszy dostęp do faktury w KSeF.
   • Kod QR „CERTYFIKAT”: Potwierdza tożsamość wystawcy. Do jego wygenerowania niezbędny jest certyfikat KSeF typu 2, który podatnicy będą mogli pobrać od 1 listopada 2025 roku.

To oznacza, że Twoja aplikacja musi nie tylko generować XML, ale także tworzyć i osadzać te dwa kody QR na wizualizacji faktury. To kluczowy element, który zapewnia autentyczność dokumentu w okresie, gdy nie ma go jeszcze w centralnym systemie.

Jak to ogarnąć? Praktyczne wskazówki dla deweloperów

Integracja z KSeF, a zwłaszcza obsługa trybów awaryjnych, to wyzwanie. Dokumentacja bywa niejasna, a środowisko testowe nie zawsze działa stabilnie. Zamiast budować wszystko od zera, warto rozważyć gotowe rozwiązania, które biorą na siebie ciężar komunikacji z KSeF.

Jeśli Twoja aplikacja nie ma jeszcze wbudowanej obsługi KSeF, masz kilka opcji:

1. Skorzystaj z bsxPrinter: To serwer wydruku, który działa jako pośrednik między Twoją aplikacją a KSeF. Wystarczy, że przekażesz mu dane faktury, a on zajmie się resztą: wygeneruje poprawny XML, obsłuży tryby offline, wygeneruje kody QR i wyśle fakturę do KSeF we właściwym terminie. Dzięki temu oszczędzasz setki godzin na implementacji i testowaniu.

2. Użyj gotowej bramki API: Na rynku dostępne są komercyjne bramki, takie jak https://www.integracja-ksef.pl/ czy https://bramka-ksef.pl/. Działają na podobnej zasadzie co bsxPrinter, oferując REST API do komunikacji z KSeF. To dobre rozwiązanie, jeśli chcesz zlecić obsługę KSeF na zewnątrz.

Nie czekaj na ostatnią chwilę

Tryby offline to nie dodatek, a fundament stabilnego działania każdej aplikacji fakturowej w nowej rzeczywistości prawnej. Zapewnienie ciągłości sprzedaży w każdych warunkach to wartość, której oczekują Twoi klienci. Zamiast wyważać otwarte drzwi, postaw na sprawdzone narzędzia i skup się na rozwoju swojej aplikacji.

Masz pytania o integrację z KSeF lub chcesz zobaczyć, jak bsxPrinter może uprościć Ci pracę? Skontaktuj się z nami – chętnie podzielimy się naszą wiedzą.

FAQ – Najczęściej zadawane pytania

Źródła: