Błąd 415 w KSeF: załącznik, klucz sesji czy brak uprawnień

Twój program pokazuje kod 415, a obok jeden z trzech opisów: „Brak możliwości wysyłania faktury z załącznikiem”, „Błąd odszyfrowania dostarczonego klucza” albo „Uwierzytelnianie zakończone niepowodzeniem” ze szczegółem „Brak przypisanych uprawnień”. Krajowy System e-Faktur (KSeF) używa tej samej liczby w trzech miejscach i za każdym razem chodzi o coś innego.

Najpierw ustalisz, który wariant masz, potem dostaniesz przyczyny i kroki dla każdego z nich. Inne numery zebraliśmy w jednym miejscu: pełna lista kodów błędów KSeF.

Co oznacza kod 415

Oficjalna dokumentacja API KSeF 2.0 Ministerstwa Finansów (MF) przypisuje kod 415 do trzech różnych tabel statusów. Wariant rozpoznasz po dwóch rzeczach: gdzie kod się pojawił i jakie słowo stoi w opisie.

1. Status jednej faktury, w opisie słowo „załącznik”. Pełny opis: „Brak możliwości wysyłania faktury z załącznikiem”. Sesja działa, odrzucona jest konkretna faktura. To wariant 1.
2. Status całej sesji, w opisie słowo „klucz”. Pełny opis: „Błąd odszyfrowania dostarczonego klucza”. Dotyczy całej sesji wysyłki, interaktywnej albo wsadowej, a nie treści faktury. To wariant 2.
3. Logowanie, w szczegółach „Brak przypisanych uprawnień”. Opis: „Uwierzytelnianie zakończone niepowodzeniem”. Pojawia się przy łączeniu z KSeF, zanim program wyśle jakąkolwiek fakturę. To wariant 3.

Przy wariancie 3 czytaj szczegół, nie tylko opis. Ten sam opis ma też kod 470, w zupełnie innej sprawie.

Jeżeli program pokazuje samą liczbę, ustal etap: łączenie z KSeF, cała paczka czy jedna faktura.

Wariant 1: faktura z załącznikiem

KSeF odrzucił jedną fakturę z opisem o załączniku. Załącznik w strukturze FA(3) to dodatkowa sekcja danych w samym pliku XML faktury (element Zalacznik). Nie jest to osobny plik PDF dołączony do wysyłki.

Co mówi dokumentacja

Dokumentacja MF stawia fakturom z załącznikiem dwa warunki. Pierwszy to zgoda w e-Urzędzie Skarbowym. Opis uprawnień w dokumentacji KSeF mówi: „Zgoda jest wymagana do wystawiania faktur zawierających załączniki i obowiązuje w obrębie bieżącego kontekstu (ContextIdentifier) użytego przy uwierzytelnieniu. Zgoda jest nadawana poza API, wyłącznie w usłudze e-Urząd Skarbowy, a zgłoszenia można składać od 1 stycznia 2026 r.” I dalej: „Jeżeli zgoda nie jest aktywna, faktura z załącznikiem wysłana do API KSeF zostanie odrzucona.”

Drugi warunek to sposób wysyłki. Opis weryfikacji faktury mówi: „Wysyłka faktur z załącznikami jest dozwolona tylko w trybie wsadowym.” Jedyny wyjątek to korekta techniczna faktury wystawionej offline, która może iść w sesji interaktywnej.

Dokumentacja nie pisze wprost, że brak zgody daje kod 415. Opis kodu pasuje jednak dokładnie do tych dwóch reguł, więc od nich zacznij.

Najczęstsze przyczyny

1. Brak aktywnej zgody. Nikt w firmie jej nie składał albo nie wiadomo, czy ją złożono. Pamiętaj, że zgoda obowiązuje w obrębie kontekstu, czyli NIP-u, w którym program się loguje. Zgoda spółki A nie obejmuje spółki B, nawet w jednej grupie.
2. Wysyłka w sesji interaktywnej. Program wysyła faktury pojedynczo, w sesji interaktywnej. Wtedy nawet aktywna zgoda nie pomoże.
3. Załącznik, o którym nie wiesz. W XML odrzuconej faktury jest element Zalacznik, choć nikt świadomie go nie dodawał. Zapytaj dostawcę programu, skąd się wziął.

Co zrobić krok po kroku

