Faktura wychodzi z programu księgowego, trafia do KSeF i wraca z numerem. Taki schemat dobrze wygląda na jednym slajdzie. W firmie pozostają jednak pytania: kto reaguje na odrzucenie dokumentu, gdzie trafia faktura zakupowa i co widzi pracownik, gdy odpowiedź nie przychodzi od razu? Integracja z KSeF obejmuje cały obieg wraz ze statusami i wyjątkami.
Rozdziel wysyłkę i odbiór
Wystawianie oraz odbieranie faktur to dwa osobne przepływy. Pierwszy może zaczynać się od zrealizowanego zamówienia w sklepie, zatwierdzonej usługi albo dokumentu utworzonego w ERP. System musi zbudować fakturę zgodną ze schematem, wysłać ją, sprawdzić wynik przetwarzania i zapisać numer KSeF oraz UPO przy właściwym dokumencie.
Drugi przepływ biegnie w przeciwną stronę. Firma pobiera informacje o fakturach zakupowych, a następnie przypisuje dokument do spółki, zamówienia, projektu lub osoby akceptującej koszt. Samo pobranie pliku nie rozstrzyga, kto ma go opisać i czy kwota zgadza się z zamówieniem.
Aktualne terminy obowiązku i zakres wdrożenia publikuje Ministerstwo Finansów na stronie etapów wdrożenia KSeF 2.0. Harmonogram mówi, kiedy firma ma korzystać z systemu. Projekt integracji powinien dodatkowo odpowiedzieć, co dzieje się z dokumentem przed wysyłką i po jego odebraniu.
Nadaj systemom konkretne role
Jedna informacja może pojawiać się w kilku miejscach, ale tylko jeden system powinien być jej właścicielem. ERP może odpowiadać za numer dokumentu i pozycje sprzedaży, CRM za opiekuna klienta, a aplikacja obiegowa za akceptację kosztu. KSeF potwierdza przyjęcie faktury i nadaje jej własny numer. Nie przejmuje przez to całego wewnętrznego procesu firmy.
W lokalnym systemie przydaje się powiązanie co najmniej czterech elementów: identyfikatora dokumentu w firmie, identyfikatora operacji wysyłki, aktualnego statusu oraz numeru KSeF po przyjęciu. Bez tego pracownik widzi komunikat o błędzie, ale nie potrafi szybko ustalić, której faktury dotyczy.
Jeżeli podobny problem występuje również między sklepem i ERP, pomocny będzie osobny tekst o tym, jak zaplanować właścicieli danych i statusy w integracji sklepu z ERP.
Przyjęcie żądania nie kończy wysyłki
API może przyjąć żądanie, zanim zakończy sprawdzanie faktury. Oficjalny przewodnik po sesji interaktywnej API KSeF 2.0 opisuje osobne identyfikatory sesji i faktury oraz późniejsze sprawdzanie statusu. Integracja musi więc zachować identyfikator zwrócony po wysyłce, a następnie odczytać wynik i dopiero wtedy oznaczyć dokument jako przyjęty.
To rozróżnienie jest szczególnie ważne przy przerwanym połączeniu. Brak odpowiedzi nie mówi, czy dokument nie dotarł, czy został przyjęty, lecz klient nie odebrał potwierdzenia. Automatyczne wysłanie tego samego dokumentu po każdym timeoutcie może utworzyć duplikat próby. Najpierw trzeba sprawdzić poprzednią operację, korzystając z zapisanego identyfikatora.
Zaprojektuj kolejkę wyjątków
Część problemów system może obsłużyć samodzielnie. Po odpowiedzi 429 Too Many Requests powinien zaczekać zgodnie z nagłówkiem Retry-After, zamiast od razu
ponawiać serię żądań. Ten mechanizm opisują oficjalne limity API KSeF 2.0.
Inne błędy wymagają decyzji człowieka. Brak NIP-u nabywcy, niewłaściwa pozycja faktury albo niezgodność z zamówieniem nie znikną po ponowieniu wywołania. Taki dokument powinien trafić do kolejki z opisem przyczyny, właścicielem sprawy i możliwością bezpiecznego wznowienia po poprawce.
Co powinien pokazać ekran wyjątków
- Dokument i system, z którego pochodzi
- Ostatni znany status oraz czas jego sprawdzenia
- Czytelny opis błędu obok kodu technicznego
- Osobę lub zespół odpowiedzialny za decyzję
- Bezpieczną akcję: ponów, popraw dane albo zamknij sprawę
Kiedy wystarczy integracja producenta
Jeżeli wszystkie faktury powstają w jednym aktualnym programie księgowym, a producent obsługuje KSeF 2.0, własny łącznik może być zbędny. Najpierw trzeba sprawdzić gotową konfigurację, uprawnienia, sposób prezentacji błędów i odbiór faktur zakupowych. Darmowe narzędzia Ministerstwa Finansów mogą też wystarczyć firmie z prostym, ręcznie obsługiwanym procesem.
Osobna integracja zaczyna mieć sens, gdy dokumenty powstają w kilku systemach, status KSeF musi wrócić do sprzedaży lub obsługi klienta, a faktury zakupowe trzeba automatycznie przypisywać do zamówień i akceptacji. Kryteria takiej decyzji opisaliśmy szerzej w porównaniu: gotowy system, integracja czy własne oprogramowanie.
Zacznij od jednej faktury
Wybierz jeden rzeczywisty dokument sprzedażowy i prześledź go od zdarzenia, które uruchamia wystawienie, aż do zaksięgowania numeru KSeF i obsługi korekty. Następnie zrób to samo z fakturą zakupową. Taka próba pokaże brakujące dane, odpowiedzialności i wyjątki wcześniej niż lista endpointów.
