KSeF API autoryzacja i tokeny

Strona opisuje zagadnienie „KSeF API autoryzacja i tokeny” w ramach Krajowego Systemu e-Faktur (KSeF) w oparciu o oficjalne informacje Ministerstwa Finansów.

Co musisz wiedzieć

Krajowy System e-Faktur (KSeF) jest centralnym systemem administracji skarbowej do wystawiania i otrzymywania faktur ustrukturyzowanych w formacie XML.

Na tej stronie znajdziesz uporządkowane informacje dotyczące tematu: KSeF API autoryzacja i tokeny. Opis koncentruje się na aktualnych przepisach oraz komunikatach Ministerstwa Finansów.

Instrukcja krok po kroku

1. Pobierz challenge autoryzacyjny

Wywołaj endpoint POST /api/v2/auth/challenge, aby otrzymać unikalny challenge (wyzwanie). Challenge jest ważny przez 10 minut i stanowi podstawę procesu uwierzytelniania.

2. Przygotuj dokument AuthTokenRequest

Utwórz dokument XML zgodny ze schematem AuthTokenRequest, zawierający challenge, ContextIdentifier (NIP, InternalId lub NipVatUe) oraz SubjectIdentifierType określający typ podmiotu uwierzytelniającego.

3. Podpisz dokument elektronicznie

Podpisz przygotowany dokument kwalifikowanym podpisem elektronicznym w formacie XAdES lub użyj tokena KSeF wygenerowanego w Module Certyfikatów i Uprawnień (MCU).

4. Wyślij podpisany dokument do API

Przekaż podpisany dokument do POST /api/v2/auth/xades-signature (dla podpisu XAdES) lub POST /api/v2/auth/ksef-token (dla tokena KSeF). W odpowiedzi otrzymasz authenticationToken i referenceNumber.

5. Uzyskaj token dostępowy

Po pomyślnym uwierzytelnieniu wywołaj POST /api/v2/auth/token/redeem, aby uzyskać accessToken (JWT do autoryzacji operacji) i refreshToken (do odświeżania accessToken bez ponownego uwierzytelniania).

Najczęstsze problemy i rozwiązania

Token wygasł podczas sesji API

Token JWT (accessToken) ma ograniczony czas ważności. Użyj refreshToken, aby odświeżyć token wywołując POST /api/v2/auth/token/refresh przed wygaśnięciem sesji.

Błąd przy podpisywaniu żądania autoryzacyjnego

Sprawdź, czy używasz prawidłowego certyfikatu kwalifikowanego lub certyfikatu KSeF. Upewnij się, że challenge jest poprawnie zakodowany i podpisany w formacie XAdES.

Tokeny z KSeF 1.0 nie działają w nowym systemie

Tokeny z KSeF 1.0 nie są kompatybilne z API 2.0. Wygeneruj nowe tokeny przez Moduł Certyfikatów i Uprawnień (MCU) dostępny na ksef.podatki.gov.pl.

Mechanizmy autoryzacji w API KSeF 2.0

API KSeF 2.0 oferuje dwa główne mechanizmy uwierzytelniania: podpis elektroniczny XAdES (kwalifikowany podpis lub pieczęć) oraz token KSeF generowany w Module Certyfikatów i Uprawnień (MCU). Oba mechanizmy prowadzą do uzyskania tokena JWT (accessToken), który jest używany do autoryzacji wszystkich operacji API.

Token JWT – accessToken i refreshToken

Po pomyślnym uwierzytelnieniu otrzymujesz parę tokenów: accessToken (krótki czas ważności, kilkanaście minut) oraz refreshToken (ważny do 7 dni). accessToken jest przekazywany w nagłówku Authorization przy każdym żądaniu API. Gdy accessToken wygaśnie, użyj refreshToken do jego odświeżenia bez ponownego uwierzytelniania.

Token KSeF vs certyfikat KSeF

Token KSeF to ciąg znaków generowany przez podatnika w MCU, służący do szybkiej autoryzacji w API. Certyfikat KSeF to elektroniczny dokument wydawany przez Ministerstwo Finansów, niezbędny do autoryzacji w trybie offline i awaryjnym. Certyfikat jest ważny maksymalnie 2 lata i wymaga wniosku w MCU.

Bezpieczeństwo tokenów i certyfikatów

Tokeny i certyfikaty należy traktować jak dane szczególnie wrażliwe. Przechowuj je bezpiecznie, nie udostępniaj osobom nieupoważnionym. W przypadku kompromitacji natychmiast odwołaj token lub certyfikat w Module Certyfikatów i Uprawnień. System stosuje limity liczby żądań (rate limiting) dla ochrony przed nadużyciami.

FAQ

Jak uzyskać token autoryzacyjny do KSeF?

Token autoryzacyjny generuje się przez Moduł Certyfikatów i Uprawnień (MCU) po uprzedniej weryfikacji tożsamości w systemie za pomocą podpisu zaufanego, podpisu kwalifikowanego lub pieczęci kwalifikowanej. Token służy do szybkiej autoryzacji w API KSeF 2.0.

Czym różni się token od certyfikatu KSeF?

Token jest generowany przez podatnika i służy do szybkiej autoryzacji w komunikacji z API KSeF. Certyfikat KSeF to elektroniczny dokument wydawany przez Ministerstwo Finansów, niezbędny do autoryzacji w trybie offline i awaryjnym. Certyfikat jest ważny maksymalnie 2 lata.

Jak wygląda proces autoryzacji w API KSeF 2.0?

Proces obejmuje trzy etapy: uzyskanie challenge z API, podpisanie challenge elektronicznym podpisem (XAdES), przekazanie podpisanego żądania do API w celu otrzymania tokenu JWT (accessToken), który jest następnie używany do autoryzacji operacji.

Czy tokeny z KSeF 1.0 działają w KSeF 2.0?

Nie, tokeny wygenerowane do KSeF 1.0 nie są kompatybilne z systemem 2.0. Należy wygenerować nowe tokeny przez Moduł Certyfikatów i Uprawnień (MCU).