1. Otwórz XML odrzuconej faktury i poszukaj elementu Zalacznik. Jeśli go nie ma, upewnij się, że 415 to na pewno status faktury, a nie sesji.
2. Zdecyduj, czy załącznik jest potrzebny. Jeśli nie, najprostsza droga to wysłać fakturę bez niego.
3. Jeśli jest potrzebny, sprawdź w e-Urzędzie Skarbowym, czy zgoda na faktury z załącznikami jest aktywna dla NIP-u, w którym program się loguje. Jeśli jej nie ma, złóż zgłoszenie. Dopóki zgoda nie jest aktywna, takie faktury nie przejdą.
4. Upewnij się, że program wysyła faktury z załącznikiem w sesji wsadowej. Jeśli umie tylko wysyłkę pojedynczą, to pytanie do jego dostawcy.
5. Wyślij fakturę ponownie. Odrzucona faktura nie dostała numeru KSeF, więc po poprawce wysyłasz ją normalnie.

Wariant 2: błąd odszyfrowania klucza sesji

Status całej sesji brzmi „Błąd odszyfrowania dostarczonego klucza”. Dokumentacja wymienia ten kod zarówno dla sesji wsadowej, jak i interaktywnej.

Każda sesja ma własny klucz AES-256, którym program szyfruje faktury. Sam ten klucz program szyfruje kluczem publicznym Ministerstwa Finansów i przekazuje przy otwarciu sesji. Kod 415 znaczy, że KSeF nie odszyfrował tej koperty z kluczem. Bez klucza nie odczyta żadnej faktury z tej sesji.

To nie jest błąd w treści faktur, tylko w programie, który szyfruje dane. Dwa sąsiednie kody łatwo z nim pomylić:

• 21470 przychodzi od razu w odpowiedzi na otwarcie sesji, gdy program wskazał nieznany albo wycofany klucz MF. Opis: błąd 21470 w KSeF.
• 435 to status faktury „Błąd odszyfrowania pliku”. Tu klucz był w porządku, a nie dał się odszyfrować plik faktury. Opis: błąd 435 w KSeF.

Najczęstsze przyczyny

Dokumentacja nie wiąże kodu 415 z konkretną przyczyną. Opisuje za to wymagania: klucz sesji szyfruje się algorytmem RSAES-OAEP z funkcją skrótu SHA-256 i MGF1, kluczem publicznym MF. Z tych wymagań wynikają dwa miejsca, w których program może się pomylić:

1. Złe parametry szyfrowania. Na przykład SHA-1 zamiast SHA-256. Rozpoznasz po tym, że 415 dostaje każda sesja, od pierwszej próby.
2. Niewłaściwy certyfikat MF. Program wskazał jeden certyfikat, a klucz zaszyfrował innym, na przykład z innego środowiska albo przeznaczonym do innego celu. Rozpoznasz po tym, że błąd ruszył po zmianie środowiska albo po aktualizacji programu.

Co zrobić krok po kroku

1. Potwierdź, że 415 to status sesji z opisem „Błąd odszyfrowania dostarczonego klucza”. Nie poprawiaj faktur, to nic nie zmieni.
2. Zanim wyślesz cokolwiek ponownie, sprawdź listę faktur przyjętych w tej sesji. Faktura, która ma już numer KSeF, po ponownej wysyłce dostanie kod 440 („Duplikat faktury”).
3. Zgłoś błąd dostawcy programu. Podaj numer referencyjny sesji, datę i godzinę oraz środowisko (produkcyjne, demo albo testowe).
4. Po poprawce wyślij faktury w nowej sesji. Program wygeneruje nowy klucz, bo klucz AES i wektor IV powstają dla każdej sesji osobno.
5. Jeśli dostawca potwierdzi szyfrowanie zgodne z dokumentacją, a 415 wraca, zgłoś sprawę do MF: formularz albo e-mail jpk.helpdesk@mf.gov.pl.

Wariant 3: brak przypisanych uprawnień przy logowaniu

Program pyta KSeF o wynik logowania. W odpowiedzi dostaje status.code 415, opis „Uwierzytelnianie zakończone niepowodzeniem” i szczegół „Brak przypisanych uprawnień”. To nie jest kod HTTP: sama odpowiedź przychodzi z kodem HTTP 200.

Dokumentacja MF podaje tylko opis i szczegół. Czytane dosłownie znaczą: ten, kto się loguje, nie ma przypisanych uprawnień w kontekście, czyli w NIP-ie, do którego program próbuje wejść.

Dwa podobne przypadki mają inne kody. Token użyty w obcym NIP-ie kończy się kodem 450 ze szczegółem „Token nie może być użyty w kontekście…” (błąd 450 w KSeF). Gdy logowanie się uda, a brakuje uprawnienia do konkretnej operacji, KSeF zwraca HTTP 403 z powodem missing-permissions (błąd 403 w KSeF).

Najczęstsze przyczyny

Dokumentacja nie wymienia przyczyn. Z zasad uprawnień KSeF wynikają trzy typowe sytuacje:

