Czego nie mówi dostawca KSeF i dlaczego retry powinno być standardem

KSeF w teorii wygląda prosto. System wystawia fakturę, wysyła ją do KSeF, odbiera numer i zapisuje potwierdzenie. Kilka kroków, logiczny proces, wszystko wydaje się przewidywalne.

W praktyce integracja z KSeF nie kończy się na samym wysłaniu dokumentu. Prawdziwe wyzwanie zaczyna się wtedy, gdy zewnętrzna usługa nie odpowiada w oczekiwanym czasie, zwraca błąd serwera, przerywa sesję albo wymaga ponownej autoryzacji.

Dla użytkownika końcowego nie powinno mieć to większego znaczenia:

• Kasjer chce obsłużyć klienta.
• Księgowa chce widzieć poprawny status faktury.
• Właściciel sklepu chce mieć pewność, że dokumenty nie giną między systemami.

Dobrze zaprojektowana integracja z KSeF nie może zakładać, że wszystko zawsze zadziała za pierwszym razem. Musi mieć retry, kolejkę wysyłki, jasne statusy i log zdarzeń.

KSeF to nie tylko wysłanie faktury

Największy błąd w projektowaniu integracji polega na traktowaniu KSeF jak prostego formularza. Wysyłamy dokument, czekamy na odpowiedź i zamykamy sprawę.

Taki model wygląda dobrze w dokumentacji, ale gorzej działa w realnej sprzedaży. Po drodze może pojawić się:

• Timeout po stronie usługi
• Chwilowa niedostępność KSeF
• Wygasły token sesji
• Odpowiedź serwera bez związku z treścią faktury

Jeżeli system nie rozróżnia tych sytuacji, każdy problem wygląda tak samo. Faktura trafia na listę błędów, księgowa dostaje powiadomienie, administrator sprawdza logi, a użytkownik nie wie, czy dokument wymaga poprawy, czy wystarczyło poczekać chwilę.

Dobra integracja powinna robić więcej niż tylko wysyłać faktury. Powinna rozumieć, co dzieje się po drodze.

Trzy typy błędów, które trzeba rozróżniać

Problemy z wysyłką do KSeF można podzielić na trzy główne grupy. Każda z nich wymaga innej reakcji.

Chwilowe problemy techniczne

Timeout, 502, 503 lub krótkotrwała niedostępność usługi.

Retry w tle — bez angażowania użytkownika

Błędy walidacji dokumentu

Błędny NIP, brak pola, problem ze strukturą dokumentu.

Poprawa faktury — eskalacja do księgowej

Problemy z autoryzacją

Wygasły token, certyfikat, brak uprawnień lub zła konfiguracja.

Administrator — problem dostępu, nie treści

Chwilowe problemy techniczne

To sytuacje, w których dokument może być poprawny, ale komunikacja z KSeF chwilowo się nie udaje. Może to być timeout, odpowiedź 502, odpowiedź 503 albo krótkotrwała niedostępność usługi.

W takich przypadkach system nie powinien od razu angażować użytkownika. Powinien zapisać próbę, odczekać i ponowić wysyłkę zgodnie z polityką retry.

Błędy walidacji dokumentu

To zupełnie inna kategoria. Jeżeli KSeF zwraca błąd wskazujący na niepoprawne dane, ponawianie wysyłki nie pomoże.

Błędny NIP, brak wymaganego pola, problem ze strukturą dokumentu albo niezgodność w danych wymagają poprawy faktury. Taki błąd powinien od razu trafić do osoby, która może go rozwiązać.

Problemy z autoryzacją

Trzecia grupa to błędy związane z dostępem. Wygasły token, problem z certyfikatem, brak uprawnień albo niepoprawna konfiguracja nie powinny być traktowane jak zwykły błąd faktury.

To zadanie dla administratora. System powinien jasno pokazać, że problem dotyczy dostępu do usługi, a nie treści dokumentu.

Dlaczego retry nie jest dodatkiem

Najgorsze, co może zrobić system, to wysłać fakturę raz i od razu oznaczyć cały proces jako nieudany. Błąd techniczny nie zawsze oznacza, że z dokumentem jest coś nie tak.

Jeżeli po drodze pojawi się chwilowy problem, rozsądną reakcją jest ponowienie wysyłki po krótkim czasie. W wielu przypadkach kolejna próba kończy się sukcesem, ponieważ problem był przejściowy.

