E-Invoice Finder
Menu
Kraje Oprogramowanie Terminy Przewodniki Checker Sprawdź obowiązek
ENFRDEPLNL
Polska · zmiana uwierzytelniania KSeF

Migracja z tokenu KSeF na certyfikat w ERP i API

Przenieś integracje ERP i API z tokenów KSeF na certyfikaty uwierzytelniające przed 2027 r. z testami, kontrolą uprawnień i rollbackiem.

Praktyczne podsumowanie:
  • Termin: 31 grudnia 2026 r. to ostatni dzień planowanego użycia tokenów systemowych.
  • Zakres: policz kontenery, automaty wsadowe i ścieżki awaryjne odczytujące sekret.
  • Działanie: otwórz produkcję dopiero po wspólnej zgodzie finansów, IT i właściciela usługi.
Sprawdź raport gotowościŹródła oficjalne
Ostatnia aktualizacja: 3 sierpnia 2026Źródła oficjalneJasne podsumowanieInformacja praktyczna, nie porada prawna
Priorytet dla źródeł oficjalnych
Widoczne daty weryfikacji
Darmowy checker bez rejestracji

Co warto wiedzieć

Przewodnik

Termin i rzeczywista zmiana architektury

Według Ministerstwa Finansów tokeny KSeF i certyfikaty KSeF można stosować od 1 lutego 2026 r., lecz od 1 stycznia 2027 r. pozostaje uwierzytelnianie certyfikatami. Nie ma oficjalnego dodatkowego okresu przejściowego po tej dacie. Migracja nie jest automatyczną konwersją tokenu: token systemowy zawiera uprawnienia zadeklarowane przy jego generowaniu, natomiast certyfikat potwierdza tożsamość, a KSeF zarządza uprawnieniami i sprawdza je po stronie serwera. Certyfikat nie niesie też kontekstu firmy; kontekst wskazuje żądanie logowania, po czym system weryfikuje co najmniej jedno aktywne uprawnienie. Zmiana obejmuje zatem kod konektora, obsługę podpisu XAdES, magazyn klucza prywatnego, konfigurację kontekstu, nadane prawa, telemetrię i procedurę wdrożenia. W harmonogramie cofnij się od gotowości przed końcem 2026 r., zostawiając czas na poprawki dostawcy, testy nieprodukcyjne i bezpieczne wdrożenie. To zalecany sposób zarządzania zmianą, a nie urzędowo narzucony plan migracji.

Przewodnik

Zmapuj zależności tokenowe i ustal bazę uprawnień

Najpierw utwórz listę każdego miejsca, w którym token KSeF jest generowany, przechowywany, wstrzykiwany lub odczytywany: instancji ERP, middleware, funkcji chmurowych, zadań nocnych, narzędzi RPA, skryptów wsparcia, środowisk testowych i procedur awaryjnych. Dla każdej zależności zapisz podmiot i kontekst, właściciela biznesowego, opiekuna technicznego, wykonywane operacje, wolumen, okno pracy, miejsce sekretu oraz skutek awarii. Administrator uprawnień KSeF powinien równolegle udokumentować obecną bazę: jakie prawa zawiera token i jakie aktywne uprawnienia serwerowe będą potrzebne po przejściu na certyfikat. Nie kopiuj mechanicznie nadmiarowego zakresu. Przykład: SAP wysyła faktury trzech spółek przez wspólny broker, a nocny proces pobiera UPO. Mimo jednego komponentu każda ścieżka ma własny kontekst NIP, kolejkę i kryterium odbioru. Dowodem inwentaryzacji jest zatwierdzona macierz system–kontekst–operacja–uprawnienie–sekret, uzgodniona przez finanse, właściciela ERP i zespół integracji.

Przewodnik

Wybierz Typ 1, uzyskaj certyfikat i zabezpiecz klucz

Do uwierzytelniania ERP lub klienta API wybierz certyfikat KSeF Typu 1 Uwierzytelnianie. Typ 2 Offline jest wydawany osobno i służy wyłącznie do potwierdzania tożsamości wystawcy oraz integralności faktury w trybach offline24, niedostępności systemu i awaryjnym; nie zaloguje sesji API. Przed wnioskowaniem ustal właściciela certyfikatu, jednoznaczną nazwę, środowisko, system docelowy i osobę zatwierdzającą. Dane potrzebne do enrollmentu certyfikatu można uzyskać dopiero po uwierzytelnieniu XAdES, nie po logowaniu tokenem KSeF, więc tę zdolność trzeba zapewnić w procesie wydania. Klucz prywatny generuj i przechowuj w kontrolowanym magazynie sekretów albo HSM zgodnym z architekturą aplikacji; nie umieszczaj go w repozytorium, obrazie kontenera, tickecie ani logu. Rozdziel uprawnienie do wydania, wdrożenia i użycia klucza. Pakiet dowodowy powinien zawierać metadane wniosku, numer seryjny, przypisanie właściciela i potwierdzenie bezpiecznego wdrożenia, ale nigdy materiał kluczowy.