1. Nikt nie nadał uprawnień. Pracownik biura loguje się własnym certyfikatem do kontekstu klienta, a klient nie nadał uprawnień ani jemu, ani biuru. Rozpoznasz po tym, że błąd dotyczy jednego klienta, a pozostali działają.
2. Uprawnienia odebrano. Klient zmienił biuro albo porządkował dostępy. Rozpoznasz po tym, że połączenie działało, a od konkretnego dnia przestało.
3. Program prosi o zły kontekst. W ustawieniach jest NIP z literówką albo NIP innej firmy.

Jakie uprawnienia są potrzebne i kto je nadaje

Do otwarcia sesji i wysyłki faktur dokumentacja wymaga jednego z kilku uprawnień, między innymi InvoiceWrite (wystawianie faktur). My prosimy klientów o trzy uprawnienia: „Wystawianie faktur”, „Przeglądanie faktur” i „Przeglądanie historii sesji”. Ostatnie służy do pobierania UPO, czyli Urzędowego Poświadczenia Odbioru.

Uprawnienia w kontekście firmy nadaje jej właściciel albo osoba z uprawnieniem do zarządzania uprawnieniami. Przedsiębiorca na jednoosobowej działalności loguje się sam i sam nadaje uprawnienia innym. Spółka bez kwalifikowanej pieczęci najpierw wskazuje pierwszą osobę formularzem ZAW-FA. Token dostaje uprawnienia przy generowaniu, więc przy tokenie najprościej wygenerować nowy: token KSeF krok po kroku.

Co zrobić krok po kroku

1. Sprawdź NIP kontekstu w ustawieniach programu. Musi to być NIP firmy, dla której wysyłasz faktury.
2. Ustal, czym program się loguje (token, certyfikat, podpis) i do kogo należą te dane: biura, pracownika czy klienta.
3. Poproś klienta o sprawdzenie w Aplikacji Podatnika KSeF, czy ta osoba lub podmiot ma nadane uprawnienia. Minimum do wysyłki to „Wystawianie faktur”.
4. Przy tokenie: niech klient wygeneruje nowy, z trzema uprawnieniami, a Ty wklej go w programie.
5. Połącz się ponownie. Jeśli przy poprawnym NIP-ie i nadanych uprawnieniach 415 nie znika, napisz do MF: formularz albo jpk.helpdesk@mf.gov.pl.

Jak temu zapobiec

• Załączniki. Przed pierwszą taką fakturą złóż zgodę w e-Urzędzie Skarbowym dla każdego NIP-u, który ich potrzebuje. Wysyłaj je w sesji wsadowej. Plik faktury z załącznikiem może mieć najwyżej 3 000 000 bajtów, bez załącznika 1 000 000 bajtów.
• Uprawnienia. Po każdej zmianie tokenu, certyfikatu albo uprawnień sprawdź połączenie z KSeF, zanim wyślesz pierwszą fakturę.

Dla programistów

Wariant 1 to status.code faktury z GET /sessions/{referenceNumber}/invoices/{invoiceReferenceNumber}. Stan zgody na załączniki zwraca GET /permissions/attachments/status. Wariant 2 to status sesji z GET /sessions/{referenceNumber}. Klucz AES-256 sesji szyfruj RSAES-OAEP z SHA-256, także w MGF1, certyfikatem z GET /security/public-key-certificates o właściwym usage (opis kluczy publicznych). Uważaj na ustawienia domyślne: publicEncrypt w Node.js bez oaepHash używa SHA-1, a w Javie OAEPWithSHA-256AndMGF1Padding bez jawnego OAEPParameterSpec liczy MGF1 z SHA-1. Wariant 3 to status.code w treści odpowiedzi HTTP 200 z GET /auth/{referenceNumber}.

Wariant 3 wyłapiesz przed pierwszą wysyłką. Po zapisaniu tokenu albo certyfikatu FakturaFlow od razu loguje się do KSeF i mówi po polsku, czy połączenie działa. Każdy błąd KSeF pokazuje po polsku, z informacją, co poprawić. Historię statusów faktury masz w oknie „Szczegóły KSeF”. FakturaFlow działa obok Twojego programu księgowego, nie zamiast niego. Zobacz, jak działa FakturaFlow.

Podsumowanie

Kod 415 w KSeF to trzy różne problemy. Przy fakturze chodzi o załącznik: potrzebna jest aktywna zgoda w e-Urzędzie Skarbowym i sesja wsadowa. Przy sesji zawiodło szyfrowanie klucza w programie, a przy logowaniu brakuje uprawnień, które nadaje właściciel kontekstu. Pozostałe numery opisuje pełna lista 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.