W KSeF API największe problemy zwykle nie zaczynają się od samej faktury. Zaczynają się wcześniej: przy próbie ustalenia, kto właściwie loguje się do systemu, w imieniu jakiego podatnika działa i czy ma do tego realne uprawnienia. To ważna różnica, bo w integracji z KSeF samo „mamy token” albo „mamy certyfikat” nie wystarcza. System i tak sprawdzi kontekst, identyfikator, uprawnienia oraz poprawność całego procesu uwierzytelniania.
Od strony praktycznej trzeba rozdzielić dwa pojęcia. Uwierzytelnianie odpowiada na pytanie: kim jest podmiot lub osoba próbująca wejść do systemu. Autoryzacja odpowiada na pytanie: co ta osoba albo system może zrobić po zalogowaniu. W KSeF API te dwa etapy są ze sobą mocno powiązane, ale nie są tym samym. I właśnie tu najczęściej powstają błędy we wdrożeniach.
Uwierzytelnianie w KSeF API: kto się loguje i w czyim imieniu
W KSeF API 2.0 logowanie nie polega na prostym wysłaniu loginu i hasła. System wymaga wskazania kontekstu logowania oraz podmiotu uwierzytelniającego.
Kontekst logowania oznacza podmiot, w imieniu którego będą wykonywane operacje. Najczęściej będzie to firma identyfikowana przez NIP. Podmiot uwierzytelniający to natomiast osoba, firma, certyfikat albo token, który próbuje uzyskać dostęp do API. Przykład z praktyki: księgowa może logować się swoim certyfikatem, ale działać w kontekście spółki, o ile ma nadane właściwe uprawnienia.
To rozróżnienie ma konkretne konsekwencje. Jeżeli certyfikat zawiera PESEL osoby fizycznej, KSeF sprawdza, czy ta osoba może działać w imieniu wskazanej firmy. Jeżeli używany jest certyfikat z NIP organizacji, system weryfikuje dane podmiotu. Jeżeli wskazany jest odcisk palca certyfikatu, uprawnienia muszą być powiązane właśnie z tym certyfikatem.
Najważniejsza zasada: dostęp techniczny nie zastępuje uprawnień biznesowych. Integracja może poprawnie podpisać żądanie, prawidłowo zaszyfrować token i trafić w dobry endpoint, a mimo to nie uzyskać dostępu, jeśli podmiot uwierzytelniający nie ma aktywnego uprawnienia do danego kontekstu.
Przed wdrożeniem warto więc sprawdzić trzy rzeczy, w tej kolejności:
- czy wybrany NIP / kontekst jest właściwy dla operacji,
- czy osoba, podmiot albo certyfikat ma nadane aktywne uprawnienia,
- czy środowisko testowe, demo i produkcyjne nie są mylone w konfiguracji.
Ten ostatni punkt brzmi banalnie, ale w integracjach robi sporo szkód. Środowisko produkcyjne KSeF działa na rzeczywistych danych i rzeczywistych uprawnieniach. Faktury wystawione produkcyjnie mają skutki prawne. Testy „na szybko” w produkcji to zły pomysł, szczególnie gdy zespół dopiero dopina obsługę sesji, błędów i limitów API.
Certyfikat, podpis XAdES czy token KSeF: którą metodę wybrać
KSeF API 2.0 przewiduje dwie główne ścieżki uwierzytelniania technicznego: przez podpis XAdES albo przez token KSeF. W praktyce wybór metody powinien zależeć od tego, czy mówimy o jednorazowym dostępie użytkownika, stabilnej integracji systemowej, pracy biura rachunkowego czy obsłudze wielu podmiotów.
Pierwsza metoda to podpisanie dokumentu AuthTokenRequest w formacie XAdES. Do podpisu można wykorzystać m.in.:
- kwalifikowany certyfikat osoby fizycznej zawierający PESEL albo NIP,
- kwalifikowaną pieczęć organizacji zawierającą NIP,
- Profil Zaufany,
- certyfikat KSeF,
- certyfikat dostawcy usług Peppol.
W produkcyjnej integracji najlepiej unikać założenia, że każdy podpis kwalifikowany zadziała równie szybko. Przy certyfikatach kwalifikowanych system może sprawdzać status certyfikatu u wystawcy przez OCSP/CRL. To normalne, ale oznacza, że status uwierzytelniania może przez chwilę wisieć jako „w toku”. Jeżeli system ma działać automatycznie i powtarzalnie, certyfikat KSeF typu 1 jest zwykle bardziej praktycznym wyborem, bo jego weryfikacja odbywa się wewnątrz KSeF.
Druga metoda to uwierzytelnianie tokenem KSeF. Tu nie wysyła się tokena wprost. API wymaga przygotowania ciągu:
tokenKSeF|timestampMs
Następnie taki ciąg trzeba zaszyfrować kluczem publicznym KSeF z użyciem RSA-OAEP i SHA-256 MGF1, a wynik zakodować w Base64. Dopiero taki zaszyfrowany token trafia do żądania uwierzytelniającego.
To nie jest detal implementacyjny, który można zostawić „na potem”. Jeżeli zespół źle obsłuży timestamp z challenge, kodowanie, algorytm szyfrowania albo klucz publiczny dla środowiska, logowanie będzie się wykładać zanim aplikacja dojdzie do obsługi faktur.
Decyzja praktyczna wygląda tak:
- dla automatycznej integracji produkcyjnej priorytetem powinien być certyfikat KSeF typu 1,
- dla testów i pierwszego prototypu można zacząć od środowiska testowego i oficjalnych bibliotek,
- dla organizacji z wieloma spółkami lub biura rachunkowego trzeba najpierw uporządkować uprawnienia i konteksty NIP, a dopiero potem budować automatyzację,
- dla ręcznych operacji użytkownika podpis kwalifikowany albo Profil Zaufany może być wystarczający, ale gorzej pasuje do procesów bezobsługowych.
Certyfikat KSeF też ma ograniczenia. Jest ważny maksymalnie 2 lata od daty wytworzenia albo od wskazanej daty początkowej obowiązywania. Są też różne typy certyfikatów: typ 1 służy do uwierzytelniania, a typ 2 do trybów offline. Nie da się zastąpić jednego drugim ani wygenerować jednego certyfikatu „do wszystkiego”. To trzeba uwzględnić w procedurze utrzymaniowej, bo wygaśnięcie certyfikatu w firmie z dużą liczbą faktur nie jest drobną niedogodnością. To potencjalny przestój w wystawianiu dokumentów.
Jak wygląda pełny proces techniczny: challenge, accessToken i refreshToken
Proces uwierzytelniania w KSeF API jest asynchroniczny. To ważne, bo aplikacja nie powinna zakładać, że po jednym żądaniu od razu ma pełny dostęp do systemu.
Pierwszy krok to pobranie auth challenge przez endpoint:
POST /auth/challenge
Challenge jest elementem wymaganym do dalszego uwierzytelniania i ma krótki czas życia: 10 minut. W odpowiedzi API zwraca challenge oraz timestamp. Jeżeli aplikacja pobierze challenge, a potem użytkownik przez kilka minut szuka certyfikatu, przełącza kartę albo czeka na podpis, proces może się po prostu przeterminować. W dobrym wdrożeniu trzeba to obsłużyć komunikatem i ponownym pobraniem challenge, a nie ogólnym błędem „autoryzacja nieudana”.
Drugi krok zależy od metody.
Przy XAdES aplikacja przygotowuje XML AuthTokenRequest, wskazuje m.in. challenge, kontekst logowania oraz sposób identyfikacji podmiotu, a potem podpisuje dokument. Podpisany XML trafia do:
POST /auth/xades-signature
Przy tokenie KSeF aplikacja szyfruje token wraz z timestampem i wysyła żądanie do:
POST /auth/ksef-token
W obu wariantach odpowiedź nie jest jeszcze docelowym dostępem do API. System zwraca authenticationToken oraz referenceNumber. Te dane służą do sprawdzenia statusu operacji. Status pobiera się przez:
GET /auth/{referenceNumber}
Dopiero gdy uwierzytelnianie zakończy się sukcesem, aplikacja wywołuje:
POST /auth/token/redeem
Tu pojawia się właściwa para tokenów:
- accessToken — token JWT używany w nagłówku
Authorization: Bearer ..., - refreshToken — token do odświeżania dostępu bez przechodzenia całego procesu od nowa.
AccessToken ma krótki czas życia, zwykle liczony w kilkunastu minutach i określony w polu exp. RefreshToken jest ważny dłużej — do 7 dni — i może służyć do pobierania nowych accessTokenów. Odświeżanie odbywa się przez:
POST /auth/token/refresh
Tu pojawia się ważne ostrzeżenie: accessToken i refreshToken są danymi poufnymi. Nie powinny trafiać do logów aplikacyjnych, historii błędów, narzędzi analitycznych ani zgłoszeń helpdeskowych w pełnej postaci. Jeżeli trzeba debugować integrację, lepiej logować identyfikatory operacji, statusy, kody błędów i skrócone fragmenty tokenów, a nie pełne sekrety.
Druga rzecz: token dostępu może pozostać ważny do czasu wskazanego w exp, nawet jeśli uprawnienia użytkownika zmienią się w międzyczasie. To ma znaczenie przy odbieraniu dostępu pracownikom, zmianach w biurze rachunkowym albo rotacji operatorów systemu. Samo odebranie uprawnienia nie musi natychmiast zatrzymać już wydanego accessTokena. Dlatego proces bezpieczeństwa powinien obejmować nie tylko nadawanie uprawnień, ale też kontrolę sesji, rotację tokenów i sensowne czasy odświeżania.
Warto też zaplanować obsługę limitów API. KSeF 2.0 ma limity żądań, które mają chronić stabilność systemu. Przy dużych wolumenach faktur integrator może wnioskować o indywidualne dostosowanie limitów, ale taki wniosek powinien wynikać z realnej potrzeby operacyjnej, a nie z tego, że aplikacja odpytuje API zbyt często. Najpierw trzeba ograniczyć puste zapytania, dodać kolejkę, retry z odstępami i kontrolę statusów. Dopiero potem ma sens rozmowa o podniesieniu limitów.
Najczęstszy błąd we wdrożeniach? Traktowanie uwierzytelniania jako jednego endpointa. W KSeF to raczej mały proces: challenge, podpis albo zaszyfrowany token, status, redeem, przechowywanie accessTokena, odświeżanie, obsługa wygaśnięcia i błędów. Jeżeli każdy z tych kroków nie ma własnej obsługi, integracja będzie działała tylko w idealnych warunkach.
FAQ: najczęstsze pytania o autoryzację i uwierzytelnianie w KSeF API
Czy uwierzytelnianie i autoryzacja w KSeF API oznaczają to samo?
Nie. Uwierzytelnianie potwierdza, kto próbuje uzyskać dostęp. Autoryzacja określa, jakie operacje ta osoba, podmiot albo system może wykonać po zalogowaniu.
Czy sam certyfikat wystarczy do korzystania z KSeF API?
Nie. Certyfikat potwierdza tożsamość, ale KSeF sprawdza jeszcze uprawnienia do kontekstu, np. do działania w imieniu firmy o konkretnym NIP.
Jak długo ważny jest challenge w KSeF API?
Challenge jest ważny 10 minut. Po tym czasie proces trzeba rozpocząć ponownie od pobrania nowego challenge.
Czym różni się authenticationToken od accessToken?
AuthenticationToken jest tokenem tymczasowym używanym w trakcie procesu uwierzytelniania. AccessToken to właściwy token JWT używany później do autoryzacji operacji w API.
Jak długo działa refreshToken?
RefreshToken może być ważny do 7 dni i służy do odświeżania accessTokena bez ponownego przechodzenia całego procesu logowania.
Czy certyfikat KSeF jest tym samym co podpis kwalifikowany?
Nie. Certyfikat KSeF jest wydawany przez system KSeF i służy do użycia w KSeF. Nie jest certyfikatem kwalifikowanym, ale jest honorowany w procesie uwierzytelniania.
Który certyfikat KSeF służy do logowania przez API?
Do uwierzytelniania służy certyfikat KSeF typu 1. Certyfikat typu 2 jest przeznaczony do trybów offline i nie zastępuje certyfikatu uwierzytelniającego.
Czy tokeny można zapisywać w logach aplikacji?
Nie. AccessToken, refreshToken i token KSeF trzeba traktować jak dane poufne. W logach powinny znaleźć się co najwyżej statusy, numery referencyjne i techniczne identyfikatory błędów.
Od czego zacząć wdrożenie autoryzacji w KSeF API?
Najpierw uporządkuj uprawnienia i konteksty NIP, potem wybierz metodę uwierzytelniania, a dopiero na końcu automatyzuj sesje i odświeżanie tokenów. Odwrotna kolejność zwykle kończy się integracją, która działa tylko na koncie testowym jednej osoby.
Więcej na stronie: integracja z KSeF.