Wprowadzenie
Bezmyślne ponowienie żądania KSeF po timeoutcie może utworzyć duplikat faktury, bo żądanie mogło dotrzeć do KSeF, choć Ty nigdy nie zobaczyłeś odpowiedzi. Bezpieczny wzorzec to stały klucz idempotencji po Twojej stronie przy każdym zgłoszeniu, sprawdzenie statusu faktury w KSeF przed ponowną wysyłką i ponowne wysłanie tylko wtedy, gdy masz pewność, że wcześniejsza próba się nie powiodła.
Dlaczego timeout jest niebezpieczny
KSeF to krajowa platforma e-fakturowania prowadzona przez Ministerstwo Finansów. Gdy wysyłasz fakturę FA(3) przez sieć, timeout jest niejednoznaczny: żądanie mogło nie dotrzeć do KSeF albo zostało przyjęte, a zgubiła się tylko odpowiedź. Jeśli założysz najgorsze i wyślesz ten sam dokument jeszcze raz, możesz skończyć z dwiema fakturami ustrukturyzowanymi dla jednej transakcji.
Wzorzec klucza idempotencji
Rozwiązaniem jest uczynienie każdego zgłoszenia rozpoznawalnym. Dołącz po swojej stronie stały klucz idempotencji — unikalną wartość wyprowadzoną z Twojego własnego identyfikatora faktury, zapisaną we własnym rejestrze żądań. API KSeF nie przyjmuje natywnego parametru klucza idempotencji; to księgowość po stronie klienta, która czyni każdą próbę rozpoznawalną jako ten sam logiczny dokument, a nie nowy. Generujesz go raz na fakturę i używasz ponownie przy każdej próbie wysyłki tej faktury.
Sprawdź status, zanim wyślesz ponownie
Zanim cokolwiek wyślesz ponownie, zapytaj KSeF o bieżący status faktury. Jeśli wcześniejsza próba faktycznie dotarła, status to pokaże — wtedy zamiast ponownej wysyłki odczytaj wynik (numer KSeF i UPO). Dopiero gdy potwierdzisz, że żadna wcześniejsza próba się nie powiodła, wyślij świeże zgłoszenie z tym samym kluczem idempotencji.
Backoff zamiast młotka
Gdy KSeF lub Twoje połączenie jest niedostępne, ponawiaj z backoffem — opóźnieniem rosnącym z każdą próbą — zamiast strzelać żądaniami w ciasnej pętli. Daje to platformie czas na powrót do zdrowia i nie dokłada obciążenia usłudze, która już ledwo zipie. Timeout to sygnał, żeby zwolnić i zweryfikować, a nie wysyłać natychmiast ponownie.
Jak to robi Notaly
Notaly prowadzi każdą fakturę przez jej cykl życia i oznacza ją jako wysłaną dopiero, gdy KSeF potwierdzi odbiór, więc ten sam dokument nie idzie dwa razy. Wynik końcowy — akceptacja z numerem KSeF i UPO albo odrzucenie z kodem błędu — trafia do Ciebie podpisanym webhookiem, a nie wymaga pollingu. To zdejmuje z Twojej integracji całą niejednoznaczność ponowień.
FAQ
Czy żądanie KSeF po timeoutcie mogło już utworzyć fakturę? Tak. Timeout znaczy tylko, że nie odebrałeś odpowiedzi; żądanie mogło dotrzeć do KSeF. Sprawdź status przed ponowną wysyłką.
Co to jest klucz idempotencji? Stały identyfikator dołączany po Twojej stronie do każdego zgłoszenia, dzięki któremu ten sam dokument nie zostanie wysłany dwa razy przez pomyłkę.
Zastrzeżenie
Notaly nie jest doradcą podatkowym, księgowym ani prawnym. Ten artykuł ma charakter informacyjny, nie stanowi porady podatkowej i może być nieaktualny. Ponosisz odpowiedzialność za własne rozliczenia VAT; w razie potrzeby skonsultuj się z wykwalifikowanym księgowym.
Źródła
Źródło: api-test.ksef.mf.gov.pl