Przewodnik

Zaimplementuj XAdES i właściwie obsłuż tokeny sesyjne

Przepływ certyfikatowy zaczyna się od POST /auth/challenge. Aplikacja buduje AuthTokenRequest z wybranym kontekstem, podpisuje go certyfikatem w formacie XAdES i przesyła zgodnie z aktualną dokumentacją API; oficjalny opis wskazuje, że oprogramowanie komercyjne potrzebuje obsługi XAdES-BES. Po poprawnym uwierzytelnieniu integracja uzyskuje tymczasowe tokeny uwierzytelniania, dostępu i odświeżania wymagane do pracy sesji. Długoterminowy certyfikat nie zastępuje więc accessToken ani refreshToken i nie powinien być wysyłany przy każdym wywołaniu biznesowym. Dotychczasowa ścieżka tokenowa jest inna: szyfruje token systemowy KSeF i kieruje go do POST /auth/ksef-token. Zaimplementuj obie ścieżki za przełącznikiem konfiguracji tylko na czas kontrolowanej migracji, wspólnie wykorzystując bezpieczną obsługę tokenów sesyjnych, odświeżanie, wygaszanie i ponawianie. Logi powinny rozróżniać błąd podpisu, kontekstu, aktywnego uprawnienia i sesji, ale maskować klucz, podpis, token KSeF oraz pełne JWT.

Przewodnik

Macierz testów i dowody gotowości

Lider QA wraz z finansami i zespołem integracji powinien zatwierdzić macierz obejmującą środowisko, kontekst, operację, oczekiwany wynik i właściciela reakcji. Testy pozytywne powinny sprawdzić challenge, podpisany AuthTokenRequest, uzyskanie i odświeżenie tokenów sesyjnych, wysłanie faktury, pobranie statusu oraz operacje odczytowe rzeczywiście używane przez ERP. Testy negatywne obejmują niewłaściwy certyfikat, błędny kontekst, brak aktywnego uprawnienia, wygaśnięty accessToken, nieskuteczny refreshToken, utratę dostępu do klucza, timeout i ponowienie bez duplikacji. Dodaj test obciążenia w typowym szczycie oraz kontrolę, że sekrety nie trafiają do logów. Dla przykładowego brokera SAP sprawdź każdą spółkę osobno i przerwij test, jeśli wynik zostanie przypisany do złego kontekstu. Dowody to identyfikatory żądań, znaczniki czasu, zanonimizowane statusy, wersja konektora, konfiguracja funkcji oraz podpisane wyniki; nie archiwizuj prywatnych kluczy ani pełnych tokenów.

Przewodnik

Praca równoległa, canary i monitoring produkcji

Równoległe utrzymanie ścieżki tokenowej i certyfikatowej jest praktyką migracyjną firmy, a nie wymaganym przez KSeF okresem o określonej długości. Najpierw włącz certyfikat dla kontrolowanego canary: jednej instancji konektora, jednej spółki lub ograniczonego rodzaju operacji, bez podwójnego wysyłania tej samej faktury. Release manager ustala okno, właściciel finansowy potwierdza zakres dokumentów, a dyżurny techniczny obserwuje wynik. Monitoruj skuteczność uwierzytelnień, czas uzyskania sesji, błędy XAdES, odmowy uprawnień, odświeżenia JWT, zaległość kolejek, liczbę ponowień i dokumenty bez oczekiwanego statusu. Porównuj te wskaźniki z bazą ścieżki tokenowej i oddziel awarie KSeF od błędów nowej implementacji. Canary można rozszerzyć dopiero po osiągnięciu ustalonego wolumenu bez krytycznego błędu i po uzgodnieniu księgowym. Alarm musi wskazywać osobę, kanał eskalacji i instrukcję zatrzymania, a obserwacje powinny trafić do protokołu decyzji.

Przewodnik

Przełączenie oraz decyzja o rollbacku

