KSeF 2.0 po stronie IT w MŚP: certyfikat, token, API i zmiany integracyjne, które trzeba uporządkować
KSeF 2.0 w praktyce: od rozliczeń do konfiguracji technicznej
Po stronie MŚP wdrożenie KSeF 2.0 nie sprowadza się do samego wystawienia faktury z systemu ERP. Z udostępnionych materiałów wynika, że trzeba uporządkować co najmniej cztery obszary: sposób uwierzytelniania w systemie, zasady nadawania uprawnień, wybór mechanizmu integracji z API oraz obsługę sytuacji szczególnych, w tym trybów offline. To oznacza, że temat dotyczy jednocześnie księgowości, administratorów systemów i dostawcy oprogramowania.
W oficjalnych materiałach KSeF wskazano, że certyfikat KSeF jest jedną z metod uwierzytelnienia w systemie. Jednocześnie certyfikat typu 2 jest wymagany do oznaczenia faktury kodem umożliwiającym potwierdzenie tożsamości wystawcy przy wystawianiu faktur w trybach szczególnych: offline24, offline w razie niedostępności systemu oraz w trybie awaryjnym. To ważne rozróżnienie, bo pokazuje, że część decyzji technicznych wpływa nie tylko na logowanie, ale także na ciągłość procesu fakturowania w sytuacji odstępstw od standardowej pracy online.
Ministerstwo Finansów opisuje też oddzielnie tokeny. Z opublikowanych informacji wynika, że token może służyć do uwierzytelnienia, ale nie jest funkcjonalnie równoważny certyfikatowi. Token zawiera uprawnienia podatnika deklarowane w momencie jego generowania, podczas gdy certyfikat KSeF ma pełnić wyłącznie rolę środka uwierzytelnienia. Dla firmy oznacza to, że wybór między tymi mechanizmami nie powinien być przypadkowy, bo inaczej układa się później zarządzanie zmianą uprawnień, odpowiedzialnością i eksploatacją integracji.
Certyfikat, token, podpis i uprawnienia: co naprawdę trzeba rozdzielić
W praktyce warto zacząć od prostego porządku pojęciowego. Certyfikat KSeF nie jest tym samym co token, a token nie zastępuje całego modelu uprawnień. W sekcji pytań i odpowiedzi resort wskazuje, że program komercyjny może działać bez dodatkowych form uwierzytelnienia, jeżeli używa tokenu wygenerowanego przez osobę mającą stosowne uprawnienia, na przykład do wystawiania i dostępu do faktur. Jednocześnie podkreślono, że uprawnienia w KSeF nadaje się konkretnym osobom lub podmiotom, a nie systemom. To rozróżnienie ma znaczenie organizacyjne: system działa technicznie, ale odpowiedzialność pozostaje po stronie osoby albo podmiotu, który nadał i wykorzystuje uprawnienia.
Oficjalna strona o certyfikatach wyjaśnia też, że występują dwa typy certyfikatu KSeF. Typ 1 służy do uwierzytelniania się w systemie i może być używany zarówno w sesji interaktywnej, jak i wsadowej. Typ 2 jest przeznaczony do trybów offline. Oba certyfikaty są generowane osobno i nie da się wygenerować jednego certyfikatu obejmującego jednocześnie oba zastosowania. Dla MŚP to sygnał, że już na etapie projektu integracji trzeba ustalić, czy firma potrzebuje tylko logowania do API, czy także obsługi procesów offline.
Źródła potwierdzają również, że certyfikat KSeF może być wydany osobie fizycznej albo podmiotowi. Jeżeli certyfikat wydano na dane podmiotu, odpowiedzialność za jego przekazywanie pracownikom i posługiwanie się nim leży po stronie organizacji. Jeżeli natomiast certyfikat zawiera dane osoby fizycznej, o taki certyfikat może wnioskować wyłącznie ta osoba i tylko ona może go pobrać oraz używać. Proponujemy więc rozdzielić w dokumentacji wewnętrznej dwa poziomy odpowiedzialności: odpowiedzialność za nadanie uprawnień w KSeF oraz odpowiedzialność za przechowywanie i użycie konkretnego środka uwierzytelnienia.
Jakie systemy i procesy objąć przeglądem przed przełączeniem
Na podstawie opublikowanych materiałów można bezpiecznie stwierdzić, że przegląd powinien objąć nie tylko ERP. Jeżeli firma korzysta z integratora, middleware, osobnego modułu wysyłkowego albo zewnętrznego biura rachunkowego, to wszystkie te elementy mogą być powiązane z uwierzytelnianiem, nadawaniem uprawnień i adresacją środowisk. Dodatkowo w pytaniach i odpowiedziach wskazano, że operacje administracyjne, takie jak nadawanie uprawnień czy generowanie tokenów, można wykonywać w Aplikacji Podatnika KSeF. To oznacza, że obieg administracyjny i integracja aplikacyjna nie są tym samym procesem i nie powinny być traktowane jako jedno zadanie.
Proponujemy sprawdzić przede wszystkim, kto w firmie faktycznie generuje tokeny, kto nadaje uprawnienia i kto jest właścicielem relacji z dostawcą oprogramowania. W części organizacji formalnym użytkownikiem KSeF będzie podatnik lub osoba uprawniona, ale techniczną konfigurację wykona partner wdrożeniowy. Bez jasnego rozdzielenia ról łatwo o sytuację, w której integracja działa testowo, lecz nie ma spójnego procesu odnowienia certyfikatu, zmiany osoby uprawnionej albo wycofania dostępu po zmianie obowiązków pracownika.
Jeżeli w organizacji działa więcej niż jeden podmiot, oddział albo jednostka wewnętrzna, warto też uwzględnić model uprawnień opisany w pytaniach i odpowiedziach, w tym wykorzystanie IDWew tam, gdzie jest to potrzebne. Źródło nie przedstawia tego jako nowej zmiany, ale potwierdza, że rozwiązanie działa i nie planuje się zmian w obsłudze wielooddziałowości w tym zakresie. Dla MŚP oznacza to potrzebę weryfikacji, czy obecna struktura dostępu odzwierciedla rzeczywisty podział pracy, a nie tylko historyczny sposób konfiguracji.
Zmiany integracyjne: adresy środowisk, przełączenia i zgodność klienta HTTP
Jednym z najlepiej udokumentowanych obszarów po stronie technicznej jest zmiana adresów środowisk KSeF. W komunikacie dla integratorów wskazano, że resort finansów wprowadził nową, jednolitą adresację środowisk KSeF. Jednocześnie podkreślono, że zmiana ma charakter techniczny i polega na aktualizacji wykorzystywanych adresów usług, bez wpływu na zakres oraz sposób działania udostępnianych interfejsów API. To ważna informacja dla MŚP, bo oznacza, że prace mogą dotyczyć bardziej konfiguracji i połączeń niż samej logiki biznesowej.
Komunikat opisuje także okres przejściowy oraz moment wyłączenia starych adresów. Dla środowisk testowych przewidziano czas na przełączenie, następnie przekierowania ze starych adresów, a później całkowite wyłączenie poprzedniej adresacji. Wprost wskazano również, że jeżeli klient HTTP albo używana biblioteka integracyjna nie obsługuje przekierowań, konieczna będzie ręczna aktualizacja adresów bazowych po stronie integratora. Z perspektywy MŚP to bardzo praktyczny punkt kontrolny: nie wystarczy zapytać dostawcy, czy integracja działa, ale trzeba ustalić, czy obsługuje przekierowania i gdzie dokładnie zapisane są bazowe adresy usług.
W tym samym komunikacie podano nowe adresy środowisk dla API, aplikacji do wizualizacji kodów QR i Aplikacji Podatnika, osobno dla środowiska testowego, demonstracyjnego i produkcyjnego. Osobna uwaga dotyczy usługi MCU, której adres pozostaje bez zmian. Proponujemy więc przejrzeć konfigurację w kilku miejscach naraz: w ERP, w warstwie integracyjnej, w skryptach wdrożeniowych, w dokumentacji operacyjnej oraz w checklistach testowych. Jeżeli adres środowiska jest zapisany w więcej niż jednym miejscu, ryzyko pominięcia rośnie nawet wtedy, gdy sama integracja została poprawnie przygotowana przez dostawcę.
Kiedy używać certyfikatu, a kiedy tokenu
Źródła pozwalają ostrożnie sformułować jedną praktyczną zasadę. Jeżeli firma potrzebuje wyłącznie uwierzytelnienia do pracy z KSeF, może rozważać zarówno token, jak i inne dopuszczone mechanizmy, o ile odpowiadają jej modelowi organizacyjnemu. Jeżeli jednak musi obsłużyć wystawianie faktur w trybach szczególnych offline, certyfikat KSeF typu 2 jest wymagany do oznaczenia faktury odpowiednim kodem potwierdzającym tożsamość wystawcy. Tego zastosowania nie należy więc zostawiać na końcówkę projektu.
W materiałach o certyfikatach podkreślono także, że system komercyjny musi mieć zaimplementowany zestaw funkcjonalności pozwalający na wykorzystanie certyfikatu KSeF, w tym mechanizm składania podpisu XAdES-BES na potrzeby uwierzytelnienia w KSeF API. Wskazano również, że dla faktur offline potrzebny jest mechanizm generowania linku do weryfikacji wystawcy faktury. To nie są kwestie czysto formalne. Jeżeli aplikacja albo moduł integracyjny ich nie wspiera, samo posiadanie certyfikatu nie rozwiązuje problemu.
Warto też odnotować ograniczenie opisane wprost przez źródło: nie jest możliwe uwierzytelnienie certyfikatem w Aplikacji Podatnika KSeF. To kolejny argument za tym, by rozdzielić w projekcie kanał administracyjny od kanału integracyjnego. Proponujemy opisać w procedurze, które czynności wykonuje się w aplikacji podatnika, a które w systemie zewnętrznym lub przez API, tak aby zespół nie zakładał błędnie, że ten sam środek uwierzytelnienia zadziała identycznie we wszystkich miejscach.
Lista kontroli przedprodukcyjnej dla MŚP
Przed przejściem na produkcję proponujemy przygotować krótką listę kontroli opartą wyłącznie na elementach potwierdzonych w źródłach. Po pierwsze, warto sprawdzić, jaki mechanizm uwierzytelnienia został przyjęty dla każdego procesu: logowania administracyjnego, pracy systemu zewnętrznego, wysyłki wsadowej i ewentualnych trybów offline. Po drugie, należy zweryfikować, czy uprawnienia są przypisane właściwym osobom lub podmiotom, bo KSeF nie nadaje ich systemom. Po trzecie, trzeba potwierdzić, że wygenerowane tokeny pochodzą od osób mających odpowiednie uprawnienia.
Po stronie technicznej proponujemy sprawdzić zgodność adresów środowisk, zachowanie klienta HTTP przy przekierowaniach oraz to, czy wszystkie komponenty korzystają z tej samej aktualnej adresacji. Dobrą praktyką roboczą będzie także potwierdzenie, czy używany system komercyjny wspiera funkcje wymagane do pracy z certyfikatem KSeF, jeżeli firma planuje taki model uwierzytelniania lub obsługę offline. W źródłach nie ma gotowej listy testów akceptacyjnych, dlatego nie warto udawać, że istnieje jeden oficjalny wzorzec. Lepiej przygotować własną checklistę dla konkretnych scenariuszy użycia.
W części organizacyjnej proponujemy opisać sposób ewidencji certyfikatów firmowych, ich przekazywania, używania i unieważniania, bo oficjalna strona wprost wskazuje potrzebę zadbania o rejestrację i rozliczalność tych operacji po stronie organizacji. Warto też z góry ustalić, kto odpowiada za odnowienie certyfikatu przed końcem ważności, ponieważ certyfikat KSeF jest ważny nie dłużej niż dwa lata od daty jego wytworzenia albo od wskazanej daty początkowej obowiązywania.
Procedura awaryjna i dokumentacja wewnętrzna
Dla MŚP procedura awaryjna nie musi być rozbudowanym podręcznikiem. Powinna jednak odpowiadać na pytania, które wynikają bezpośrednio ze źródeł: jaki typ certyfikatu jest używany, kto może wystąpić o kolejny certyfikat, gdzie wykonuje się operacje administracyjne, które systemy korzystają z tokenu, a które z innych metod uwierzytelnienia, oraz co dzieje się po zmianie osoby odpowiedzialnej albo po wymianie dostawcy integracji.
Szczególnie istotne jest opisanie odpowiedzialności za certyfikaty wydane na podmiot. Oficjalna strona zaznacza, że w takim przypadku to organizacja odpowiada za przekazywanie certyfikatów konkretnym pracownikom i za sposób posługiwania się nimi. Jeżeli firma nie opisze tego w swoich zasadach wewnętrznych, łatwo stracić rozliczalność działań mimo formalnie poprawnej konfiguracji systemu.
Na koniec proponujemy, aby dokumentacja wewnętrzna nie kończyła się na samym wdrożeniu. Warto utrzymywać prosty rejestr: jaki środek uwierzytelnienia obsługuje dany proces, kto jest właścicielem biznesowym procesu, kto odpowiada za konfigurację techniczną i w jakim miejscu zapisano adresy środowisk. Przy KSeF 2.0 porządek po stronie IT nie polega wyłącznie na uruchomieniu połączenia z API. Chodzi o to, by firma wiedziała, kto, czym i w jakim trybie działa, zanim pojawi się zmiana uprawnień, konieczność przełączenia adresów albo potrzeba skorzystania z trybu szczególnego.
