Token uwierzytelniający KSeF to klucz, który umożliwia automatyczny dostęp do faktur w Krajowym Systemie e-Faktur. Bez tokena nie zintegrujesz żadnego programu z KSeF — ani programu księgowego, ani narzędzia monitorującego faktury. W tym artykule pokażę jak wygenerować token krok po kroku.
Co to jest token KSeF?
Token KSeF to długi ciąg znaków (string), który pełni rolę hasła dostępowego do API KSeF. Generujesz go w Aplikacji Podatnika i podajesz go programom, które mają w Twoim imieniu odpytywać KSeF o faktury.
Token jest przypisany do konkretnego NIP-u i ma określone uprawnienia. Najważniejsze: token daje dostęp tylko do tych operacji, które mu przyznasz — możesz wygenerować token z uprawnieniami tylko do odczytu, bez możliwości wystawiania faktur.
Rodzaje tokenów KSeF
W KSeF istnieją dwa rodzaje tokenów. Ważne, żeby je rozróżnić:
Token uwierzytelniający (authorization token)
To ten, który generujesz w Aplikacji Podatnika. Służy do otwarcia sesji z API KSeF. Jest długoterminowy — działa do momentu odwołania lub wygaśnięcia. To jest token, którego potrzebujesz do integracji z programami zewnętrznymi.
Cechy tokena uwierzytelniającego:
- Generowany ręcznie w Aplikacji Podatnika
- Długoterminowy (ważność: do odwołania lub data wygaśnięcia, którą sam ustawiasz)
- Używany do inicjowania sesji API
- Powinien być traktowany jak hasło — nie udostępniaj go publicznie
Token sesyjny (session token / access token)
To token krótkoterminowy, generowany automatycznie przez API KSeF po zalogowaniu tokenem uwierzytelniającym. Służy do wykonywania operacji w ramach otwartej sesji. Nie generujesz go ręcznie — programy robią to automatycznie.
Cechy tokena sesyjnego:
- Generowany automatycznie przez API
- Krótkoterminowy (ważność sesji)
- Używany do odpytywania o faktury, pobierania XML
- Nie musisz się nim zajmować — robi to program
Podsumowanie:
Generujesz token uwierzytelniający (jednorazowo). Podajesz go programowi. Program używa go do otwarcia sesji i uzyskania tokena sesyjnego (automatycznie).
Jak wygenerować token uwierzytelniający — krok po kroku
Cały proces trwa 5-10 minut. Potrzebujesz: dostępu do internetu, Profilu Zaufanego (lub e-dowodu / pieczęci kwalifikowanej) i NIP firmy, dla której generujesz token.
Krok 1: Zaloguj się do Aplikacji Podatnika
Wejdź na ap.ksef.mf.gov.pl i zaloguj się. Możesz użyć:
- Profil Zaufany — najczęściej używany, logowanie przez login.gov.pl
- E-dowód — wymaga czytnika NFC
- Pieczęć kwalifikowana — dla firm z podpisem kwalifikowanym
Szczegóły procesu logowania opisaliśmy w artykule Jak zalogować się do KSeF.
Po zalogowaniu wybierz kontekst (NIP firmy), dla której chcesz wygenerować token.
Krok 2: Przejdź do zarządzania uprawnieniami
W menu głównym Aplikacji Podatnika znajdź sekcję "Tokeny" lub "Zarządzanie uprawnieniami" (nazwa zależy od wersji interfejsu). Kliknij, żeby przejść do listy tokenów.
Jeśli wcześniej generowałeś tokeny, zobaczysz je na liście — z datą utworzenia, opisem i statusem (aktywny/odwołany).
Krok 3: Wygeneruj nowy token
Kliknij "Wygeneruj token" (lub "Utwórz nowy token"). System poprosi Cię o:
- Opis tokena — wpisz coś, co pomoże Ci potem zidentyfikować, do czego ten token służy (np. "FakturyKSeF monitoring", "Program księgowy XYZ")
- Rodzaj uprawnień — wybierz uprawnienia, które token ma mieć. Do monitorowania faktur wystarczy odczyt faktur (nie potrzebujesz uprawnień do wystawiania)
- Data wygaśnięcia (opcjonalnie) — możesz ustawić datę, po której token przestanie działać. Jeśli nie ustawisz, token działa do ręcznego odwołania
Potwierdź generowanie — może być wymagana dodatkowa autoryzacja (Profil Zaufany).
Krok 4: Skopiuj i zapisz token
Ważne: token zobaczysz tylko raz!
Po wygenerowaniu tokena system wyświetli go jednorazowo. Skopiuj go natychmiast i zapisz w bezpiecznym miejscu (menedżer haseł, zaszyfrowana notatka). Jeśli go utracisz, musisz wygenerować nowy.
Token to długi ciąg znaków, wyglądający mniej więcej tak:
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwi...
Skopiuj cały ciąg — od pierwszego do ostatniego znaku, bez spacji na początku i końcu.
Jak długo działa token?
To zależy od ustawień, które wybrałeś podczas generowania:
- Bez daty wygaśnięcia — token działa do momentu ręcznego odwołania w Aplikacji Podatnika
- Z datą wygaśnięcia — token przestaje działać po wskazanej dacie. Po wygaśnięciu musisz wygenerować nowy
- Odwołany ręcznie — w każdej chwili możesz odwołać token w Aplikacji Podatnika. Od tego momentu przestaje działać natychmiast
Rekomendacja: dla integracji produkcyjnych (jak FakturyKSeF) ustaw token bez daty wygaśnięcia, ale regularnie weryfikuj listę aktywnych tokenów w Aplikacji Podatnika.
Co zrobić gdy token wygaśnie lub przestanie działać?
Jeśli token wygasnął, został odwołany lub z jakiegoś powodu przestał działać:
- Zaloguj się do Aplikacji Podatnika
- Odwołaj stary token (jeśli jest jeszcze aktywny)
- Wygeneruj nowy token (powtórz kroki 2-4 powyżej)
- Zaktualizuj token w programie, który go używa (np. w FakturyKSeF — zmień token w ustawieniach firmy)
Cały proces trwa kilka minut. Programy korzystające z API KSeF zwykle informują, że token jest nieprawidłowy lub sesja nie może być otwarta — to sygnał, że czas wygenerować nowy.
Bezpieczeństwo tokena
Token KSeF to dane wrażliwe — traktuj go jak hasło. Kilka zasad:
- Nie wysyłaj tokena emailem w formie zwykłego tekstu
- Nie wklejaj go na forach ani w publicznych repo na GitHubie
- Przechowuj w menedżerze haseł (Bitwarden, 1Password, KeePass)
- Generuj osobne tokeny dla każdego programu — łatwiej odwołać jeden bez wpływu na inne
- Token z uprawnieniami do odczytu nie pozwala wystawiać faktur — to minimalizuje ryzyko w przypadku wycieku
Jak użyć tokena w FakturyKSeF
Po wygenerowaniu tokena możesz go od razu wykorzystać w FakturyKSeF do automatycznego monitorowania faktur:
- Zaloguj się na app.fakturyksef.com
- Kliknij "Dodaj firmę"
- Wpisz NIP firmy
- Wklej token uwierzytelniający
- Podaj email, na który mają przychodzić powiadomienia
- Zapisz — monitoring startuje natychmiast
Od tego momentu FakturyKSeF odpytuje KSeF co 15 minut i wysyła email o każdej nowej fakturze przychodzące. Jak sprawdzać faktury innymi sposobami opisaliśmy w artykule Jak sprawdzić fakturę w KSeF — 3 sposoby.
Najczęstsze problemy
Nie widzę opcji generowania tokena
Upewnij się, że jesteś zalogowany jako osoba z odpowiednimi uprawnieniami do NIP-u. Jeśli logujesz się Profilem Zaufanym osoby fizycznej, musisz mieć nadane uprawnienia do reprezentowania podmiotu w KSeF.
Token nie działa w programie
Sprawdź czy: (1) skopiowałeś cały token, bez obcinania, (2) token nie wygasł, (3) program korzysta z właściwego środowiska (test vs produkcja — tokeny nie są wymienne między środowiskami).
Zgubiłem token
Nie da się go odzyskać — wygeneruj nowy. Stary możesz odwołać w Aplikacji Podatnika, żeby nikt go nie wykorzystał.
Jeśli chcesz dowiedzieć się więcej o integracji z KSeF przez API, przeczytaj nasz artykuł KSeF API — dokumentacja, integracja, przykłady.