Błąd 410 w KSeF: nieprawidłowy zakres uprawnień przy fakturze

Faktura wróciła ze statusem 410 i opisem „Nieprawidłowy zakres uprawnień”. Logowanie się udało, sesja się otworzyła, a Krajowy System e-Faktur (KSeF) i tak nie przyjął tej faktury.

Ta strona oddziela to, co wiadomo o kodzie 410 na pewno, od tego, co wynika z zasad uprawnień. Dostaniesz też listę rzeczy do sprawdzenia, po kolei. Wszystkie inne kody: pełna lista kodów błędów KSeF.

Co oznacza kod 410

410 to status jednej faktury w sesji. Tabela statusów faktur w dokumentacji API KSeF 2.0 Ministerstwa Finansów (MF) podaje dla niego tylko opis „Nieprawidłowy zakres uprawnień”. Dokumentacja MF nie mówi, co dokładnie wywołuje ten status. Nie podaje szczegółów ani przykładów. Wszystko, co piszemy niżej o przyczynach, to wnioski z opisanych zasad uprawnień, a nie oficjalny opis kodu.

Pewne jest jedno: status faktury dotyczy faktury wysłanej w sesji. Skoro go widzisz, logowanie i otwarcie sesji się udały. Problem dotyczy więc tej konkretnej faktury w zestawieniu z kontekstem, czyli NIP-em, w którym program się zalogował.

Dwa sąsiednie kody też dotyczą uprawnień, ale na innym etapie:

• 415 przy logowaniu, ze szczegółem „Brak przypisanych uprawnień”. Logujący nie ma uprawnień w tym kontekście, więc do wysyłki w ogóle nie dochodzi. Opis: błąd 415 w KSeF.
• HTTP 403 z powodem missing-permissions („Brak wymaganych uprawnień do wykonania operacji w bieżącym kontekście”). KSeF odmawia wykonania całej operacji. Opis: błąd 403 w KSeF.

Inny 410: HTTP „Gone” przy logowaniu

Jeśli widzisz sam kod HTTP 410, a nie status faktury, to zupełnie inna sprawa. Zwraca go zapytanie o wynik logowania (GET /auth/{referenceNumber}), z opisem „Operacja wygasła i nie jest już dostępna”. KSeF przechowuje statusy logowania przez 7 dni, a potem odpowiada właśnie kodem 410. Uprawnienia nie mają tu nic do rzeczy. Program pyta o stare logowanie i powinien po prostu zalogować się od nowa. Jeśli to się powtarza, zgłoś to dostawcy programu.

Jakie uprawnienia KSeF sprawdza przy fakturze

Dokumentacja opisuje cztery zasady, które mają tu znaczenie:

1. Uprawnienie do wystawienia tej faktury. Opis weryfikacji faktury mówi: „Wysłanie faktury do KSeF wymaga posiadania odpowiednich uprawnień do jej wystawienia w kontekście danego podmiotu.”
2. Uprawnienie do otwarcia sesji. Sesja wymaga uprawnienia do wystawiania faktur (InvoiceWrite) albo jednego z uprawnień specjalnych. Skoro sesja się otworzyła, ten warunek był spełniony.
3. Kontekst a sprzedawca. Przy opisie kodów QR dokumentacja pisze: „System sprawdza, czy kontekst (ContextIdentifier) ma prawo do wystawiania faktury dla danego NIP-u sprzedawcy (Podmiot1 faktury)”. Kontekst A może wystawić fakturę za sprzedawcę B, „gdy podmiot A posiada nadane uprawnienia wystawiania faktur w imieniu podmiotu B”.
4. Uprawnienia sprawdzane względem danych faktury. Według opisu uprawnień samofakturowanie (SelfInvoicing), faktury VAT RR (RRInvoicing) i przedstawiciel podatkowy (TaxRepresentative) „są istotne przy wysyłaniu przez podmiot plików faktur i weryfikowane w procesie ich walidacji. Weryfikowana jest zależność pomiędzy podmiotem, a danymi na fakturach.” Nadaje je wyłącznie właściciel albo administrator z uprawnieniem do zarządzania uprawnieniami (CredentialsManage).

Z tych zasad wynika prosty test. NIP sprzedawcy w Podmiot1 faktury powinien być NIP-em kontekstu, w którym program się zalogował. Jeśli jest inny, kontekst musi mieć nadane uprawnienie do wystawiania faktur za tego sprzedawcę.

Najczęstsze przyczyny

Dokumentacja nie opisuje przyczyn kodu 410. Z zasad uprawnień wynika, że chodzi o niezgodność między kontekstem logowania a danymi na fakturze. Poniższe sytuacje to nasze wnioski, nie oficjalna lista MF.

