KSeF API token KSeF – szyfrowanie i uwierzytelnianie

Szyfrowanie tokena KSeF

Token KSeF to ciąg znaków generowany przez podatnika w Module Certyfikatów i Uprawnień (MCU). Token służy do szybkiej autoryzacji w API bez konieczności podpisywania dokumentu AuthTokenRequest.

Przed wysłaniem do KSeF token musi być zaszyfrowany w formacie: token|timestamp, gdzie timestamp to aktualny czas w formacie Unix. Szyfrowanie odbywa się za pomocą algorytmu RSA-OAEP z SHA-256 przy użyciu klucza publicznego KSeF.

Klucz publiczny KSeF można pobrać z endpointu GET /api/v2/security/public-key-certificates. Tokeny KSeF będą obsługiwane do końca 2026 roku, po czym ich funkcjonalność przejmą certyfikaty KSeF.

Instrukcja krok po kroku

1. Wygeneruj token KSeF w MCU

Zaloguj się do Modułu Certyfikatów i Uprawnień (ksef.podatki.gov.pl) profilem zaufanym lub podpisem kwalifikowanym. Wygeneruj token KSeF, który będzie używany do uwierzytelniania w API.

2. Pobierz klucz publiczny KSeF

Wywołaj endpoint GET /api/v2/security/public-key-certificates, aby pobrać aktualny klucz publiczny KSeF. Klucz jest używany do szyfrowania tokena przed wysłaniem do systemu.

3. Przygotuj dane do szyfrowania

Utwórz ciąg znaków w formacie token|timestamp, gdzie token to wygenerowany token KSeF, a timestamp to aktualny czas Unix w milisekundach. Przykład: EXAMPLE_TOKEN_PLACEHOLDER|1700000000000.

4. Zaszyfruj token algorytmem RSA-OAEP

Zaszyfruj przygotowany ciąg znaków algorytmem RSAES-OAEP z funkcją skrótu SHA-256 i MGF1. Użyj klucza publicznego KSeF pobranego wcześniej. Wynik szyfrowania zakoduj w formacie Base64.

5. Wyślij zaszyfrowany token do API

Wyślij żądanie POST /api/v2/auth/ksef-token z zaszyfrowanym tokenem w polu encryptedToken oraz challenge i contextIdentifier. W odpowiedzi otrzymasz authenticationToken i referenceNumber do dalszego procesu uwierzytelniania.

Najczęstsze problemy i rozwiązania

Błąd 'Nieprawidłowy token' przy sprawdzaniu statusu

Upewnij się, że używasz authenticationToken.token (tymczasowego tokena operacyjnego) w nagłówku Authorization: Bearer przy sprawdzaniu statusu uwierzytelniania (GET /api/v2/auth/{referenceNumber}). Nie używaj accessToken - ten otrzymasz dopiero po wywołaniu POST /api/v2/auth/token/redeem.

Błąd szyfrowania tokena

Sprawdź, czy używasz algorytmu RSAES-OAEP z SHA-256 i MGF1. Upewnij się, że format danych to token|timestamp (z separatorem |) i że timestamp jest w milisekundach. Zweryfikuj, czy używasz aktualnego klucza publicznego KSeF pobranego z endpointu /api/v2/security/public-key-certificates.

Token wygasł

Token KSeF ma ograniczony czas ważności. Jeśli token wygasł, wygeneruj nowy token w Module Certyfikatów i Uprawnień. Upewnij się, że timestamp w szyfrowaniu jest aktualny i nie przekracza czasu ważności tokena.

Różnice w implementacji RSA-OAEP między bibliotekami

Różne biblioteki (node-forge, BouncyCastle, .NET) mogą wymagać różnych konfiguracji dla RSA-OAEP. Upewnij się, że używasz SHA-256 jako funkcji skrótu i MGF1 jako funkcji generującej maskę. Sprawdź dokumentację biblioteki dotyczącą parametrów RSA-OAEP.

Format tokena i timestamp

Token KSeF musi być połączony z timestamp w formacie: token|timestamp, gdzie separator to znak pipe (|). Timestamp to aktualny czas Unix w milisekundach. Przykład: jeśli token to EXAMPLE_TOKEN_PLACEHOLDER i timestamp to 1700000000000, ciąg do szyfrowania to EXAMPLE_TOKEN_PLACEHOLDER|1700000000000.

Algorytm szyfrowania RSA-OAEP

Token musi być zaszyfrowany algorytmem RSAES-OAEP (RSA Encryption Scheme - Optimal Asymmetric Encryption Padding) z funkcją skrótu SHA-256 i funkcją generującą maskę MGF1. Algorytm zapewnia bezpieczne szyfrowanie asymetryczne. Wynik szyfrowania musi być zakodowany w formacie Base64 przed wysłaniem do API.

Proces uwierzytelniania z tokenem KSeF

Proces składa się z kilku etapów: 1) Pobranie challenge (POST /api/v2/auth/challenge), 2) Szyfrowanie tokena i wysłanie do API (POST /api/v2/auth/ksef-token), 3) Sprawdzenie statusu uwierzytelniania używając authenticationToken (GET /api/v2/auth/{referenceNumber}), 4) Pobranie accessToken po pomyślnym uwierzytelnieniu (POST /api/v2/auth/token/redeem).

Różnica między authenticationToken a accessToken

authenticationToken to tymczasowy token operacyjny otrzymany po wysłaniu zaszyfrowanego tokena KSeF. Służy do sprawdzania statusu uwierzytelniania i pobrania accessToken. accessToken to finalny token JWT używany do autoryzacji wszystkich operacji API. authenticationToken ma krótki czas ważności, accessToken można odświeżać za pomocą refreshToken.

FAQ

Powiązane tematy

• KSeF API autoryzacja i tokeny
• KSeF API token refresh
• KSeF API authentication token