Translation. Original: tokeny-ksef.md

Управління токенами KSeF

29.06.2025

Токен KSeF — це унікальний, згенерований ідентифікатор автентифікації, який — нарівні з кваліфікованим електронним підписом — дозволяє автентифікуватися до API KSeF.

Token KSeF видається з незмінним набором повноважень, визначених під час його створення; будь-яка модифікація цих повноважень вимагає генерування нового токена.

Увага!
Token KSeF виконує роль конфіденційного секрету автентифікації — його слід зберігати виключно в надійному та безпечному сховищі.

Попередні вимоги

Генерування токена KSeF можливе виключно після одноразової автентифікації електронним підписом (XAdES).

1. Генерування токена

Токен може бути згенерований виключно в контексті Nip або InternalId. Генерування відбувається через виклик ендпоінту:
POST /tokens

Вказуючи в тілі запиту колекцію повноважень та опис токена.

Приклади реалізації:

Поле	Приклад значення	Опис
Permissions	["InvoiceRead", "InvoiceWrite", "CredentialsRead", "CredentialsManage"]	Список повноважень, призначених токену
Description	"Токен для читання рахунків-фактур і даних облікового запису"	Опис токена

Приклад мовою C#: KSeF.Client.Tests.Core\E2E\KsefToken\KsefTokenE2ETests.cs

 KsefTokenRequest tokenRequest = new KsefTokenRequest
    {
        Permissions = [
            KsefTokenPermissionType.InvoiceRead,
            KsefTokenPermissionType.InvoiceWrite
            ],
        Description = "Demo token",
    };
 KsefTokenResponse token = await ksefClient.GenerateKsefTokenAsync(tokenRequest, accessToken, cancellationToken);

Приклад мовою Java: KsefTokenIntegrationTest.java

KsefTokenRequest request = new KsefTokenRequestBuilder()
        .withDescription("test description")
        .withPermissions(List.of(TokenPermissionType.INVOICE_READ, TokenPermissionType.INVOICE_WRITE))
        .build();
GenerateTokenResponse ksefToken = ksefClient.generateKsefToken(request, authToken.accessToken());

2. Фільтрування токенів

Метадані токенів KSeF можна отримувати та фільтрувати за допомогою виклику:
GET /tokens

Приклад мовою C#: KSeF.Client.Tests.Core\E2E\KsefToken\KsefTokenE2ETests.cs

QueryKsefTokensResponse singleResult = await KsefClient.QueryKsefTokensAsync(
    AccessToken,
    statuses: new List<AuthenticationKsefTokenStatus> {
        AuthenticationKsefTokenStatus.Pending,
        AuthenticationKsefTokenStatus.Active,
        AuthenticationKsefTokenStatus.Revoking,
        AuthenticationKsefTokenStatus.Revoked,
        AuthenticationKsefTokenStatus.Failed
    }, // за замовчуванням: null
    authorIdentifier: "authorIdentifier", // за замовчуванням: null
    authorIdentifierType: AuthenticationTokenContextIdentifierType.Nip, // або інший тип, за замовчуванням: null
    description: "description",
    continuationToken: continuationToken,
    pageSize: pageSize, // за замовчуванням: null
    cancellationToken: cancellationToken // за замовчуванням null,
    );

Приклад мовою Java: KsefTokenIntegrationTest.java

List<AuthenticationTokenStatus> status = List.of(AuthenticationTokenStatus.ACTIVE);
Integer pageSize = 10;
QueryTokensResponse tokens = ksefClient.queryKsefTokens(status, StringUtils.EMPTY, null, null, null, pageSize, accessToken);

У відповідь повертаються метадані токенів, серед іншого інформація про те, хто і в якому контексті згенерував токен KSeF та повноваження, призначені йому.

3. Отримання конкретного токена

Щоб отримати деталі конкретного токена, слід використати виклик:
GET /tokens/{referenceNumber}

referenceNumber — це унікальний ідентифікатор токена, який можна отримати під час його створення або зі списку токенів.

Приклад мовою C#: KSeF.Client.Tests.Core\E2E\KsefToken\KsefTokenE2ETests.cs

AuthenticationKsefToken token = await ksefClient.GetKsefTokenAsync(referenceNumber, accessToken, cancellationToken);

Приклад мовою Java: KsefTokenIntegrationTest.java

AuthenticationToken ksefToken = ksefClient.getKsefToken(token.getReferenceNumber(), accessToken);

4. Анулювання токена

Щоб анулювати токен, слід використати виклик:
DELETE /tokens/{referenceNumber}

referenceNumber — це унікальний ідентифікатор токена, який ми хочемо анулювати.

Приклад мовою C#: KSeF.Client.Tests.Core\E2E\KsefToken\KsefTokenE2ETests.cs

await ksefClient.RevokeKsefTokenAsync(referenceNumber, accessToken, cancellationToken);

Приклад мовою Java: KsefTokenIntegrationTest.java

ksefClient.revokeKsefToken(token.getReferenceNumber(), accessToken);