1. Grupa z dwoma NIP-ami i jednym tokenem. Dwie spółki jednego właściciela albo holding ze spółką zależną. Program loguje się tokenem spółki A i wysyła nim również faktury spółki B. W Podmiot1 stoi NIP B, a kontekst to A. Rozpoznasz po tym, że odrzucane są wyłącznie faktury jednej spółki. NIP tokenu widać w jego środkowej części, po nip-. Jeśli program loguje się w kontekście NIP-u sprzedawcy, ta sama pomyłka wyjdzie wcześniej, przy logowaniu, jako błąd 450 ze szczegółem „Token nie może być użyty w kontekście…”.
2. Biuro wysyła pod własnym NIP-em. Program loguje się w kontekście biura, a w Podmiot1 jest klient. Według dokumentacji kontekst biura może wystawić fakturę za klienta, gdy klient nadał biuru uprawnienia do wystawiania faktur w swoim imieniu. Bez tego faktura nie przejdzie. Rozpoznasz po tym, że błąd dotyczy nowych klientów albo tych, którzy nie nadawali biuru uprawnień.
3. Samofakturowanie bez uprawnienia od sprzedawcy. Nabywca wystawia fakturę w imieniu sprzedawcy, a sprzedawca nie nadał mu w KSeF uprawnienia do samofakturowania. Umowa o samofakturowaniu tego nie zastępuje. Rozpoznasz po tym, że odrzucane są faktury oznaczone jako samofakturowanie (w FA(3) pole P_17 z wartością 1). Więcej: samofakturowanie w KSeF.
4. Faktury VAT RR i przedstawiciel podatkowy. Działa ta sama zasada. Potrzebne jest osobne uprawnienie, a KSeF porównuje je z danymi na fakturze. Rozpoznasz po tym, że błąd dotyczy tylko tego rodzaju faktur.
5. Literówka w NIP-ie sprzedawcy. W Podmiot1 jest NIP, który różni się od kontekstu jedną cyfrą, na przykład przez błąd w danych firmy w programie. Rozpoznasz po tym, że wszystkie faktury tej firmy dostają 410. W środowisku produkcyjnym KSeF sprawdza też sumę kontrolną NIP-u, więc część literówek wyjdzie jako inny błąd.

Co zrobić krok po kroku

1. Zapisz NIP sprzedawcy. Otwórz XML odrzuconej faktury i odczytaj NIP z Podmiot1.
2. Ustal NIP kontekstu. To NIP, w którym program się loguje. Znajdziesz go w ustawieniach połączenia z KSeF, a przy tokenie także w samym tokenie, po nip-.
3. NIP-y różnią się przez pomyłkę? Wyślij fakturę z właściwego kontekstu. Każda firma potrzebuje własnego tokenu, wygenerowanego w kontekście jej NIP-u (token KSeF krok po kroku). Program powinien dobierać token do NIP-u sprzedawcy.
4. NIP-y różnią się celowo? Tak jest przy biurze wysyłającym pod własnym NIP-em, przy samofakturowaniu i przy przedstawicielu podatkowym. Wtedy najpewniej brakuje uprawnienia. Nadaje je właściciel firmy, która udziela uprawnienia, albo jej administrator z uprawnieniem do zarządzania uprawnieniami. Przy samofakturowaniu jest to sprzedawca, przy biurze klient. Biuro ma też drugą drogę: logować się w kontekście klienta, jego tokenem.
5. NIP-y są takie same? Sprawdź, czy faktura nie ma oznaczeń, które wymagają osobnego uprawnienia, choć nie powinna ich mieć (na przykład samofakturowania).
6. Wyślij fakturę ponownie. Faktura z kodem 410 nie została przyjęta i nie ma numeru KSeF. Ponowna wysyłka po poprawce nie będzie więc duplikatem.
7. Napisz do MF, jeśli nic nie pomaga. Gdy NIP-y się zgadzają, uprawnienia są nadane, a 410 wraca, użyj formularza MF albo napisz na jpk.helpdesk@mf.gov.pl. Podaj numer referencyjny sesji, numer faktury, datę i środowisko.

Jak temu zapobiec

• Jeden NIP, jeden kontekst, jeden token. W grupie firm każda spółka ma własny token, a program wybiera go po NIP-ie sprzedawcy.
• Uprawnienia przed pierwszą fakturą. Nowy klient biura albo nowy kontrahent w samofakturowaniu: najpierw nadanie uprawnienia w KSeF, potem wysyłka.
• Zmiany u klienta. Gdy klient zmienia biuro albo porządkuje dostępy, sprawdź nowe uprawnienia, zanim ruszy wysyłka hurtowa.

Dla programistów

Status faktury zwraca GET /sessions/{referenceNumber}/invoices/{invoiceReferenceNumber} w polach code, description, details i extensions. Przy kodzie 410 porównaj ContextIdentifier użyty przy uwierzytelnieniu z Podmiot1/NIP faktury. Otwarcie sesji interaktywnej wymaga InvoiceWrite, PefInvoiceWrite lub EnforcementOperations, a wsadowej InvoiceWrite lub EnforcementOperations. Uprawnienia SelfInvoicing, RRInvoicing i TaxRepresentative KSeF weryfikuje względem danych faktury. HTTP 410 „Gone” z GET /auth/{referenceNumber} znaczy, że rekord statusu logowania wygasł (przechowywany jest 7 dni). Wtedy rozpocznij nowe uwierzytelnienie.

Każdy błąd KSeF po polsku, z tym, co poprawić. FakturaFlow pokazuje przy fakturze opis błędu i wskazówkę. W oknie „Szczegóły KSeF” masz historię statusów, numer KSeF, link do weryfikacji MF i wysłany XML. Po zapisaniu tokenu albo certyfikatu FakturaFlow od razu loguje się do KSeF i mówi, czy połączenie działa. Działa obok Twojego programu księgowego, nie zamiast niego. Załóż konto.

Podsumowanie

Kod 410 przy fakturze ma tylko opis „Nieprawidłowy zakres uprawnień”, bez oficjalnie podanych przyczyn. Z zasad uprawnień wynika, że kontekst logowania najpewniej nie ma prawa wystawić tej faktury za sprzedawcę z Podmiot1. Zacznij od porównania tych dwóch NIP-ów, a jeśli różnią się celowo, poproś o nadanie uprawnienia. Inne kody znajdziesz w zestawieniu 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.