Skonfiguruj uprawnienia · ksef2 SDK dokumentacja

Użyj auth.permissions, gdy uwierzytelniony kontekst ma nadawać, sprawdzać albo cofać uprawnienia KSeF. Zmiany uprawnień są asynchroniczne: metody grant i revoke najpierw zwracają referencję operacji.

Nadaj uprawnienia

Wybierz metodę nadania pasującą do docelowego podmiotu. Utrzymuj zakres uprawnień tak mały, jak pozwala na to przepływ.

Osoba

operation = auth.permissions.grant_person(
    subject_type="pesel",
    subject_value="90010112345",
    permissions=["invoice_read"],
    description="Read invoices",
    first_name="Jan",
    last_name="Kowalski",
)

# GrantPermissionsResponse
# {
#   "reference_number": "20260625-PERM-..."
# }

python

Podmiot

from ksef2.models import EntityPermission

operation = auth.permissions.grant_entity(
    subject_value="1234567890",
    permissions=[
        EntityPermission(type="invoice_read", can_delegate=False),
    ],
    description="Accounting office read access",
    entity_name="Accounting Sp. z o.o.",
)

python

Autoryzacja

operation = auth.permissions.grant_authorization(
    subject_type="nip",
    subject_value="1234567890",
    permission="self_invoicing",
    description="Self-invoicing agreement",
    entity_name="Partner Sp. z o.o.",
)

python

Poczekaj na operację

Każde wywołanie grant_*() i revoke*() zwraca uchwyt PermissionOperation. Czekaj na niego, aż KSeF zgłosi wynik operacji uprawnień.

status = operation.wait(timeout=60.0, poll_interval=1.0)

python

wait() zgłasza KSeFPermissionOperationFailedError, gdy KSeF zakończy operację bez zastosowania uprawnienia, oraz KSeFPermissionOperationTimeoutError, gdy nie zakończy się na czas. Aby sprawdzić jednorazowo bez czekania, wywołaj operation.get_status() albo get_operation_status(), gdy zapisałeś tylko numer referencyjny:

status = auth.permissions.get_operation_status(
    reference_number=operation.reference_number,
)

# PermissionOperationStatusResponse
# {
#   "status": {
#     "code": 200,
#     "description": "Completed"
#   }
# }

python

Wyszukaj uprawnienia

Metody list_*() mają osobne kształty, ponieważ KSeF rozróżnia rekordy personal, person, entity, authorization, EU entity, subordinate entity i subunit. Każda zwraca Pager: iteruj po nim, by dostać każdy rekord, wywołaj .pages() dla list wielkości strony albo .first_page(), by wykonać jedno żądanie.

Moje uprawnienia

from ksef2.models import PersonalPermissionsQuery

permissions = auth.permissions.list_personal(
    PersonalPermissionsQuery(
        permission_types=["invoice_read"],
        permission_state="active",
    ),
)

for permission in permissions:
    print(permission.id, permission.permission_type, permission.permission_state)

python

Nadania entity

from ksef2.models import EntityPermissionsQuery

permissions = auth.permissions.list_entities(
    EntityPermissionsQuery(context_type="nip", context_value="5261040828"),
)

for permission in permissions:
    print(permission.id, permission.permission_type, permission.can_delegate)

python

Autoryzacje

from ksef2.models import AuthorizationPermissionsQuery

grants = auth.permissions.list_authorizations(
    AuthorizationPermissionsQuery(
        query_type="granted",
        permission_types=["self_invoicing"],
    ),
)

for grant in grants:
    print(grant.id, grant.authorization_scope, grant.authorized_entity_value)

python

Cofnij uprawnienia

Użyj identyfikatora uprawnienia zwróconego przez listę. Cofnięcie też zwraca uchwyt PermissionOperation.

operation = auth.permissions.revoke(permission_id="permission-id")
status = operation.wait()
print(status.status.code, status.status.description)

python

Dla nadań autoryzacji użyj metody cofania autoryzacji:

operation = auth.permissions.revoke_authorization(
    permission_id="authorization-id",
)

python

Sprawdź uprawnienie do załączników

status = auth.permissions.get_attachment_permission_status()

# AttachmentPermissionStatus
# {
#   "is_attachment_allowed": true,
#   "revoked_date": null
# }

python

Zalecany przepływ

Nadaj najmniejszy zestaw uprawnień wymagany przez docelowy podmiot.
Zapisz reference_number operacji.
Poczekaj na operację przed pokazaniem uprawnienia jako aktywnego.
Wyszukaj uprawnienia, aby zebrać identyfikatory do audytu albo cofnięcia.
Cofnij po identyfikatorze uprawnienia, gdy dostęp ma się zakończyć, a potem poczekaj na operację cofnięcia.

Następne przepływy

Uprawnienia: Zrozum rodziny uprawnień KSeF i powód różnych kształtów zapytań.
Zarządzaj tokenami: Generuj i cofaj tokeny automatyzacji z ograniczonym zakresem uprawnień.
Użyj danych TEST: Twórz sandboxowe podmioty i nadania dla testów integracyjnych.