Program nie może wysłać faktur do Krajowego Systemu e-Faktur (KSeF). W historii wysyłki albo w logu jest kod 21470 i komunikat „Przesłany identyfikator klucza jest nieznany lub wskazuje na wycofany klucz.” W szczegółach stoi jeszcze „Klucz o identyfikatorze {keyId} nie jest wspierany.”, gdzie zamiast {keyId} widać konkretny identyfikator.
Poniżej wyjaśniamy prostymi słowami, o jaki klucz chodzi, dlaczego nie musisz poprawiać faktur i co przekazać dostawcy programu. Inne kody opisujemy na pełnej liście kodów błędów KSeF.
Co oznacza kod 21470
21470 to kod wyjątku, który KSeF zwraca razem z odpowiedzią HTTP 400 przy otwieraniu sesji interaktywnej (POST /sessions/online). Odpowiedź ma trzy pola: ExceptionCode (tu 21470), ExceptionDescription (opis błędu) i Details (szczegóły z identyfikatorem klucza).
To nie jest status faktury ani status sesji. Sesja w ogóle się nie otworzyła. Żadna faktura z tej wysyłki nie dotarła więc do KSeF.
O jaki klucz chodzi
Każda faktura trafia do KSeF zaszyfrowana. Program tworzy dla każdej sesji nowy, jednorazowy klucz AES-256 i nim szyfruje faktury. Ten klucz program szyfruje z kolei kluczem publicznym Ministerstwa Finansów, tak, żeby odczytać go mogło tylko MF. Przy otwieraniu sesji program podaje identyfikator klucza publicznego, którego użył.
MF co jakiś czas wymienia swoje klucze publiczne, a stare wycofuje. Jeśli program poda identyfikator klucza, którego KSeF nie zna albo który już wycofano, sesja nie zostanie otwarta. Stąd 21470.
Ważne: to klucz Ministerstwa Finansów, wspólny dla wszystkich użytkowników KSeF. Nie ma związku z Twoim tokenem KSeF ani z certyfikatem, którym logujesz się do systemu. Nowy token tego błędu nie naprawi.
Najczęstsze przyczyny
1. Program trzyma stary klucz w pamięci
Program pobrał kiedyś listę kluczy MF i korzysta z niej bez odświeżania. Po wymianie klucza przez MF dalej podaje identyfikator starego.
Jak rozpoznać: wysyłka długo działała bez zarzutu, a teraz nagle nie otwiera się żadna sesja. Błąd dotyczy wszystkich klientów naraz, bo klucz jest wspólny dla wszystkich NIP-ów. Treść faktur nie ma znaczenia.
2. Klucz wpisany na stałe w programie
Jeśli integracja ma klucz MF albo jego identyfikator wpisany na stałe w kodzie lub w konfiguracji, działa tylko do pierwszej wymiany klucza.
Jak rozpoznać: masz starszą wersję programu, a dostawca wydał niedawno aktualizację. Biura, które ją zainstalowały, wysyłają bez problemu.
3. Błąd w nowej integracji
Jeśli 21470 pojawia się od pierwszej próby i wysyłka nigdy nie działała, program podaje identyfikator, który nie pochodzi z aktualnej listy MF.
Jak rozpoznać: to nowe wdrożenie albo własna integracja biura, która jeszcze ani razu nie otworzyła sesji.
Co zrobić krok po kroku
- Nie poprawiaj faktur. KSeF nie doszedł do ich treści, bo nie otworzył sesji.
- Nie generuj nowego tokenu. Token KSeF nie ma związku z tym kluczem.
- Zainstaluj aktualizację programu, jeśli dostawca ją wydał. W programach w chmurze robi to sam dostawca.
- Zgłoś błąd dostawcy programu. Przekaż kod 21470, pełną treść komunikatu razem z identyfikatorem klucza ze szczegółów, datę i godzinę oraz środowisko (produkcja, test albo demo). Najprościej skopiować komunikat z historii wysyłki lub z logu.
- Po poprawce wyślij faktury ponownie. Sesja się nie otworzyła, więc żadna z tych faktur nie trafiła do KSeF. Ponowna wysyłka nie grozi duplikatem.
Zgłoszenie do MF zwykle nie jest tu potrzebne. Dokumentacja MF opisuje dokładnie, co w takiej sytuacji ma zrobić program.
Jak temu zapobiec
Po stronie biura wystarczą dwie rzeczy. Aktualizuj program, z którego wysyłasz faktury. Zapytaj dostawcę, czy program sam pobiera aktualne klucze MF, czy ma je wpisane na stałe.
Dla programistów
Oficjalna procedura jest w dokumentacji kluczy publicznych do szyfrowania, punkt 4.4. Po 21470 pobierz ponownie GET /security/public-key-certificates, wybierz aktualny certyfikat dla danego usage i powtórz żądanie z nowym publicKeyId. W praktyce: nie wpisuj klucza ani jego identyfikatora na stałe i nie trzymaj listy certyfikatów w pamięci bez końca. Odświeżaj ją przy starcie, okresowo i od razu po 21470. Po odświeżeniu ponów otwarcie sesji raz, a nie w pętli. Klucz AES sesji szyfruj kluczem z tego samego certyfikatu, którego identyfikator wysyłasz w publicKeyId. Inaczej KSeF nie odszyfruje klucza, a to już status sesji 415. Klucz AES i wektor IV generuj dla każdej sesji od nowa.
21470, 415 i 435: trzy różne etapy
Wszystkie trzy kody dotyczą szyfrowania, ale pojawiają się w innym miejscu:
- 21470 przychodzi od razu, przy otwieraniu sesji (HTTP 400). KSeF nie rozpoznaje identyfikatora klucza publicznego i sesji nie otwiera.
- 415 w statusie sesji, „Błąd odszyfrowania dostarczonego klucza”. Identyfikator był w porządku, ale KSeF nie odszyfrował przesłanego klucza AES. Uwaga: 415 to także status logowania i status faktury, za każdym razem z innym znaczeniem. Rozdzielamy je w tekście o błędzie 415 w KSeF.
- 435 to „Błąd odszyfrowania pliku” w statusie faktury, a w sesji wsadowej „Błąd odszyfrowania zaszyfrowanych części archiwum”. Klucz był dobry, ale nie udało się odszyfrować samej faktury albo części paczki. Szczegóły w tekście o błędzie 435 w KSeF.
Jest jeszcze czwarta sytuacja. Jeśli program w ogóle nie wyśle danych szyfrowania, KSeF odpowie błędem walidacji 21405, a nie 21470. Sami to widzieliśmy przy pierwszej integracji z KSeF 2.0: odpowiedź brzmiała 'encryption' must not be empty. Więcej w tekście o błędzie 21405.
Każdy z tych błędów naprawia dostawca programu, a nie księgowa poprawiająca fakturę.
Chcesz widzieć błędy KSeF po polsku, a nie same numery? FakturaFlow pokazuje każdy błąd KSeF po polsku, z informacją, co poprawić. W oknie „Szczegóły KSeF” widzisz historię statusów faktury, jej numer KSeF i wysłany plik XML. FakturaFlow działa obok Twojego programu księgowego, nie zamiast niego. Zobacz, jak to działa.
Podsumowanie
Kod 21470 znaczy, że program wskazał klucz publiczny MF, którego KSeF nie zna albo który już wycofano. Faktury są w porządku i żadna nie trafiła do KSeF, więc po poprawce wystarczy wysłać je ponownie. Naprawa należy do dostawcy programu: pobranie aktualnej listy certyfikatów i powtórzenie żądania z nowym identyfikatorem. Inne kody znajdziesz na pełnej liście kodów błędów KSeF.
Stan na październik 2026 r. Opis na podstawie dokumentacji API KSeF 2.0 (wersja 2.8). Kody i komunikaty mogą się zmienić wraz z nowymi wersjami API.