W Motion błędy techniczne nie są od razu przerzucane na użytkownika. System ponawia wysyłkę tam, gdzie ma to sens, a dopiero jeśli kolejne próby nie przynoszą rezultatu, sprawa trafia do dalszej obsługi.

Co powinna widzieć księgowa

Z perspektywy księgowej proces powinien być prosty. Faktura ma status, numer KSeF, informację o wysyłce i jasny komunikat, jeśli coś wymaga działania.

Nie ma potrzeby, aby księgowa analizowała każdy timeout albo każdą ponowną próbę wysyłki. Techniczne szczegóły powinny być dostępne w systemie, ale nie powinny utrudniać codziennej pracy.

Dobrze zaprojektowany system pokazuje wynik w prosty sposób:

• faktura została wysłana,
• czeka na wysyłkę,
• albo wymaga reakcji.

Reszta powinna działać w tle.

Dlaczego logowanie każdej próby jest ważne

Retry bez historii zdarzeń to tylko połowa rozwiązania. Każda próba wysłania faktury powinna zostać zapisana w systemie.

Liczy się:

• Czas próby wysyłki
• Odpowiedź KSeF i kod błędu
• Treść komunikatu
• Wynik kolejnego ponowienia

Dzięki temu administrator może łatwo sprawdzić, co wydarzyło się z dokumentem. Log zdarzeń pomaga także przy reklamacjach, audytach i pytaniach o opóźnienie numeru KSeF.

Bez historii odpowiedź często brzmi, że nie wiadomo, co się stało. Z logiem audytowym można pokazać dokładną ścieżkę faktury.

To różnica między zgadywaniem a kontrolą nad procesem.

KsefGate i jedna polityka dla całej sieci

W pojedynczym sklepie retry może działać na poziomie centralnego systemu. W sieci kilku lub kilkunastu lokali sytuacja robi się trudniejsza.

Każdy sklep wystawia dokumenty. Każdy może napotkać chwilowy problem z komunikacją. Każda lokalizacja może wygenerować osobny alert.

Dlatego w Motion dla większych struktur stosujemy podejście centralne. KsefGate działa jako warstwa pośrednia między systemem sprzedaży a KSeF. Wszystkie lokalizacje korzystają z jednej kolejki, jednej polityki retry i jednego miejsca monitorowania.

Dzięki temu chwilowa niedostępność usługi nie zamienia się w chaos rozproszony po wielu sklepach. Administrator widzi jeden proces, jedną historię i jeden dashboard.

W małej firmie może to brzmieć jak dodatkowa architektura. W sieci sprzedaży staje się sposobem na zachowanie porządku.

Co zrobić, gdy klient czeka na fakturę

Najtrudniejszy moment pojawia się wtedy, gdy klient stoi przy kasie, a system musi obsłużyć fakturę. Sprzedaż powinna przebiegać płynnie. Techniczna komunikacja z KSeF nie może stać się powodem długiego oczekiwania.

Dokument powinien zostać bezpiecznie zapisany, otrzymać odpowiedni status, a wysyłka do KSeF powinna odbywać się w tle zgodnie z obsługiwanym trybem pracy i wymaganiami systemu.

Kasjer nie powinien tłumaczyć klientowi timeoutów, tokenów ani ponownych prób. Klient chce zakończyć zakup, otrzymać dokument i wyjść ze sklepu.

Dobra integracja:

• nie zatrzymuje sprzedaży przy każdym chwilowym problemie technicznym,
• oznacza dokument właściwym statusem,
• pilnuje kolejki wysyłki,
• wykonuje retry bez angażowania kasjera tam, gdzie nie jest to potrzebne.

Co Motion robi inaczej

Motion traktuje integrację z KSeF jako proces, a nie jednorazowe wywołanie API. System nie tylko wysyła dokumenty, ale też pilnuje statusów, obsługuje ponowienia, rozróżnia klasy błędów i zapisuje historię zdarzeń.

Dzięki temu:

• użytkownik widzi jasny status faktury,
• księgowa dostaje tylko te błędy, które naprawdę wymagają jej uwagi,
• administrator ma dostęp do technicznych szczegółów.

To szczególnie ważne w sprzedaży stacjonarnej. Sklep nie może działać w rytmie zewnętrznych opóźnień. Klient przy kasie nie powinien czekać tylko dlatego, że jedna próba komunikacji z KSeF nie zakończyła się sukcesem.

Najważniejsze wnioski

FAQ