KSeF nadawanie uprawnień
Co musisz wiedzieć
Uprawnienia w KSeF pozwalają na zarządzanie fakturami, dostępem do danych, wysyłanie dokumentów, pobieranie oraz administrację kontem. System wprowadza zaawansowany mechanizm zarządzania uprawnieniami, który stanowi fundament bezpiecznego i zgodnego z przepisami korzystania z systemu.
Uprawnienia nadaje osoba posiadająca pełny dostęp – zazwyczaj właściciel firmy (rola Owner), administrator podmiotu (uprawnienie CredentialsManage), administrator jednostki podrzędnej (SubunitManage) lub administrator podmiotu unijnego (VatUeManage).
Najczęstsze problemy dotyczą różnicy między rolą podatnika, reprezentanta i pełnomocnika. Ważne jest rozróżnienie między uprawnieniami nadanymi w sposób bezpośredni (wprost danemu użytkownikowi) a pośredni (przez podmiot pośredniczący, np. biuro rachunkowe).
Uprawnienia mogą być nadawane osobom fizycznym (identyfikowanym przez PESEL, NIP lub odcisk palca certyfikatu), podmiotom (identyfikowanym przez NIP) oraz w kontekście jednostek podrzędnych (InternalId) lub podmiotów unijnych (NipVatUe).
System umożliwia nadawanie uprawnień selektywnych (dla konkretnego partnera) lub generalnych (dla wszystkich partnerów podmiotu pośredniczącego). Uprawnienia do przeglądania i wystawiania faktur mogą być nadawane z możliwością dalszego przekazywania, co pozwala na ich delegowanie.
Instrukcja krok po kroku
1. Zaloguj się do KSeF jako osoba posiadająca pełne uprawnienia
Zaloguj się jako właściciel podmiotu (rola Owner), administrator z uprawnieniem CredentialsManage, administrator jednostki podrzędnej (SubunitManage) lub administrator podmiotu unijnego (VatUeManage). Upewnij się, że logujesz się w odpowiednim kontekście (NIP, InternalId lub NipVatUe).
2. Określ typ odbiorcy uprawnień
Zdecyduj, komu nadajesz uprawnienia: osobie fizycznej (PESEL, NIP lub Fingerprint), podmiotowi (NIP), jednostce podrzędnej (InternalId) lub podmiotowi unijnemu (NipVatUe). Przygotuj odpowiedni identyfikator odbiorcy.
3. Wybierz rodzaj uprawnienia do nadania
Wybierz odpowiednie uprawnienia: fakturowe (InvoiceWrite - wystawianie faktur, InvoiceRead - przeglądanie faktur), administracyjne (CredentialsManage - zarządzanie uprawnieniami, SubunitManage - zarządzanie jednostkami podrzędnymi, VatUeManage - zarządzanie podmiotami unijnymi), podmiotowe (SelfInvoicing - samofakturowanie, RRInvoicing - samofakturowanie RR, TaxRepresentative - przedstawiciel podatkowy) lub techniczne (Introspection - przeglądanie historii).
4. Określ kontekst uprawnienia
Dla uprawnień pośrednich (uprawnienia do odczytu i wystawiania faktur z możliwością przekazywania) określ, czy nadajesz uprawnienie selektywne (dla konkretnego partnera - podaj NIP) czy generalne (dla wszystkich partnerów - użyj AllPartners). Dla jednostek podrzędnych określ InternalId lub NIP podmiotu podrzędnego.
5. Nadaj uprawnienie przez API lub portal
W portalu webowym: przejdź do sekcji ‘Zarządzanie uprawnieniami’, wybierz ‘Dodaj nowe uprawnienie’, wprowadź dane odbiorcy i zakres uprawnień. W API: użyj odpowiedniego endpointu (POST /api/v2/permissions/persons/grants dla osób fizycznych, POST /api/v2/permissions/entities/grants dla podmiotów, POST /api/v2/permissions/indirect/grants dla uprawnień pośrednich) wraz z accessToken.
6. Sprawdź status operacji nadania uprawnienia
Operacja nadania uprawnienia jest asynchroniczna. Sprawdź status operacji używając operationReferenceNumber otrzymanego po nadaniu uprawnienia (GET /api/v2/permissions/operations/{operationReferenceNumber}). Status wskazuje, czy operacja zakończyła się sukcesem, czy wystąpił błąd.
7. Zweryfikuj nadane uprawnienia
Po pomyślnym nadaniu uprawnienia, możesz sprawdzić listę nadanych uprawnień używając odpowiednich endpointów wyszukiwania (POST /api/v2/permissions/query/persons/grants, POST /api/v2/permissions/query/entities/roles itp.). Upewnij się, że uprawnienie jest aktywne i przypisane do właściwego odbiorcy.
Najczęstsze problemy i rozwiązania
Błąd 401 podczas nadawania uprawnienia
Zalogowano się jako osoba bez pełnego uprawnienia administracyjnego. Aby nadać uprawnienia, musisz posiadać rolę Owner lub uprawnienie CredentialsManage. Sprawdź, czy logujesz się w odpowiednim kontekście (NIP, InternalId lub NipVatUe) i czy masz wymagane uprawnienia w tym kontekście.
Nie mogę dodać biura rachunkowego
Sprawdź, czy biuro posiada profil zaufany lub podpis kwalifikowany. Aby nadać uprawnienia podmiotowi, musisz podać jego NIP. Upewnij się, że używasz poprawnego identyfikatora podmiotu. Jeśli nadajesz uprawnienia do obsługi faktur, możesz ustawić opcję pozwalającą biuru przekazać te uprawnienia dalej swoim pracownikom.
Błąd podczas nadawania uprawnienia pośredniego
Uprawnienia pośrednie mogą być nadawane tylko dla InvoiceRead i InvoiceWrite. Podmiot pośredniczący musi najpierw otrzymać uprawnienie z możliwością dalszego przekazywania od podmiotu docelowego. Sprawdź, czy masz uprawnienie do nadawania uprawnień pośrednich i czy podajesz poprawny targetIdentifier (NIP dla selektywnych lub AllPartners dla generalnych).
Operacja nadania uprawnienia zwraca status ‘w toku’
Operacja nadania uprawnienia jest asynchroniczna i może trwać kilka chwil. Odpytywaj status operacji używając operationReferenceNumber do skutku. Jeśli status długo pozostaje ‘w toku’, sprawdź logi systemu lub skontaktuj się z pomocą techniczną KSeF.
Nie mogę nadać uprawnienia administratorowi jednostki podrzędnej
Aby nadać uprawnienia administratorowi jednostki podrzędnej, musisz posiadać uprawnienie SubunitManage. Użyj endpointu POST /api/v2/permissions/subunits/grants i podaj poprawny contextIdentifier (InternalId lub NIP jednostki podrzędnej). Sprawdź, czy jednostka podrzędna istnieje w systemie.
Uprawnienie nie działa natychmiast po nadaniu
Operacja nadania uprawnienia jest asynchroniczna - wykonanie operacji nie skutkuje natychmiastowym dostępem. Musisz sprawdzić status operacji i poczekać na jej pomyślne przetworzenie przez system. Dopiero po otrzymaniu statusu sukcesu uprawnienie staje się aktywne.
Rodzaje uprawnień w KSeF
Uprawnienia fakturowe: InvoiceWrite (wystawianie faktur) i InvoiceRead (przeglądanie faktur) - mogą być nadawane w sposób pośredni z możliwością dalszego przekazywania. Uprawnienia administracyjne: CredentialsManage (zarządzanie uprawnieniami), SubunitManage (zarządzanie jednostkami podrzędnymi), VatUeManage (zarządzanie podmiotami unijnymi) - nie mogą być nadawane w sposób pośredni. Uprawnienia podmiotowe: SelfInvoicing (samofakturowanie), RRInvoicing (samofakturowanie RR), TaxRepresentative (operacje przedstawiciela podatkowego) - nadawane tylko podmiotom. Uprawnienia techniczne: Introspection (przeglądanie historii operacji i sesji).
Uprawnienia bezpośrednie i pośrednie
Uprawnienia bezpośrednie nadawane są wprost danemu użytkownikowi lub podmiotowi przez właściciela lub administratora. Uprawnienia pośrednie nadawane są przez podmiot pośredniczący (np. biuro rachunkowe) w kontekście innego podmiotu docelowego. Tylko InvoiceRead i InvoiceWrite mogą być nadawane w sposób pośredni. Podmiot pośredniczący musi najpierw otrzymać uprawnienie z możliwością dalszego przekazywania od podmiotu docelowego. Uprawnienia pośrednie mogą być selektywne (dla konkretnego partnera) lub generalne (dla wszystkich partnerów).
Identyfikatory w systemie uprawnień
NIP - identyfikuje podmioty krajowe oraz osoby fizyczne. PESEL - identyfikuje osoby fizyczne, wymagane m.in. przy nadaniu uprawnień pracownikom posługującym się profilem zaufanym. Fingerprint - odcisk palca certyfikatu (SHA-256), wykorzystywany gdy certyfikat nie zawiera NIP ani PESEL, oraz przy identyfikowaniu administratorów podmiotów unijnych. InternalId - wewnętrzny identyfikator jednostki podrzędnej (dwuczłonowy: NIP-5_cyfr). NipVatUe - identyfikator złożony łączący podmiot polski z podmiotem unijnym (nip-vat_ue).
Role w systemie KSeF
Właściciel podmiotu (Owner) - rola posiadana domyślnie, obejmuje wszystkie uprawnienia fakturowe i administracyjne poza VatUeManage. Administrator podmiotu - osoba z uprawnieniem CredentialsManage, może nadawać i odbierać uprawnienia. Administrator jednostki podrzędnej - osoba z uprawnieniem SubunitManage, może powoływać administratorów w jednostkach podrzędnych. Administrator podmiotu unijnego - osoba z uprawnieniem VatUeManage, może zarządzać uprawnieniami w kontekście złożonym NipVatUe. Podmiot pośredniczący - podmiot, który otrzymał uprawnienie z możliwością przekazywania i może przekazać je dalej.
FAQ
Czy mogę nadać uprawnienia księgowej?
Tak, możesz nadać uprawnienia osobie fizycznej (np. księgowej) identyfikowanej przez PESEL, NIP lub odcisk palca certyfikatu. Nadaj odpowiednie uprawnienia (np. InvoiceWrite i InvoiceRead) w kontekście Twojego podmiotu. Użyj endpointu POST /api/v2/permissions/persons/grants lub odpowiedniej opcji w portalu webowym.
Czy mogę nadać uprawnienia osobie spoza firmy?
Tak, możesz nadać uprawnienia osobie fizycznej spoza firmy (np. pełnomocnikowi) lub podmiotowi (np. biuru rachunkowemu). Osoba fizyczna może być identyfikowana przez PESEL, NIP lub odcisk palca certyfikatu. Podmiot identyfikowany jest przez NIP. Ważne jest, aby odbiorca uprawnień miał odpowiedni środek uwierzytelniania (Profil Zaufany, ePUAP, certyfikat kwalifikowany).
Czym różnią się uprawnienia selektywne od generalnych?
Uprawnienia selektywne nadawane są dla konkretnego partnera (podajesz NIP podmiotu docelowego) - odbiorca działa tylko w kontekście wskazanego podmiotu. Uprawnienia generalne nadawane są bez wskazania konkretnego partnera (używasz AllPartners) - odbiorca zyskuje dostęp do operacji w kontekście wszystkich podmiotów obsługiwanych przez pośrednika. Generalne uprawnienia powinny być stosowane z ostrożnością ze względu na ich szeroki zakres.
Czym jest możliwość przekazywania uprawnień dalej?
Możliwość przekazywania uprawnień pozwala na ich delegowanie. Tylko InvoiceRead oraz InvoiceWrite mogą być nadawane z tą opcją. Jeśli nadajesz uprawnienie podmiotowi z możliwością przekazywania, ten podmiot może przekazać to uprawnienie dalej (np. swoim pracownikom) w sposób pośredni. Opcja może być wykorzystana tylko podczas nadawania uprawnienia podmiotowi do obsługi faktur.
Jak odebrać uprawnienia?
Aby odebrać uprawnienie, musisz znać jego permissionId (identyfikator techniczny nadanego uprawnienia). Użyj endpointu DELETE /api/v2/permissions/common/grants/{permissionId} dla większości typów uprawnień lub DELETE /api/v2/permissions/authorizations/grants/{permissionId} dla uprawnień podmiotowych. Operacja odbierania jest asynchroniczna - sprawdź status operacji.
Jak sprawdzić, komu nadałem uprawnienia?
Możesz sprawdzić listę nadanych uprawnień używając odpowiednich endpointów wyszukiwania: POST /api/v2/permissions/query/persons/grants (dla osób fizycznych), POST /api/v2/permissions/query/entities/roles (dla ról podmiotu), POST /api/v2/permissions/query/subunits/grants (dla administratorów jednostek podrzędnych) itp. Możesz filtrować po rodzaju uprawnień, stanie (Active/Inactive), identyfikatorze nadawcy i odbiorcy.
Czy mogę nadać uprawnienia biuru rachunkowemu do obsługi wielu klientów?
Tak, możesz nadać biuru rachunkowemu uprawnienia InvoiceRead i InvoiceWrite z możliwością przekazywania. Biuro może następnie przekazać te uprawnienia swoim pracownikom w sposób pośredni - selektywnie (dla konkretnego klienta) lub generalnie (dla wszystkich klientów biura). Dzięki temu pracownicy biura mogą obsługiwać faktury Twojej firmy bez konieczności posiadania uprawnień do obsługi faktur własnych biura.