KSeF 21111: nieprawidłowe wyzwanie autoryzacyjne. Przyczyny i poprawka w integracji
Kod 21111 w KSeF oznacza, że podpisane lub zaszyfrowane wyzwanie nie pasuje do wydanego. Zwykle wygasło po 10 minutach. Pokazuję, jak to naprawić.
Wyjątek 21111 „Nieprawidłowe wyzwanie autoryzacyjne” pojawia się na samym początku pracy z KSeF, przy logowaniu programu. To błąd techniczny integracji, a nie uprawnień czy danych na fakturze. Użytkownik nic tu nie poprawi w karcie klienta. Trzeba sprawdzić, co program robi z wyzwaniem (challenge), które dostaje od KSeF.
Czym jest wyzwanie autoryzacyjne
Logowanie do API KSeF 2.0 zaczyna się od pobrania wyzwania: jednorazowej wartości i znacznika czasu. Program musi potwierdzić, że to on je otrzymał. Przy podpisie kwalifikowanym albo certyfikacie KSeF wstawia wyzwanie do dokumentu XML AuthTokenRequest i podpisuje go w formacie XAdES. Przy tokenie KSeF szyfruje ciąg „token|znacznik czasu w milisekundach” kluczem publicznym KSeF algorytmem RSA-OAEP z SHA-256. Wyzwanie żyje 10 minut.
Najczęstsze przyczyny błędu 21111
Wyzwanie wygasło. Między pobraniem wyzwania a odesłaniem podpisu minęło ponad 10 minut. Zdarza się przy ręcznym podpisie, gdy ktoś odchodzi od komputera w trakcie logowania.
Podpisano inne wyzwanie. Program pobrał nowe wyzwanie, ale do podpisu wziął poprzednie, zapisane w pamięci podręcznej albo w pliku.
Wyzwanie z innego środowiska. Pobrane z KSeF testowego, wysłane na produkcję albo odwrotnie.
Zły znacznik czasu przy tokenie. Do szyfrowania użyto lokalnego czasu serwera zamiast znacznika z odpowiedzi KSeF albo podano go w sekundach zamiast w milisekundach.
Wielokrotne użycie. Ten sam podpisany dokument wysłany drugi raz, np. przy automatycznym ponowieniu po timeoucie.
Jak naprawić 21111
1
Zawsze świeże wyzwanie
Każda próba logowania zaczyna się od nowego wywołania po challenge, bez cache.
2
Znacznik czasu z odpowiedzi KSeF
Do tokena dołączasz timestamp z wyzwania, w milisekundach, a nie czas serwera.
3
Ponowienie od początku
Po błędzie logowania integracja pobiera nowe wyzwanie, zamiast wysyłać stary podpis drugi raz.
21111 a status 450 przy uwierzytelnieniu
Ta sama przyczyna może wrócić w innym miejscu: jako status uwierzytelnienia 450 z opisem „nieprawidłowe wyzwanie autoryzacyjne”. Różnica polega na tym, kiedy KSeF to wykrył. Wyjątek 21111 to odrzucenie żądania od razu, status 450 to wynik weryfikacji po przyjęciu żądania. Naprawa jest w obu przypadkach ta sama. Pozostałe statusy logowania opisałem w tekście o błędzie uwierzytelnienia, a sąsiednie kody wyjątków w przeglądzie błędów KSeF.
21470: identyfikator klucza nieznany albo wskazuje na wycofany klucz. Program szyfruje starym kluczem publicznym KSeF i musi pobrać aktualny.
21117: nieprawidłowy identyfikator podmiotu dla wskazanego typu kontekstu, np. NIP podany w polu przeznaczonym na identyfikator VAT UE.
Jak odtworzyć błąd 21111 na środowisku testowym
Najprostszy test poprawki: na środowisku testowym pobierz wyzwanie, odczekaj ponad 10 minut i dopiero wtedy wyślij podpis. KSeF powinien zwrócić 21111, a integracja powinna sama pobrać nowe wyzwanie i zalogować się poprawnie przy drugiej próbie. Drugi test to wysłanie tego samego podpisanego dokumentu dwa razy. Jeśli w logach widać, że po błędzie integracja ponawia stare żądanie, zamiast zaczynać od nowego wyzwania, poprawka nie jest kompletna.
Pośrednio tak, jeśli program używa czasu serwera zamiast znacznika z odpowiedzi KSeF. Przy poprawnej implementacji lokalny zegar nie ma znaczenia dla wyzwania.
›Ile razy mogę użyć jednego wyzwania?
Jedno wyzwanie służy jednej próbie logowania. Każde ponowienie zaczyna się od pobrania nowego.
›Czy ten błąd blokuje wysyłkę faktur ze sklepu?
Tak, bez logowania program nie otworzy sesji. Faktury powinny czekać w kolejce, jak w integracji KSeF z WooCommerce.
›Czy 21111 pojawia się przy logowaniu przez Aplikację Podatnika?
Zwykle nie, bo aplikacja MF sama obsługuje wyzwanie. Błąd 21111 dotyczy głównie programów i integracji, które logują się przez API.
Chcesz przegadać swój projekt?
Odpowiadam osobiście w ciągu 24h w dni robocze — bez handlowca po drodze.