Token i certyfikat KSeF: jak ogarnąć uwierzytelnianie i uprawnienia

Gdy podłączasz aplikację do KSeF (Krajowy System e-Faktur), pierwsze pytanie nie brzmi „jak wysłać fakturę", tylko „jak się w ogóle zalogować i kto ma do czego prawo". Uwierzytelnianie, uprawnienia i zawiadomienie ZAW-FA razem decydują o tym, czy integracja będzie ci działać — i czy będzie działać także po 1 stycznia 2027. Oto przegląd, co jest czym.

Jak zalogować się do KSeF

KSeF zna kilka sposobów uwierzytelnienia. Dla człowieka przy ekranie i dla maszyny istotne są inne.

• Kwalifikowany podpis elektroniczny — należy do osoby fizycznej. Ma moc prawną podpisu własnoręcznego i opiera się na kwalifikowanym certyfikacie. Służy do logowania i podpisu.
• Kwalifikowana pieczęć elektroniczna — identyfikuje organizację, a nie konkretną osobę. Dla firmy to najczystsza droga: jeśli pieczęć zawiera NIP podmiotu, firma uzyskuje dostęp sama, bez składania ZAW-FA.
• Profil Zaufany (podpis zaufany) — profil zaufany dla osoby fizycznej.
• Token — ciąg znaków, który niesie uprawnienia zadeklarowane w momencie wygenerowania. Używa się go do logowania maszynowego/integracyjnego z aplikacji komercyjnych.
• Certyfikat KSeF — wydawany jest wewnątrz KSeF i jest to wyłącznie środek uwierzytelniający, podobnie jak kwalifikowany podpis.

Dla podłączenia aplikacji kluczowe są dwa ostatnie: token i certyfikat KSeF. I właśnie w nich tkwi największy haczyk.

Token vs. certyfikat KSeF: na czym polega różnica

Wyglądają wymiennie, ale nimi nie są. Różnica polega na tym, gdzie żyją uprawnienia.

Token ma uprawnienia wbudowane bezpośrednio w siebie. Generujesz go z jakimś zestawem praw i te prawa nosi ze sobą. To wygodne — jeden ciąg znaków i jesteś zalogowany oraz autoryzowany.

Certyfikat KSeF uprawnień w sobie nie niesie. To czysty środek do potwierdzenia tożsamości. Prawa rozwiązuje się osobno, przez role wewnątrz KSeF (zobacz dalej). Certyfikat ma dwa funkcjonalne zastosowania: uwierzytelnianie do logowania interaktywnego i wsadowego (batch) przez API; oraz zastosowanie offline — od 1.2.2026 jest potrzebny do podpisu faktur wystawianych w trybie offline24 / przy niedostępności systemu / w trybie awaryjnym. Ważność certyfikatu to maksymalnie 2 lata od wydania (lub od daty, którą podatnik wybierze jako start).

To nie jest różnica akademicka. Decyduje o tym, jak zbudujesz model autoryzacji aplikacji i co stanie się na przełomie roku.

Termin, którego nie możesz przegapić: 1.1.2027

Token i certyfikat KSeF współistnieją od 1.2.2026. Ale nie na zawsze:

• Tokeny działają do 31.12.2026.
• Od 1.1.2027 KSeF przyjmuje już tylko certyfikaty KSeF. Tokeny przestaną działać. Integracja ustawiona wyłącznie na token po Nowym Roku nie połączy się z API i nie wyśle ani jednej faktury.

Do tego jeden szczegół, o którym łatwo zapomnieć: tokeny z KSeF 1.0 nie obowiązują w KSeF 2.0. Musisz je wygenerować ponownie, co jest możliwe od 1.2.2026.

Wniosek dla długo żyjącej integracji .NET jest jednoznaczny: token pomoże ci ruszyć z miejsca w 2026 roku, ale migrację na certyfikat KSeF zaplanuj jeszcze przed 1.1.2027. Jeśli zostawisz to na ostatnią chwilę, ryzykujesz, że fakturacja stanie ci na przełomie roku — czyli dokładnie wtedy, gdy zamyka się okres rozliczeniowy.

Role i uprawnienia

Logowanie to dopiero połowa. Druga to: kto może co robić.

Firma, która nie używa kwalifikowanej pieczęci, wskazuje osobę fizyczną mającą działać za nią w KSeF, składając zawiadomienie ZAW-FA do urzędu skarbowego (papierowo lub elektronicznie). Od 1.2.2026 obowiązuje nowa wersja ZAW-FA. W okresie obowiązkowym na podstawie złożonego ZAW-FA prawo do wystawiania faktur nadawane jest automatycznie.

Tak wskazana osoba — typowo członek zarządu, CFO lub upoważniony pracownik — może następnie wewnątrz KSeF nadawać dalsze uprawnienia (wystawianie / wgląd / zarządzanie) kolejnym użytkownikom lub oprogramowaniu księgowemu. To ważne dla integracji: twoja aplikacja nie potrzebuje, żeby logował się dyrektor. Potrzebuje własnej tożsamości (certyfikatu) i przypisanych do niej praw.

Podsumowanie, kiedy zajmować się ZAW-FA, a kiedy nie:

