Token KSeF: po co jest, jak go wygenerować i jak bezpiecznie używać go w programie

Token KSeF to wygenerowany w systemie sekret, który przy logowaniu działa na równi z kwalifikowanym podpisem elektronicznym. Dzięki niemu sklep albo program księgowy loguje się do KSeF sam, bez człowieka z podpisem przy komputerze. Ta wygoda ma swoją cenę: kto ma token, ten ma dostęp do faktur firmy w zakresie jego uprawnień. Dokumentacja Ministerstwa Finansów nazywa go wprost poufnym sekretem, który trzeba trzymać w bezpiecznym magazynie.

Jak wygenerować token KSeF

Token można wygenerować tylko w kontekście NIP-u albo identyfikatora wewnętrznego. Nie nadasz mu uprawnień, których sam nie masz: KSeF odpowie wtedy wyjątkiem 26001. Wyjątek 26002 oznacza, że w bieżącym typie kontekstu tokena wygenerować się nie da.

Jakie uprawnienia dać tokenowi

• Sklep wysyłający sprzedaż: InvoiceWrite. InvoiceRead dodaj tylko wtedy, gdy sklep ma też pobierać faktury z KSeF.
• Program pobierający faktury kosztowe: InvoiceRead.
• Program, który robi jedno i drugie: oba, ale lepiej dwa osobne tokeny dla dwóch modułów, żeby wyciek jednego nie otwierał wszystkiego.
• Zarządzanie uprawnieniami (CredentialsManage): prawie nigdy dla integracji. To uprawnienie dla administratora, nie dla sklepu.

Kiedy token przestaje działać

• Unieważnienie: właściciel tokena albo administrator usuwa go w KSeF. Status przechodzi przez etap unieważniania do unieważnionego.
• Utrata uprawnień: dokumentacja wskazuje, że tokeny są unieważniane, gdy osoba traci uprawnienia, np. po odejściu z firmy.
• Błędy przy logowaniu: status 450 z opisem „token nieaktywny” albo „token unieważniony”, opisany w tekście o błędzie uwierzytelnienia, oraz wyjątek 21301 „Token KSeF został unieważniony”, opisany w tekście o kodach 21301 i 21304.

Najczęstszy scenariusz awarii integracji wygląda tak: token wygenerowała księgowa, księgowa odeszła, jej uprawnienia odebrano, a razem z nimi przestał działać token sklepu. Dlatego token do integracji powinna generować osoba, która zostaje w firmie na dłużej, a opis tokena powinien mówić, do czego służy.

Jak token działa przy logowaniu

Program pobiera wyzwanie od KSeF, łączy token ze znacznikiem czasu z wyzwania, szyfruje całość kluczem publicznym KSeF i odsyła. Token nigdy nie leci jawnym tekstem. Gdy program pomyli znacznik czasu, dostanie wyjątek 21111. Szerszy obraz logowania i sesji opisałem w tekście o API KSeF.

Gdzie przechowywać token KSeF

• Dobrze: menedżer sekretów albo zmienna środowiskowa na serwerze, dostępna tylko dla procesu integracji.
• Źle: plik w repozytorium kodu, pole w bazie danych zapisane jawnym tekstem, arkusz z hasłami, wiadomość na komunikatorze.
• Plan wymiany: jeśli token mógł wyciec, generujesz nowy, podmieniasz w konfiguracji i unieważniasz stary. To kilka minut, gdy procedura jest gotowa.

W opisie tokena wpisuj system i datę, np. „sklep WooCommerce, wysyłka sprzedaży, 10.2026”. Po roku lista tokenów z opisami „test” i „nowy” jest bezużyteczna przy audycie.

Źródło: tokeny KSeF w dokumentacji API KSeF 2.0.