Token czy certyfikat KSeF? Praktyczny przewodnik autoryzacji

Po co w ogóle token lub certyfikat?

Krajowy System e-Faktur wymaga uwierzytelnienia każdego podmiotu, który chce wystawiać lub pobierać faktury. Ministerstwo Finansów udostępnia dwie metody autoryzacji: token autoryzacyjny oraz certyfikat KSeF wraz z kluczem prywatnym.

Obie metody pozwalają systemom informatycznym komunikować się z API KSeF, ale różnią się sposobem działania i poziomem złożoności. Token jest prostszy i najczęściej wykorzystywany przez programy księgowe i integracje SaaS. Certyfikat to rozwiązanie bardziej zaawansowane, stosowane głównie w dużych systemach lub w scenariuszach awaryjnych.

Czym jest token autoryzacyjny?

Token to unikalny 40-znakowy ciąg alfanumeryczny, który generujesz po zalogowaniu się do KSeF przez Profil Zaufany, podpis kwalifikowany lub e-dowód. Token działa podobnie jak klucz API – aplikacja przekazuje go w zapytaniach do KSeF, aby potwierdzić swoją tożsamość.

Każdy token może mieć przypisane konkretne uprawnienia: tylko wystawianie faktur, tylko odczyt, lub pełny dostęp. Kluczowa cecha tokena: wyświetla się tylko raz podczas generowania. Jeśli go nie zapiszesz, musisz usunąć token i wygenerować nowy.

Dlatego warto od razu skopiować go do bezpiecznego miejsca – menedżera haseł, bezpiecznego vaulta lub zaszyfrowanego systemu integracyjnego. Token należy traktować jak dane do bankowości internetowej.

Jak wygenerować token krok po kroku

Wejdź na stronę ksef.mf.gov.pl i kliknij 'Uwierzytelnij'. Podaj NIP firmy i zaloguj się przez Profil Zaufany lub podpis kwalifikowany. Po zalogowaniu wybierz w menu 'Generuj token'.

W formularzu podaj nazwę tokena (np. 'Program księgowy 2025') i wybierz uprawnienia. Możesz utworzyć osobne tokeny dla różnych systemów – jeden do fakturowania, drugi do integracji z CRM. Po kliknięciu 'Generuj token' skopiuj wyświetlony ciąg znaków i zapisz go w bezpiecznym miejscu.

Ministerstwo Finansów zaleca traktować token jak dane do bankowości internetowej. Nie udostępniaj go nikomu, a w przypadku podejrzenia wycieku – natychmiast usuń i wygeneruj nowy.

Czym jest certyfikat KSeF i klucz prywatny?

Certyfikat KSeF to certyfikat kryptograficzny, który identyfikuje firmę lub system komunikujący się z KSeF. Wraz z certyfikatem generowany jest klucz prywatny, który pozostaje wyłącznie po stronie użytkownika lub systemu integracyjnego. Mechanizm działa podobnie do certyfikatów TLS, podpisów elektronicznych czy certyfikatów używanych w bankowości.

W komunikacji z API aplikacja podpisuje żądanie kluczem prywatnym, a KSeF weryfikuje podpis przy użyciu certyfikatu. Dzięki temu system może potwierdzić tożsamość bez używania tokena.

Ministerstwo Finansów przewiduje dwa rodzaje certyfikatów. Certyfikat typu 1 służy do uwierzytelniania w API KSeF, sesji interaktywnych i przetwarzania wsadowego – może być używany przez systemy ERP lub inne narzędzia integracyjne zamiast tokena. Certyfikat typu 2 służy wyłącznie do oznaczania faktur wystawianych offline, gdy KSeF jest niedostępny lub działa tryb awaryjny.

Token vs certyfikat – kiedy którego użyć?

Token jest najlepszy gdy używasz programu księgowego, integrujesz KSeF z SaaS lub potrzebujesz prostego dostępu do API. Jest łatwy do wygenerowania, szybki w implementacji i nie wymaga kryptografii. Dlatego większość małych i średnich firm korzysta wyłącznie z tokena.

Certyfikat z kluczem prywatnym jest lepszy gdy masz własny system ERP, potrzebujesz wyższego poziomu bezpieczeństwa, chcesz obsłużyć tryb offline lub integracja działa w infrastrukturze enterprise. W takim przypadku aplikacja przechowuje certyfikat i klucz prywatny, używając ich do podpisywania komunikacji z KSeF.

Większość narzędzi integracyjnych korzysta z tokena, ponieważ jest prostszy w obsłudze. Certyfikat i klucz prywatny są wymagane głównie gdy system implementuje pełną obsługę trybu offline, firma ma własną infrastrukturę podpisów lub integracja działa bez udziału użytkownika przez długi czas.

Jak bezpiecznie przekazać token lub certyfikat do narzędzia?

Token lub klucz prywatny to dane o wysokiej wrażliwości. Nie powinno się ich przekazywać przez e-mail, komunikatory ani dokumenty tekstowe. Najbezpieczniejsze metody to menedżer haseł z funkcją udostępniania, bezpieczny vault lub szyfrowany transfer w aplikacji.

W KSeF GPT (ksefgpt.pl) rozwiązaliśmy ten problem przez szyfrowane przekazywanie danych autoryzacyjnych. Tokeny i certyfikaty są przechowywane w formie zaszyfrowanej i nigdy nie są dostępne w postaci jawnej.

Autoryzacja w KSeF GPT – token czy certyfikat?

W narzędziu KSeF GPT (ksefgpt.pl) można korzystać z obu metod autoryzacji udostępnianych przez Ministerstwo Finansów: tokena autoryzacyjnego oraz certyfikatu KSeF wraz z kluczem prywatnym.

Token jest najprostszą metodą konfiguracji. Wystarczy wygenerować go w KSeF i wkleić do ustawień integracji. Dzięki temu aplikacja może komunikować się z API KSeF w imieniu Twojej firmy i automatycznie wysyłać lub pobierać faktury. Warto jednak pamiętać, że token może zostać w każdej chwili unieważniony lub usunięty w systemie KSeF – w takiej sytuacji integracja przestanie działać i konieczne będzie wygenerowanie nowego tokena.

Alternatywą jest autoryzacja certyfikatem KSeF i kluczem prywatnym. W tym modelu aplikacja podpisuje komunikację kryptograficznie, a KSeF weryfikuje tożsamość na podstawie certyfikatu. Certyfikat ma określony okres ważności – maksymalnie do 2 lat – dzięki czemu integracja może działać stabilnie przez dłuższy czas bez konieczności ponownej konfiguracji.

Dlatego w praktyce: token to szybka konfiguracja i najprostsza integracja, a certyfikat z kluczem prywatnym to rozwiązanie bardziej trwałe i stabilne dla długoterminowych integracji. KSeF GPT obsługuje oba mechanizmy, dzięki czemu możesz wybrać metodę najlepiej dopasowaną do sposobu pracy Twojej firmy.