FAQ: Integracja z KSeF – tryby pracy, statusy i obsługa błędów przez API
Opis problemu
Podczas budowania integracji z Fakturownią przez API pojawiają się pytania dotyczące:
- jak rozróżnić tryby pracy KSeF (online / offline / offline24),
- skąd wiedzieć, że faktura została wystawiona w trybie awaryjnym,
- jak symulować awarię KSeF w środowisku demo,
- jak procedować z fakturą po wystąpieniu błędu ‘server_error’ lub ‘demo_server_error’,
- jak działa retry i webhooki w kontekście błędów wysyłki do KSeF.
Tryby pracy KSeF – różnice i sposób rozpoznania
Fakturownia obsługuje trzy tryby wysyłki dokumentów do KSeF:
| Tryb | Kiedy jest stosowany |
|---|---|
| online | Standardowa wysyłka – KSeF dostępny, faktura wysłana i zaksięgowana na bieżąco |
| offline | Serwis latarni KSeF zwróci informację o niedostępności systemu KSeF |
| offline24 | Wykryty wydłużony czas przetwarzania faktur w KSeF lub włączona wysyłka masowa z odpowiednimi ustawieniami; faktura wysłana w innym dniu niż data jej wystawienia jest przez KSeF traktowana jako offline24; faktura zawierająca przed wysyłką 2 kody QR |
Jak sprawdzić tryb wysyłki przez API?
Aktualny tryb wysyłki dostępny jest w szczegółach wysyłki do KSeF. W odpowiedzi API należy sprawdzić pole:
gov_send_mode
Pole przyjmuje wartości: ‘online’, ‘offline’, ‘offline24’.
Pełna dokumentacja API dotycząca KSeF dostępna jest tutaj:
👉 https://github.com/fakturownia/API/blob/master/KSeF.md
Szczegółowy opis trybów offline/offline24:
👉 Tryby offline – dokumentacja
Co oznacza błąd ‘server_error’ / ‘demo_server_error’?
Błąd ‘server_error’ nie jest równoznaczny z awarią KSeF. Oznacza inne problemy z połączeniem, np. przekroczenie limitu połączeń po stronie KSeF.
- Faktura może zostać utworzona w Fakturowni, ale nie zostać przekazana do KSeF.
- W takiej sytuacji w szczegółach faktury pojawi się informacja o błędzie (np. przekroczony limit połączeń).
- Tryb
server_errornie uruchamia automatycznie trybu offline – jest to odrębna kategoria błędu.
W razie wątpliwości dotyczących konkretnego błędu server_error należy skontaktować się z pomocą techniczną Fakturowni, podając numer dokumentu oraz udzielając dostępu technicznego:
👉 Jak udzielić dostępu Pomocy Technicznej
Co zrobić z fakturą wystawioną w trybie offline?
Zgodnie z dokumentacją KSeF, fakturę wystawioną w trybie offline należy dosłać do KSeF po ustąpieniu awarii.
Dostępne sposoby:
- Ręcznie w Fakturowni – po ustąpieniu awarii kliknij przycisk „Wyślij do KSeF” przy danej fakturze.
- Przez API – możliwe jest zlecenie wysyłki dokumentu do KSeF bezpośrednio przez API (endpoint opisany w dokumentacji KSeF dla Fakturowni).
Jak symulować awarię KSeF w środowisku demo?
Symulację trybu offline w integracji demo można wywołać zgodnie z informacjami zawartymi w dokumentacji API Fakturowni dotyczącej KSeF.
⚠️ Uwaga: Środowisko demo Fakturowni nie generuje kodów QR – jest to zachowanie celowe dla trybu testowego.
Jeśli dokumentacja w tym zakresie jest dla Ciebie niewystarczająca lub niejasna, zalecamy kontakt bezpośredni z pomocą techniczną Fakturowni w celu uzyskania szczegółowych instrukcji testowania scenariuszy awaryjnych.
Webhooki a błędy wysyłki do KSeF
Aktualnie webhooki w Fakturowni są wysyłane wyłącznie przy aktualizacji faktury (np. nadaniu numeru KSeF). Błąd wysyłki do KSeF nie aktualizuje faktury, dlatego webhook nie zostanie wysłany w przypadku wystąpienia błędu.
Konsekwencja praktyczna:
Integrator nie otrzyma automatycznego powiadomienia o błędach wysyłki do KSeF przez webhooki – konieczne jest aktywne sprawdzanie statusu wysyłki przez API (polling) lub regularne monitorowanie szczegółów faktur.
💡 Rekomendacja: Wdrożenie mechanizmu odpytywania API o status wysyłki (
gov_send_mode, status KSeF) dla faktur w stanach innych niżonline/ z nadanym numerem KSeF, aby wykrywać błędy bez konieczności ręcznego przeglądania systemu.