W integracji z KSeF nie należy automatycznie ponawiać każdego nieudanego żądania. Najpierw trzeba ustalić, czy problem dotyczy danych, uprawnień, stanu operacji, ograniczenia API czy przejściowej niedostępności.
Błąd danych, uprawnień lub nieprawidłowego stanu wymaga usunięcia przyczyny, a nie zwykłego retry.
Po timeoutcie lub braku odpowiedzi należy najpierw ustalić stan operacji albo dokumentu.
Operacje asynchroniczne wymagają kontrolowanego odpytywania statusu i obsługi retencji.
Awaria lub tryb offline to odrębna ścieżka od zwykłego błędu technicznego.
Najtrudniejszy przypadek nie zawsze polega na otrzymaniu jednoznacznego błędu. Czasem integracja traci odpowiedź i nie wie, czy KSeF wykonał operację. Wtedy mechaniczne ponowienie może być niewłaściwe: najpierw potrzebna jest klasyfikacja problemu, a przy wyniku nierozstrzygniętym także weryfikacja stanu.
Dobrze zaprojektowana integracja oprogramowania z KSeF powinna zatem rozdzielać korektę danych, odnowienie autoryzacji, sprawdzanie statusu, kontrolowane ponowienie i obsługę ręczną. Szczegółowe reguły zawsze trzeba odnosić do aktualnej wersji API oraz konkretnego endpointu.
Zacznij od klasyfikacji błędu, nie od ponowienia żądania
Obsługa błędów w oficjalnym API KSeF 2.0 powinna rozróżniać błędy danych lub walidacji, uwierzytelnienia i uprawnień, stanu sesji lub operacji, a także problemy techniczne i ograniczenia częstotliwości.[1][2][3][5] Dokładna lista kategorii i kodów zależy jednak od endpointu oraz aktualnej wersji API.
Błąd trwały to w tym kontekście problem wymagający zmiany danych, konfiguracji, uprawnień albo stanu procesu. Błąd przejściowy może ustąpić bez takiej korekty. Tego podziału nie należy wyprowadzać wyłącznie z grupy kodów HTTP: znaczenie odpowiedzi trzeba sprawdzić w kontrakcie używanego endpointu.
Sygnał lub kategoria
Co sprawdzić
Następne działanie
Czego nie zakładać
Błąd danych lub walidacji
Treść odpowiedzi i dane dokumentu
Poprawić przyczynę przed kolejną próbą
Że identyczne żądanie zadziała po odczekaniu
Błąd uwierzytelnienia lub uprawnień
Stan uwierzytelnienia, uprawnienia i wymagania endpointu
Usunąć problem z dostępem, następnie ponownie ocenić żądanie
Że jest to przejściowy problem transportowy
Nieprawidłowy stan sesji lub operacji
Status procesu i dozwolone przejścia stanu
Ustalić właściwy stan przed kolejnym działaniem
Że ponowienie zmieni stan na poprawny
Ograniczenie częstotliwości
Aktualny kontrakt endpointu i odpowiedź API
Zastosować kontrolowaną politykę ponowień zgodną z kontraktem
Że wszystkie endpointy mają ten sam limit
Timeout lub brak odpowiedzi
Czy można ustalić status operacji albo dokumentu
Najpierw zweryfikować wynik
Że operacja nie została wykonana
Status operacji w toku
Numer referencyjny i zasady odpytywania
Kontynuować kontrolowany polling
Że oczekiwanie oznacza błąd
Niedostępność systemu
Źródło problemu i oficjalne komunikaty
Rozdzielić retry od procedury offline
Że każdy timeout oznacza formalną awarię
Błędy, których nie powinno załatwiać automatyczne retry
Automatyczne ponowienie należy ograniczyć do błędów zaklasyfikowanych jako przejściowe albo sytuacji, w których wynik operacji pozostaje nierozstrzygnięty. Błędy walidacji, uprawnień i nieprawidłowego stanu wymagają najpierw usunięcia przyczyny. Oficjalna dokumentacja nie definiuje przy tym jednej uniwersalnej macierzy retry dla wszystkich endpointów.[1][2][3]
Wybrane odpowiedzi KSeF, w tym 400 i 429, mogą korzystać z opcjonalnego formatu Problem Details uruchamianego nagłówkiem X-Error-Format: problem-details.[1][3] Nie oznacza to, że każda odpowiedź i każdy endpoint zawsze zwracają taki format. Według changelogu starszy format application/json pozostaje wspierany.
Odpowiedź 429 należy traktować jako sygnał ograniczenia częstotliwości zgodnie z bieżącym kontraktem API. Sama nie uzasadnia przyjęcia jednego limitu ani jednej polityki ponowień dla całego KSeF.
Timeout i brak odpowiedzi: najpierw ustal wynik wysyłki
Timeout informuje o tym, że klient nie otrzymał odpowiedzi w oczekiwanym czasie. Nie przesądza natomiast, czy operacja po stronie KSeF rozpoczęła się lub zakończyła. Jeżeli wynik wysyłki pozostaje niepewny, przed jej ponowieniem należy ustalić status operacji albo dokumentu, o ile API udostępnia taką możliwość.[1][7][9]
Jest to zalecenie architektoniczne dla operacji wywołujących skutek biznesowy. Dokumentacja nie opisuje jednej uniwersalnej gwarancji idempotencji dla wszystkich operacji KSeF, dlatego nie można zakładać, że ponowienie każdego identycznego żądania będzie obojętne.
Zapisz kontekst wywołania. Utrwal lokalny identyfikator wysyłki, czas żądania, identyfikator zwrócony przez API oraz otrzymaną odpowiedź lub informację o jej braku.
Rozstrzygnij, czy wynik jest znany. Jednoznaczne odrzucenie wymaga innej reakcji niż timeout albo zerwane połączenie.
Sprawdź dostępny status. Jeśli dany proces pozwala odczytać stan operacji lub dokumentu, wykonaj tę weryfikację przed ponowną wysyłką.
Wybierz działanie na podstawie wyniku. Może to być zakończenie procesu, korekta przyczyny, kontrolowane ponowienie albo skierowanie przypadku do ręcznej analizy.
Zachowaj decyzję w rejestrze. Powiąż kolejną próbę z pierwotnym wywołaniem, aby nie utracić historii procesu.
Co zapisać przy każdym żądaniu powodującym skutek biznesowy
Minimalny zapis operacyjny powinien pozwalać odtworzyć, jaki dokument wysyłano, kiedy rozpoczęto próbę, jaki identyfikator nadał procesowi system oraz jaki stan ostatnio potwierdzono. Nie zastępuje to statusu KSeF, ale pozwala rozdzielić pierwszą wysyłkę, ponowienie i ręczną interwencję.
Kiedy wynik pozostaje nierozstrzygnięty
Wynik jest nierozstrzygnięty wtedy, gdy klient nie ma wiarygodnego potwierdzenia sukcesu ani jednoznacznego odrzucenia. Taki przypadek powinien mieć osobny stan lokalny. Nie należy automatycznie utożsamiać go z błędem trwałym ani z operacją, która na pewno się nie wykonała.
Praktyczna różnica jest istotna: po jednoznacznym błędzie danych poprawia się przyczynę, natomiast po utracie odpowiedzi najpierw szuka się potwierdzenia wyniku. Dopiero brak możliwości rozstrzygnięcia uruchamia kontrolowaną ścieżkę dalszej obsługi.
Jak obsłużyć status operacji asynchronicznej
Opisane operacje asynchroniczne KSeF mogą wymagać cyklicznego sprawdzania statusu za pomocą numeru referencyjnego. Status oczekiwania nie musi oznaczać błędu: może wskazywać, że przetwarzanie nadal trwa.[2][8]
Polling, czyli cykliczne odpytywanie statusu, powinien mieć jednoznaczne warunki zakończenia. Proces kończy się po otrzymaniu stanu końcowego albo po osiągnięciu własnego kontrolowanego timeoutu. Częstotliwość odpytywania, nazwy statusów i okres ich dostępności trzeba ustalić na podstawie dokumentacji konkretnego endpointu.
ReferenceNumber to nie numer KSeF faktury
referenceNumber identyfikuje opisaną operację asynchroniczną i umożliwia pobieranie jej statusu. Nie jest to numer KSeF nadawany fakturze. Pomylenie tych identyfikatorów utrudnia diagnozę i może prowadzić do sprawdzania niewłaściwego zasobu.
Numer referencyjny oraz ostatni znany status powinny trafić do trwałego rejestru. Dzięki temu odpytywanie można wznowić po restarcie procesu bez tworzenia nowej operacji wyłącznie dlatego, że aplikacja utraciła stan lokalny.
Stan końcowy, własny timeout i 410 Gone
Statusy techniczne i odpowiedzi niektórych operacji asynchronicznych podlegają retencji. Po jej upływie odpytywanie może zwrócić 410 Gone.[1] Okresy retencji różnią się między operacjami, a statusy sesji i wysyłki faktur mają odrębne zasady.
Odpowiedź 410 Gone nie dowodzi sama w sobie, że operacja biznesowa zakończyła się niepowodzeniem. Oznacza, że danego statusu nie można już odczytać w ten sposób. Lokalny model procesu powinien więc przewidywać co najmniej stany: oczekiwanie, sukces, błąd oraz przypadek wymagający weryfikacji po utracie dostępności statusu.
Błąd w sesji wsadowej nie musi oznaczać błędu całej paczki
W sesji wsadowej błędy mogą dotyczyć konkretnych plików XML, a nie całej paczki.[7] Wynik trzeba zatem analizować na poziomie dokumentu. Szczegółowy sposób odczytania odrzuconych plików zależy od dokumentacji właściwej sesji i endpointu.
Mapowanie wyniku na konkretny dokument
Każdy plik powinien zachować powiązanie z lokalnym identyfikatorem dokumentu i wynikiem przetwarzania. Takie mapowanie pozwala oddzielić dokumenty przyjęte, odrzucone i nadal wymagające weryfikacji, bez przypisywania jednego stanu całej paczce.
Sesja wsadowa
Wymaga rozpatrywania wyników dla konkretnych plików XML oraz ustalenia, których dokumentów dotyczy problem.
Sesja interaktywna
Jest odrębnym trybem. Nie należy przenosić do niej nazw statusów ani reguł obsługi sesji wsadowej bez sprawdzenia dokumentacji odpowiednich endpointów.
Dlaczego nie należy od razu wysyłać ponownie całej paczki
Ponowienie całej paczki bez analizy wyniku pomija możliwość, że tylko część dokumentów wymaga korekty. Bezpieczniejsza procedura polega na ustaleniu stanu każdego pliku, poprawieniu dokumentów odrzuconych i ponowieniu wyłącznie tych operacji, dla których jest to uzasadnione.
Niedostępność KSeF a retry i tryb offline
Błąd techniczny nie potwierdza formalnej awarii KSeF. Niedostępność systemu i formalnie ogłoszona awaria mogą uruchamiać tryby offline oraz odrębne terminy przesłania dokumentów, dlatego przed zastosowaniem takiej procedury trzeba sprawdzić komunikaty systemu.[6]
Skutki prawne i terminy zależą od rodzaju trybu, aktualnych przepisów oraz komunikatów Ministerstwa Finansów. Lokalnego timeoutu lub problemu z siecią nie należy więc samodzielnie traktować jako potwierdzenia formalnej awarii.
Lokalny problem komunikacyjny
Wymaga diagnozy połączenia i ustalenia wyniku operacji. Sam nie uruchamia automatycznie procedury offline.
Przejściowy problem API
Może uzasadniać kontrolowane ponowienie, jeżeli klasyfikacja konkretnej odpowiedzi i kontrakt endpointu na to pozwalają.
Potwierdzona niedostępność lub właściwy tryb offline
Wymaga zastosowania procedury odpowiedniej dla aktualnego komunikatu KSeF, a nie zwykłej reguły retry.
Monitoring powinien rozdzielać te zdarzenia. Dzięki temu zespół widzi, czy problem dotyczy pojedynczego klienta, odpowiedzi API, nierozstrzygniętego wyniku czy oficjalnie potwierdzonej niedostępności systemu.
Co weryfikować przy zmianie API i przed wdrożeniem
Kontrakt API KSeF 2.0 jest zmieniany, a dokumentacja wskazuje terminy wdrażania zmian osobno dla środowisk TEST, DEMO i PROD.[1][4][9] Informację tę trzeba ponownie sprawdzać przed wdrożeniem, ponieważ dokumentacja i daty wdrożeń są zmienne.
Polityka retry powinna być wersjonowana razem z obsługiwanym kontraktem. Changelog pomaga wykrywać zmiany, ale nie zastępuje dokumentacji konkretnego endpointu. Nie istnieje jedna niezmienna tabela kodów i reakcji właściwa dla całego API.
Lista testów dla obsługi błędów i ponowień
Porównać używaną wersję OpenAPI z aktualnym changelogiem.
Sprawdzić, czy zmiana została wdrożona na właściwym środowisku: TEST, DEMO lub PROD.
Zweryfikować format odpowiedzi błędów, w tym dostępność opcjonalnego Problem Details dla danego przypadku.
Przetestować błędy danych, uwierzytelnienia, uprawnień i nieprawidłowego stanu operacji.
Przetestować ograniczenie częstotliwości zgodnie z aktualnym kontraktem endpointu, bez zakładania wspólnego limitu dla całego API.
Sprawdzić zachowanie aplikacji po timeoutcie i utracie odpowiedzi.
Przetestować polling, własny timeout oraz przypadek, w którym status nie jest już dostępny po retencji.
Potwierdzić, że sesja wsadowa zachowuje mapowanie wyniku na konkretny dokument.
Zweryfikować moment przekazania przypadku z automatyzacji do ręcznej obsługi.
Test zakończony sukcesem nie wystarcza do oceny polityki retry. Istotne są także stany graniczne: brak odpowiedzi, operacja pozostająca w toku, utrata dostępności statusu i częściowe odrzucenie dokumentów. Dopiero ich kontrolowana obsługa pokazuje, czy integracja podejmuje dalsze działanie na podstawie rozpoznanego stanu, a nie samego faktu wystąpienia błędu.
