KSeF API authentication token vs access token
authenticationToken a accessToken jest kluczowe dla prawidłowej implementacji.Różnice między authenticationToken a accessToken
authenticationToken to tymczasowy token operacyjny otrzymany po wysłaniu żądania uwierzytelniania (podpis XAdES lub token KSeF). Służy do sprawdzania statusu uwierzytelniania i pobrania finalnego accessToken.
accessToken to token JWT używany do autoryzacji wszystkich operacji API (otwieranie sesji, wysyłanie faktur, pobieranie danych). Jest otrzymywany po pomyślnym uwierzytelnieniu przez wywołanie POST /api/v2/auth/token/redeem.
Proces uwierzytelniania składa się z kilku etapów, w których używane są różne tokeny. Nieprawidłowe użycie tokena na danym etapie prowadzi do błędów autoryzacji.
Instrukcja krok po kroku
1. Wyślij żądanie uwierzytelniania
Wyślij żądanie uwierzytelniania: POST /api/v2/auth/xades-signature (dla podpisu XAdES) lub POST /api/v2/auth/ksef-token (dla tokena KSeF). W odpowiedzi otrzymasz authenticationToken.token (tymczasowy token operacyjny) i referenceNumber.
2. Sprawdź status uwierzytelniania
Użyj authenticationToken.token w nagłówku Authorization: Bearer do sprawdzenia statusu uwierzytelniania: GET /api/v2/auth/{referenceNumber}. Sprawdzaj status do momentu otrzymania informacji o pomyślnym uwierzytelnieniu.
3. Pobierz accessToken
Po pomyślnym uwierzytelnieniu wywołaj POST /api/v2/auth/token/redeem używając authenticationToken.token w nagłówku Authorization: Bearer. W odpowiedzi otrzymasz accessToken (JWT) i refreshToken.
4. Użyj accessToken do operacji API
Używaj accessToken.token w nagłówku Authorization: Bearer przy wszystkich kolejnych żądaniach API (otwieranie sesji, wysyłanie faktur, pobieranie danych). authenticationToken nie jest już potrzebny.
Najczęstsze problemy i rozwiązania
Błąd 401 przy sprawdzaniu statusu uwierzytelniania
Upewnij się, że używasz authenticationToken.token (tymczasowego tokena operacyjnego) w nagłówku Authorization: Bearer, nie accessToken. authenticationToken otrzymujesz w odpowiedzi na POST /api/v2/auth/xades-signature lub POST /api/v2/auth/ksef-token.
Kiedy używać authenticationToken, a kiedy accessToken?
authenticationToken używaj tylko do sprawdzania statusu uwierzytelniania (GET /api/v2/auth/{referenceNumber}) i pobrania accessToken (POST /api/v2/auth/token/redeem). accessToken używaj do wszystkich innych operacji API (sesje, faktury, pobieranie danych).
authenticationToken wygasł
authenticationToken ma krótki czas ważności (określony w polu validUntil). Jeśli wygasł przed pobraniem accessToken, musisz ponownie wysłać żądanie uwierzytelniania (POST /api/v2/auth/xades-signature lub POST /api/v2/auth/ksef-token), aby otrzymać nowy authenticationToken.
Proces uwierzytelniania jest asynchroniczny
Tak, proces uwierzytelniania w KSeF jest asynchroniczny. Po wysłaniu żądania uwierzytelniania musisz regularnie sprawdzać status (GET /api/v2/auth/{referenceNumber}), dopóki nie otrzymasz informacji o pomyślnym uwierzytelnieniu. Dopiero wtedy możesz pobrać accessToken.
Przepływ uwierzytelniania w KSeF API 2.0
Proces składa się z kilku etapów: 1) Wysłanie żądania uwierzytelniania (XAdES lub token KSeF) → otrzymanie authenticationToken i referenceNumber, 2) Sprawdzanie statusu uwierzytelniania używając authenticationToken → oczekiwanie na pomyślne uwierzytelnienie, 3) Pobranie accessToken używając authenticationToken → otrzymanie accessToken i refreshToken, 4) Używanie accessToken do wszystkich operacji API.
authenticationToken – tymczasowy token operacyjny
authenticationToken to token otrzymany po wysłaniu żądania uwierzytelniania. Ma krótki czas ważności (określony w polu validUntil) i służy wyłącznie do: sprawdzania statusu uwierzytelniania (GET /api/v2/auth/{referenceNumber}) oraz pobrania accessToken (POST /api/v2/auth/token/redeem). Po pobraniu accessToken authenticationToken nie jest już potrzebny.
accessToken – token autoryzacyjny JWT
accessToken to token JWT otrzymany po pomyślnym uwierzytelnieniu (POST /api/v2/auth/token/redeem). Jest używany do autoryzacji wszystkich operacji API: otwieranie sesji interaktywnych i wsadowych, wysyłanie faktur, pobieranie faktur, zarządzanie uprawnieniami. accessToken ma ograniczony czas ważności i może być odświeżany za pomocą refreshToken.
Typowe błędy i rozwiązania
Błąd 401 przy sprawdzaniu statusu: użyj authenticationToken, nie accessToken. Błąd przy pobieraniu accessToken: upewnij się, że uwierzytelnianie zakończyło się pomyślnie (sprawdź status). authenticationToken wygasł: wyślij ponownie żądanie uwierzytelniania. Używanie authenticationToken do operacji API: użyj accessToken zamiast authenticationToken.
FAQ
Czym różni się authenticationToken od accessToken?
authenticationToken to tymczasowy token operacyjny otrzymany po wysłaniu żądania uwierzytelniania. Służy do sprawdzania statusu uwierzytelniania i pobrania accessToken. accessToken to token JWT używany do autoryzacji wszystkich operacji API. authenticationToken ma krótki czas ważności, accessToken może być odświeżany.
Kiedy używać authenticationToken?
authenticationToken używaj tylko do: sprawdzania statusu uwierzytelniania (GET /api/v2/auth/{referenceNumber}) oraz pobrania accessToken (POST /api/v2/auth/token/redeem). Po pobraniu accessToken authenticationToken nie jest już potrzebny.
Kiedy używać accessToken?
accessToken używaj do wszystkich operacji API: otwieranie sesji interaktywnych i wsadowych, wysyłanie faktur, pobieranie faktur, zarządzanie uprawnieniami, eksport paczek. accessToken jest przekazywany w nagłówku Authorization: Bearer przy każdym żądaniu API.
Co zrobić, jeśli authenticationToken wygasł?
Jeśli authenticationToken wygasł przed pobraniem accessToken, musisz ponownie wysłać żądanie uwierzytelniania (POST /api/v2/auth/xades-signature lub POST /api/v2/auth/ksef-token), aby otrzymać nowy authenticationToken i referenceNumber.
Dlaczego proces uwierzytelniania jest asynchroniczny?
Proces uwierzytelniania w KSeF jest asynchroniczny, ponieważ system musi zweryfikować certyfikat u jego wystawcy (OCSP/CRL), co może zająć czas. Po wysłaniu żądania uwierzytelniania musisz regularnie sprawdzać status, dopóki nie otrzymasz informacji o pomyślnym uwierzytelnieniu.