• Firma z kwalifikowaną pieczęcią (z NIP) → ma dostęp sama, ZAW-FA nie składa.
• Firma bez pieczęci → składa ZAW-FA, wskazuje osobę fizyczną, ta deleguje prawa dalej.

Kogo właściwie dotyczy KSeF

Żeby uwierzytelnianie miało sens, warto wiedzieć, kiedy w ogóle będzie ci potrzebne. Krótko, bo szczegóły są na osobny artykuł:

• Wystawianie jest obowiązkowe od 1.2.2026 dla dużych podatników (obrót za 2025 rok powyżej 200 mln PLN, rzędu 4 200 podmiotów), od 1.4.2026 dla pozostałych podatników VAT. Uwaga na uproszczenia: mikroprzedsiębiorcy nie mają obowiązku aż do 1.1.2027, a dodatkowo istnieje ulga przejściowa — kto fakturuje miesięcznie poza KSeF do 10 000 PLN brutto, może aż do 31.12.2026 fakturować poza systemem.
• Odbiór faktur przez KSeF jest obowiązkowy dla wszystkich podatników już od 1.2.2026, nawet jeśli sami jeszcze nie wystawiają.
• Faktura dla nabywcy zagranicznego nadal wystawiana jest w KSeF (to faktura w rozumieniu polskich przepisów); zagranicznemu nabywcy przekażesz ją poza KSeF, na przykład jako wizualizację PDF lub udostępniony link, bo do KSeF dostępu nie ma.

Wynika z tego, że tożsamości i uprawnień w KSeF będziesz potrzebować wcześniej, niż zaczniesz sam wystawiać — z powodu odbioru już od lutego 2026.

Co rozważyć przy podłączaniu aplikacji .NET

Gdy przełożę to na konkretne kroki integracji:

1. Tożsamość aplikacji. Dla integracji produkcyjnej celuj w certyfikat KSeF, nie w token. Token użyj najwyżej jako rozwiązania przejściowego na rok 2026 i od początku zakładaj wymianę przed 1.1.2027.
2. Sesja przez API. Zainicjuj sesję podpisanym XML / certyfikatem (lub tokenem do końca 2026), otrzymasz token sesji i dopiero z nim wysyłasz ustrukturyzowane faktury w formacie FA(3).
3. Uprawnienia poza certyfikatem. Ponieważ certyfikat praw nie niesie, musisz mieć rozwiązane role w KSeF (przez ZAW-FA i delegację). Sprawdź, że tożsamość aplikacji ma przypisane prawo do wystawiania / wglądu, zanim wdrożysz.
4. Ważność i odnowienie. Certyfikat jest ważny maks. 2 lata. Zaplanuj jego odnowienie jako proces, a nie jednorazowe działanie — inaczej wygaśnie ci w trakcie pracy.
5. Anti-corruption layer. Opakuj obce SDK własną warstwą, żeby jego osobliwości — ciągi błędów, kody numeryczne, TTL sesji — nie przeciekały do logiki biznesowej. Gdy SDK lub schemat się zmieni, zmieniasz jedno miejsce.
6. Durable, idempotentne wysyłanie. Każdy submit traktuj jako trwałą, idempotentną jednostkę pracy: asynchroniczne wysłanie → polling statusu → potwierdzenie UPO. Nie fire-and-forget w żądaniu HTTP.

Uwaga o załącznikach: od 1.2.2026 można wystawić fakturę z załącznikiem, ale dopiero po wcześniejszym zgłoszeniu zamiaru. Konkretną obsługę zweryfikuj względem aktualnie opublikowanego schematu FA(3), tutaj szczegóły jeszcze się ustalają.

FAQ

Jaka jest różnica między tokenem KSeF a certyfikatem KSeF?

Token ma w sobie zakodowane uprawnienia zadeklarowane w momencie jego wygenerowania. Certyfikat KSeF to wyłącznie środek uwierzytelniający i nie niesie uprawnień — te rozwiązuje się osobno przez role w KSeF. Token działa do 31.12.2026, a od 1.1.2027 KSeF przyjmuje już tylko certyfikaty.

Czym jest ZAW-FA i kiedy muszę je złożyć?

ZAW-FA to zawiadomienie do urzędu skarbowego, którym firma bez kwalifikowanej pieczęci wskazuje osobę fizyczną, która będzie działać za nią w KSeF. Jeśli firma użyje kwalifikowanej pieczęci z własnym NIP, uzyskuje dostęp sama i nie musi składać ZAW-FA.

Czy token z KSeF 1.0 działa też w KSeF 2.0?

Nie. Tokeny z KSeF 1.0 nie obowiązują w KSeF 2.0 i trzeba je wygenerować ponownie, co jest możliwe od 1.2.2026. Dla długo żyjącej integracji i tak zaplanuj przejście na certyfikat KSeF przed 1.1.2027.

Pomożemy z podłączeniem

Robimy to w praktyce. Nasza integracja KSeF działa na produkcji — ponad 40 000 dokumentów dostarczonych w 100 % — a jej częścią jest też zarządzanie tożsamościami, sesjami i odnawianiem certyfikatów. Jeśli podłączasz aplikację .NET i chcesz mieć uwierzytelnianie i role zbudowane tak, by wytrzymały także przejście na certyfikaty w styczniu 2027, napisz do nas.