Podziel wykonanie na fazy: 0 — inwentaryzacja i baza uprawnień; 1 — certyfikat, klucz i implementacja XAdES; 2 — testy nieprodukcyjne; 3 — canary; 4 — stopniowe przełączenie; 5 — stabilizacja i wycofanie tokenu. Przed fazą 4 wprowadź krótki wewnętrzny freeze zmian konektora, potwierdź backup konfiguracji i przećwicz powrót. Decyzję go/no-go podejmują wspólnie właściciel procesu fakturowania, lider integracji i release manager na podstawie wyników testów, stanu kolejek, dostępności zespołu oraz braku niewyjaśnionych błędów autoryzacji. Kryteria rollbacku mogą obejmować seryjne nieudane logowania, rosnącą kolejkę, ryzyko błędnego kontekstu albo brak możliwości odświeżania sesji. Powrót do tokenu KSeF jest tylko tymczasową opcją przed zakończeniem jego obsługi; nie stanowi planu po 1 stycznia 2027 r. Po rollbacku zabezpiecz zaległe dokumenty, zapisz przyczynę, cofnij wyłącznie zmienione komponenty i otwórz poprawkę z nowym odbiorem.

Przewodnik

Wycofaj stare sekrety i unikaj typowych pomyłek

Po przełączeniu zachowaj token tylko przez wewnętrznie zatwierdzony czas stabilizacji, jeśli nadal jest potrzebny do realnego rollbacku przed końcem wsparcia. Następnie potwierdź w telemetrii i skanach konfiguracji, że żadna aplikacja go nie odczytuje, unieważnij token KSeF, usuń jego kopie z sejfów, zmiennych CI/CD, konfiguracji i procedur oraz zamknij powiązane dostępy. Właściciel bezpieczeństwa dokumentuje unieważnienie, a właściciel usługi zatwierdza kompletność usunięcia. Najczęstsze błędy to uznanie certyfikatu za „nowy token”, założenie automatycznego przeniesienia uprawnień, użycie Typu 2 do logowania, pominięcie kontekstu firmy, mylenie tokenu KSeF z krótkotrwałymi JWT oraz usunięcie starego sekretu przed sprawdzeniem wszystkich zadań wsadowych. Ryzykiem jest też trwałe pozostawienie podwójnej ścieżki, która zwiększa powierzchnię dostępu i utrudnia diagnostykę. Zamknięcie migracji wymaga dowodu unieważnienia, czystego skanu zależności i aktualnej instrukcji operacyjnej bez ścieżki tokenowej.

Przewodnik

Kryteria wyboru oprogramowania i następne kroki

Dostawcę ERP lub konektora oceniaj na demonstracji pełnego przepływu, nie na deklaracji „obsługuje certyfikaty”. Wymagaj POST /auth/challenge, XAdES-BES dla AuthTokenRequest, poprawnej obsługi accessToken i refreshToken, wyboru kontekstu, diagnostyki uprawnień, integracji z kontrolowanym magazynem kluczy oraz logów bez sekretów. Produkt powinien pozwalać uruchomić ścieżki za przełącznikiem, wdrożyć canary, obserwować osobne metryki, przeprowadzić rollback i eksportować dowody. Zapytaj o wersje obsługiwanej dokumentacji API, terminy poprawek, SLA, role administracyjne, przenośność klucza, pracę wielu spółek, testy obciążeniowe i sposób zakończenia umowy. Odrzuć rozwiązanie, które wymaga Typu 2 do sesji, traktuje certyfikat jak nośnik praw albo nie rozróżnia tokenu systemowego od JWT. Następny krok to warsztat właścicieli, dwutygodniowy proof of concept na rzeczywistych scenariuszach bez danych produkcyjnych, ocena luk i zatwierdzenie faz 0–5 z terminami, budżetem oraz mierzalnymi kryteriami odbioru.

Lista kontrolna

Wyznacz właściciela biznesowego, lidera integracji, administratora uprawnień, opiekuna klucza i release managera.

Zinwentaryzuj wszystkie aplikacje, zadania wsadowe, środowiska i procedury korzystające z tokenu KSeF.

Uzgodnij dla każdego kontekstu minimalny zestaw aktywnych uprawnień potrzebnych po migracji.

Uzyskaj certyfikat Typu 1 i umieść klucz prywatny w kontrolowanym magazynie bez eksportu do plików roboczych.

Dodaj przepływ /auth/challenge, podpis XAdES-BES oraz bezpieczną obsługę accessToken i refreshToken.

Wykonaj testy pozytywne, negatywne, obciążeniowe i awaryjne dla każdego podmiotu oraz krytycznej operacji.

Uruchom canary bez podwójnej wysyłki faktur i monitoruj autoryzację, kolejki, statusy oraz ponowienia.

Zatwierdź kryteria go/no-go, progi rollbacku, okno zmiany, freeze i osoby dostępne podczas wdrożenia.

Po stabilizacji unieważnij token KSeF i usuń jego kopie ze wszystkich sejfów, konfiguracji oraz instrukcji.

Zamknij zmianę pakietem dowodów zawierającym akceptacje, wyniki testów, metryki i potwierdzenie usunięcia sekretu.

Najczęstsze pytania

