KSeF błędy przy nadawaniu uprawnień
Co musisz wiedzieć
Nadawanie uprawnień w KSeF 2.0 opiera się na precyzyjnym modelu ról Owner, CredentialsManage, SubunitManage, VatUeManage i możliwości dalszego przekazywania uprawnień. MF wskazuje, że każdy właściciel podmiotu odpowiada za to, komu i w jakim kontekście (NIP, InternalId, NipVatUe, AllPartners) przydziela dostęp do fakturowania lub administracji.
Operacje nadawania i odbierania praw są w pełni audytowalne – system nadaje numer operationReferenceNumber, który trzeba regularnie sprawdzać, aby ocenić, czy proces zakończył się sukcesem, błędem czy nadal trwa (statusy 100/200/400).
Najczęstsze błędy są techniczne (21405 – walidacja, 30001 – podmiot/uprawnienie istnieje) albo biznesowe (brak uprawnień CredentialsManage, błędny identyfikator odbiorcy, próba delegacji niewspieranych praw). W diagnozie pomocne są endpointy query/grants opisane w dokumentacji MF.
Instrukcja krok po kroku
1. Zweryfikuj rolę i kontekst nadawcy
Sprawdź, kto inicjuje operację. Nadawać uprawnienia mogą Ownerzy, administratorzy z CredentialsManage/SubunitManage/VatUeManage lub podmioty pośrednie z możliwością przekazywania uprawnień. Upewnij się, że logujesz się w tym samym kontekście NIP/InternalId/NipVatUe, w którym chcesz nadać prawo.
2. Określ prawidłowy typ uprawnienia i identyfikator odbiorcy
Osoby fizyczne identyfikujemy przez PESEL/NIP/Fingerprint, podmioty przez NIP, podmioty UE przez NipVatUe, a jednostki podrzędne przez InternalId. Dla uprawnień pośrednich wybierz targetIdentifier: Nip (selektywne) lub AllPartners (generalne).
3. Nadaj prawo i zapisz operationReferenceNumber
Wywołaj właściwy endpoint (np. POST /permissions/persons/grants, /entities/grants, /indirect/grants). Każda odpowiedź zawiera operationReferenceNumber – jest to jedyny identyfikator pozwalający później sprawdzić status operacji.
4. Monitoruj status operacji
Sprawdzaj status poprzez endpoint statusowy (np. GET /operations/{operationReferenceNumber}) lub dedykowane zapytania query/grants. Status 100 oznacza przyjęcie, 200 – zakończenie sukcesem, 400 – błąd (z kodem np. 21405, 30001).
5. Reaguj na kody błędów i powtarzaj po korekcie
Dla 21405 popraw payload zgodnie z komunikatem walidatora. Dla 30001 usuń duplikat lub użyj revoke przed ponownym nadaniem. W przypadku błędów certyfikatów (25008/25009) odśwież listę certyfikatów i sprawdź, czy numer seryjny jest poprawny.
Najczęstsze problemy i rozwiązania
Błąd 21405 – walidacja danych wejściowych
API odrzuciło payload, bo pole subjectIdentifier, contextIdentifier lub permissions zawiera błędną wartość. Zweryfikuj typ identyfikatora (Nip, Pesel, Fingerprint, InternalId, AllPartners) i upewnij się, że opis nie przekracza limitów. Komunikat Details precyzuje, który element nie przeszedł walidacji.
Błąd 30001 – podmiot lub uprawnienie już istnieje
Próba nadania tego samego uprawnienia dwa razy. Użyj endpointu query/grants, aby sprawdzić stan aktualnych praw, ewentualnie wywołaj revoke (DELETE /permissions/common/grants/{permissionId}) i nadaj nowe uprawnienie po usunięciu duplikatu.
Błąd 25008/25009 przy pracy z certyfikatami
Operacja na certyfikacie KSeF dotyczy numeru, który nie istnieje lub został już odwołany. Sprawdź historię certyfikatów w MCU i upewnij się, że używasz aktualnego referenceNumber zwróconego przy wniosku o certyfikat.
OperationReferenceNumber w statusie 400 mimo poprawnego payloadu
Najczęściej brakuje uprawnienia CredentialsManage/SubunitManage/VatUeManage w kontekście, w którym próbujesz nadać prawo. Nadaj brakujące uprawnienie właścicielowi/administratorowi lub zaloguj się Ownerem.
Najczęstsze kody błędów przy nadawaniu uprawnień
| Kod | Opis | Gdzie występuje |
|---|---|---|
| 21405 | Błąd walidacji danych wejściowych – payload niezgodny z kontraktem | Wszystkie metody /permissions/*/grants, /tokens, /certificates |
| 30001 | Podmiot lub uprawnienie już istnieje | Nadawanie podmiotowi/pośrednikowi tych samych praw, duplikaty delegacji |
| 25008 | Certyfikat o podanym numerze seryjnym nie istnieje | Moduł certyfikatów – odczyt/odwołanie certyfikatu |
| 25009 | Nie można odwołać certyfikatu (już odwołany/ zablokowany) | Moduł certyfikatów |
| 440xx | Duplikaty/kolizje biznesowe | Nadawanie uprawnień w kontekście niewłaściwego podmiotu lub powtarzalne numeracje |
| 401 | Brak uprawnień do kontekstu (Owner/CredentialsManage) | Wszystkie operacje, jeśli nadawca nie ma praw |
| Źródło: dokumentacja OpenAPI KSeF 2.0 (sekcja Permissions & Certificates). |
Jak audytować i diagnozować nadane prawa
KSeF udostępnia komplet zapytań permissions/query/*, które pozwalają na pobranie listy aktualnych uprawnień osobowych, podmiotowych, pośrednich i jednostek podrzędnych. Dzięki nim możesz wykryć duplikaty, sprawdzić stan aktywacji (Active/Inactive) oraz zidentyfikować administratorów jednostek JST czy grup VAT. Regularne raporty z tych endpointów minimalizują ryzyko błędów 30001 i przyspieszają reakcję na błędnie nadane prawa.
Ograniczenia identyfikatorów i delegacji
System precyzyjnie weryfikuje identyfikatory: Pesel dla osób fizycznych, Nip dla podmiotów krajowych, Fingerprint dla certyfikatów, InternalId dla jednostek podrzędnych oraz NipVatUe i AllPartners dla scenariuszy UE i pośredników. Tylko uprawnienia do odczytu i wystawiania faktur (InvoiceRead/InvoiceWrite) mogą być nadawane z możliwością dalszego przekazywania, a uprawnienia SelfInvoicing/RRInvoicing/TaxRepresentative nigdy nie są delegowane.
FAQ
Jak sprawdzić status nadawania uprawnień po otrzymaniu operationReferenceNumber?
Użyj endpointów statusowych (np. GET /auth/{referenceNumber} lub /operations/{referenceNumber}) oraz zapytań permissions/query/*. Status 200 oznacza sukces, 400 – błąd z kodem w polu exceptionCode. Bez statusu 200 uprawnienie nie zostało nadane.
Czy mogę nadać to samo uprawnienie wielu osobom jednocześnie?
Tak, ale musisz wykonać oddzielne wywołania dla każdego identyfikatora. Nadawanie hurtowe wymaga automatyzacji po stronie klienta. Pamiętaj, że ponowne nadanie bez wcześniejszego revoke zakończy się błędem 30001.
Jak postępować, gdy nadanie pośrednie zwraca błąd?
Sprawdź, czy podmiot pośredniczący ma aktywne uprawnienie InvoiceRead/InvoiceWrite z możliwością dalszego przekazywania. Upewnij się, że targetIdentifier jest ustawiony na konkretny NIP (tryb selektywny) lub AllPartners (tryb generalny).
Czy brak numeru PESEL w certyfikacie uniemożliwia nadanie uprawnień?
Nie. W takim przypadku użyj identyfikatora Fingerprint i upewnij się, że najpierw zgłoszono go w ZAW-FA lub nadano uprawnienie w MCU – inaczej system zwróci błąd braku uprawnień.