[Fakturownia - Baza wiedzy](https://pomoc.fakturownia.pl.md) / [Pytania i odpowiedzi](https://pomoc.fakturownia.pl/pytania-i-odpowiedzi.md)

# [Integracja z KSeF – tryby pracy, statusy i obsługa błędów przez API](https://pomoc.fakturownia.pl/integracja-z-ksef-tryby-pracy-statusy-i-obsluga-bledow-przez-api.md)

## 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](https://github.com/fakturownia/API/blob/master/KSeF.md)

Szczegółowy opis trybów offline/offline24:
👉 [Tryby offline – dokumentacja](https://github.com/fakturownia/API/blob/master/KSeF.md#tryby-offline-awaryjny-niedost%C4%99pno%C5%9B%C4%87-offline24)

---

### 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](https://pomoc.fakturownia.pl/148038-Jak-udzielic-dostepu-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.

---

### Przydatne linki

- 📄 [Dokumentacja API KSeF – Fakturownia](https://github.com/fakturownia/API/blob/master/KSeF.md)
- 📄 [Struktura logiczna FA(3) – KSeF](https://ksef.podatki.gov.pl/informacje-ogolne-ksef-20/struktura-logiczna-fa-3/)
- 📄 [Informacje o integracji z KSeF – Fakturownia](https://fakturownia.pl/ksef)
- 📄 [Jak udzielić dostępu Pomocy Technicznej](https://pomoc.fakturownia.pl/148038-Jak-udzielic-dostepu-Pomocy-Technicznej-)