Do kiedy można używać tokenów KSeF?

Ministerstwo Finansów wskazuje, że tokeny KSeF i certyfikaty KSeF działają równolegle od 1 lutego 2026 r., a od 1 stycznia 2027 r. pozostają wyłącznie certyfikaty. Nie należy planować produkcyjnego fallbacku do tokenu po tej dacie ani zakładać nieogłoszonego okresu łaski. Wewnętrzny harmonogram powinien zakończyć migrację wcześniej, aby pozostał czas na usunięcie błędów.

Czy token KSeF można zamienić na certyfikat automatycznie?

Nie. To dwa odmienne mechanizmy i nie istnieje automatyczna konwersja zachowująca konfigurację tokenu. Trzeba uzyskać właściwy certyfikat, zabezpieczyć jego klucz, wdrożyć uwierzytelnianie XAdES, sprawdzić uprawnienia po stronie KSeF, przetestować sesje oraz w sposób kontrolowany przełączyć aplikację. Stary token wycofuje się dopiero po potwierdzonym sukcesie.

Jaki certyfikat jest potrzebny integracji ERP z API?

Do uwierzytelniania sesji ERP/API służy certyfikat KSeF Typu 1 Uwierzytelnianie. Typ 2 Offline jest osobnym certyfikatem przeznaczonym do potwierdzania tożsamości wystawcy i integralności faktury w trybach offline24, niedostępności i awaryjnym. Typ 2 nie może otworzyć sesji API, nawet jeśli aplikacja potrafi użyć jego klucza.

Czy certyfikat KSeF zawiera uprawnienia i NIP firmy?

Nie. Certyfikat jest poświadczeniem tożsamości, nie nośnikiem uprawnień ani kontekstu przedsiębiorstwa. Kontekst, na przykład właściwy NIP, wskazuje żądanie uwierzytelnienia, a KSeF sprawdza po stronie serwera, czy istnieje co najmniej jedno aktywne uprawnienie. Dlatego ważny certyfikat może poprawnie podpisać żądanie, które mimo to nie otrzyma dostępu do oczekiwanej operacji.

Jak wygląda logowanie certyfikatem bez mylenia tokenów?

Integracja pobiera challenge przez POST /auth/challenge, przygotowuje AuthTokenRequest dla wybranego kontekstu i podpisuje go XAdES przy użyciu Typu 1. Następnie otrzymuje tymczasowe tokeny potrzebne do ustanowienia i utrzymania sesji, w tym token dostępu i odświeżania. Są to tokeny sesyjne JWT, a nie dawny token systemowy KSeF używany w odrębnym POST /auth/ksef-token.

Jak przetestować zmianę bez przestoju i podwójnych faktur?

Zachowaj oddzielne ścieżki uwierzytelnienia za przełącznikiem i uruchom certyfikat dla jednej instancji, spółki albo kontrolowanej grupy operacji. Kieruj dany dokument tylko jedną ścieżką, używając idempotencji i obserwując kolejkę, statusy, odrzucenia oraz czas sesji. Dopiero po uzgodnieniu wyników przez finanse i IT zwiększaj udział ruchu; długość próby ustala firma według ryzyka.

Kiedy rollback do tokenu jest dopuszczalny?

Rollback może być praktycznym środkiem ograniczającym przerwę wyłącznie wtedy, gdy token nadal jest wspierany, aktywny, bezpieczny i objęty zatwierdzonym planem przed 1 stycznia 2027 r. Powinien uruchamiać go wskazany decydent po przekroczeniu mierzalnego progu, na przykład narastaniu kolejki lub seryjnych błędach sesji. Po powrocie trzeba udokumentować przyczynę, naprawić implementację i ponownie przejść odbiór.

Kiedy można usunąć stary token i jakie dowody zachować?

Usuń go po udanym przełączeniu wszystkich znanych zależności, zakończeniu okresu obserwacji, przejrzeniu telemetrii i formalnej decyzji, że fallback nie jest już potrzebny. Najpierw unieważnij token w KSeF, potem usuń kopie z sejfów, potoków wdrożeniowych, konfiguracji i instrukcji. Zachowaj akceptację, wyniki skanu zależności, metryki stabilizacji oraz potwierdzenie unieważnienia, lecz nie wartość sekretu.

Kluczowe przepisy, formaty i pojęcia

Komisja EuropejskaEN 16931Dyrektywa 2014/55/UEustrukturyzowana faktura elektronicznaMigracja z tokenów KSeF na certyfikaty w integracjach ERP i APIPolska

Czytaj dalej

Źródła oficjalne

Priorytetowo traktujemy oficjalne źródła rządowe i UE, gdy są dostępne, oraz pokazujemy daty weryfikacji.