Integracja z KSeF – tryby pracy, statusy i obsługa błędów przez API

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:

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_error nie 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:

1. Ręcznie w Fakturowni – po ustąpieniu awarii kliknij przycisk „Wyślij do KSeF” przy danej fakturze.
2. 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.

Dlaczego żądanie, które przechodzi na KSeF DEMO, na produkcji kończy się błędem 422?

Konto połączone z KSeF DEMO celowo nie odtwarza wszystkich zabezpieczeń produkcyjnych – dokumenty wysłane do DEMO nie mają skutków prawnych. Dlatego żądanie, które przechodzi na DEMO, może zostać odrzucone na produkcji.

Najczęstszy przypadek to faktura końcowa wystawiona zaraz po zaliczce. KSeF nadaje numer asynchronicznie, więc odpowiedź na utworzenie zaliczki nie oznacza, że zaliczka ma już numer KSeF. Faktura końcowa musi podać numery KSeF swoich zaliczek, dlatego przy produkcyjnym KSeF żądanie POST /invoices.json z fakturą końcową zwróci błąd 422: „Nie można wystawić faktury końcowej — powiązane faktury zaliczkowe (…) nie posiadają jeszcze numeru KSeF. Poczekaj, aż zostaną przetworzone.” Tak samo działa wystawienie korekty do dokumentu bez numeru KSeF.

Zalecana obsługa:

1. Po wystawieniu zaliczki poczekaj, aż otrzyma numer KSeF: pole gov_id jest wypełnione, a gov_status ma wartość ok. Informację dostaniesz webhookiem invoice:update albo odpytując GET /invoices/{ID}.json.
2. Dopiero wtedy wystaw fakturę końcową.
3. Jeśli mimo to otrzymasz 422, sprawdź gov_status zaliczki:
   • processing – odczekaj kilka sekund i powtórz żądanie,
   • pusty – zaliczka nie została wysłana do KSeF; wyślij ją (GET /invoices/{ID}.json?send_to_ksef=yes), a końcową wystaw po nadaniu numeru,
   • status błędu (np. send_error) – popraw zaliczkę i wyślij ją ponownie.

Inne operacje, które na produkcji kończą się błędem 422, a na DEMO przechodzą: edycja i usunięcie faktury od chwili zlecenia jej wysyłki do KSeF oraz pobranie PDF przed nadaniem numeru KSeF. Z kolei wysyłka e-mailem przez API zwraca "status":"ok", ale wiadomość wychodzi dopiero po nadaniu numeru KSeF – nie ponawiaj wtedy wywołania, bo klient dostanie fakturę kilka razy.

Nie ma trybu, który włącza blokady produkcyjne na koncie DEMO. To samo ustawienie konta decyduje o blokadach i o tym, dokąd trafiają faktury, więc konto z blokadami produkcyjnymi wysyła faktury do prawdziwego KSeF.

Przydatne linki

• 📄 Dokumentacja API KSeF – Fakturownia
• 📄 Struktura logiczna FA(3) – KSeF
• 📄 Informacje o integracji z KSeF – Fakturownia
• 📄 Jak udzielić dostępu Pomocy Technicznej