Tryb OFFLINE24 w KSeF - statusy i zachowanie API
Wpis dotyczy integracji z KSeF przez API Fakturowni. Opisuje zachowanie pola gov_status w trybie OFFLINE24 oraz kwestię bezpieczeństwa ponownej wysyłki.
Status gov_status w trybie OFFLINE24
Gdy faktura zostaje wystawiona w trybie OFFLINE24 (np. z powodu przeciążenia KSeF), API zwraca status offline - jest to osobny status, niezależny od processing.
Oznacza to, że odpytując cyklicznie pole gov_status po wywołaniu wysyłki do KSeF, można jednoznacznie odróżnić:
- processing - faktura jest aktywnie przetwarzana przez KSeF w trybie standardowym
- offline - faktura oczekuje na rejestrację w trybie OFFLINE24
Jak rozpoznać tryb OFFLINE24 przez API
Sam status offline jednoznacznie sygnalizuje, że faktura trafiła do trybu OFFLINE24. Nie ma potrzeby sprawdzania dodatkowych pól - jeśli gov_status ma wartość offline, wiadomo, że faktura nie utknęła z powodu błędu, lecz czeka na przetworzenie przez KSeF w ramach procedury offline.
Po przetworzeniu faktury przez KSeF status zostanie zaktualizowany i pojawi się informacja o wyniku rejestracji.
Czy faktura w trybie OFFLINE24 może otrzymać błąd?
Tryb OFFLINE24 nie gwarantuje sukcesu. Faktura może ostatecznie otrzymać status offline_error, jeśli KSeF ją odrzuci. Może się to zdarzyć między innymi w przypadku gdy:
- wewnętrzne ID użyte w fakturze nie istnieje w KSeF
- w KSeF znajduje się już faktura o tym samym numerze (wystawiona poza Fakturowniią)
Jeśli faktura otrzyma status offline_error, należy skontaktować się z helpdeskiem Fakturowni - każdy taki przypadek wymaga indywidualnej weryfikacji.
Bezpieczeństwo ponownej wysyłki (send_to_ksef=1)
Ponowne wywołanie wysyłki na tej samej fakturze (np. po statusie server_error) jest bezpieczne. Fakturownia posiada własne zabezpieczenia po swojej stronie, które blokują ponowną wysyłkę tego samego dokumentu.
Dodatkowym zabezpieczeniem jest sam KSeF - system rządowy nie przyjmie faktury z tym samym numerem w polu P_2, co chroni przed duplikacją również po stronie zewnętrznej.