Token KSeF - co to jest? Definicja pojęcia KSeF
Co to jest token KSeF?
Token KSeF to specjalny token autoryzacyjny generowany w systemie KSeF, który może być używany do uwierzytelniania w KSeF API zamiast certyfikatu kwalifikowanego. Token składa się z zaszyfrowanego ciągu zawierającego token i znacznik czasu (timestamp).
Token KSeF jest alternatywą dla podpisu kwalifikowanego w procesie uwierzytelniania w API. Zamiast podpisywać dokument AuthTokenRequest podpisem kwalifikowanym (XAdES), możesz użyć tokena KSeF, który jest szyfrowany kluczem publicznym KSeF.
Token KSeF jest szczególnie przydatny dla: automatyzacji procesów (nie wymaga interakcji użytkownika), integracji systemów (łatwiejszy w użyciu niż certyfikaty), scenariuszy, gdzie certyfikat kwalifikowany jest zbyt skomplikowany.
Jak uzyskać token KSeF?
Aby uzyskać token KSeF: 1) Zaloguj się do KSeF używając Profilu Zaufanego, podpisu kwalifikowanego lub certyfikatu kwalifikowanego, 2) Przejdź do sekcji zarządzania tokenami (w Aplikacji Podatnika KSeF lub przez MCU), 3) Wygeneruj nowy token KSeF - system wyświetli token i timestamp, 4) Zapisz token bezpiecznie (nie udostępniaj go osobom trzecim), 5) Użyj tokena do uwierzytelniania w API. Token KSeF jest ważny przez określony czas (zwykle kilka miesięcy) i może być odwołany w dowolnym momencie.
Jak używać tokena KSeF w API?
Aby użyć tokena KSeF do uwierzytelniania w API: 1) Pobierz challenge z endpointu POST /api/v2/auth/challenge, 2) Przygotuj ciąg token|timestamp (gdzie token to Twój token KSeF, a timestamp to aktualny czas), 3) Zaszyfruj ciąg kluczem publicznym KSeF używając algorytmu RSA-OAEP (SHA-256), 4) Wyślij zaszyfrowany ciąg do endpointu POST /api/v2/auth/ksef-token, 5) Otrzymasz authenticationToken i referenceNumber, 6) Sprawdź status uwierzytelniania i uzyskaj accessToken. Proces jest zautomatyzowany w oficjalnych SDK KSeF.
Token KSeF vs certyfikat kwalifikowany
Token KSeF: łatwiejszy w użyciu (nie wymaga certyfikatu), przydatny do automatyzacji, może być generowany online, wymaga logowania do KSeF do wygenerowania. Certyfikat kwalifikowany: bardziej uniwersalny (może być używany poza KSeF), ma pełną moc prawną, wymaga zakupu (100-300 zł rocznie), bardziej bezpieczny (klucz prywatny jest chroniony). Wybór zależy od potrzeb - dla automatyzacji API token KSeF może być wygodniejszy, dla podpisywania dokumentów poza KSeF lepszy jest certyfikat kwalifikowany.
FAQ
Gdzie znajdę mój token KSeF?
Token KSeF możesz wygenerować w: Aplikacji Podatnika KSeF - po zalogowaniu przejdź do sekcji zarządzania tokenami, MCU (Moduł Certyfikatów Użytkownika) - jeśli masz dostęp do MCU. Token jest wyświetlany tylko raz przy generowaniu, więc zapisz go bezpiecznie. Jeśli zgubisz token, możesz wygenerować nowy (stary token zostanie automatycznie unieważniony).
Jak długo ważny jest token KSeF?
Token KSeF jest ważny przez okres określony przy generowaniu (zwykle kilka miesięcy). Możesz sprawdzić ważność tokena w Aplikacji Podatnika KSeF lub MCU. Po wygaśnięciu musisz wygenerować nowy token. Możesz też odwołać token w dowolnym momencie, jeśli podejrzewasz, że został skompromitowany.
Czy token KSeF jest bezpieczny?
Tak, token KSeF jest bezpieczny, ponieważ: jest szyfrowany przed wysłaniem do KSeF, wymaga logowania do KSeF do wygenerowania, może być odwołany w dowolnym momencie, jest unikalny dla każdego użytkownika. Ważne jest, aby chronić token - nie udostępniaj go osobom trzecim i przechowuj go bezpiecznie (np. w menedżerze haseł lub zmiennych środowiskowych).
Czy muszę mieć token KSeF?
Nie, token KSeF nie jest wymagany - możesz użyć certyfikatu kwalifikowanego do uwierzytelniania w API. Token KSeF jest opcjonalną alternatywą, która może być wygodniejsza dla automatyzacji. Jeśli wystawiasz faktury ręcznie przez portal webowy, nie potrzebujesz tokena KSeF - wystarczy Profil Zaufany lub certyfikat kwalifikowany do logowania.