Sesja – sprawdzenie stanu i pobranie UPO

10.07.2025

Niniejszy dokument opisuje operacje służące do monitorowania stanu sesji (interaktywnej lub wsadowej) oraz pobierania UPO dla faktur i całej sesji.

1. Pobranie listy sesji

Zwraca listę sesji spełniających podane kryteria wyszukiwania.

GET sessions

Zwraca bieżący status sesji wraz z zagregowanymi danymi o liczbie przesłanych, poprawnie i niepoprawnie przetworzonych faktur; po zamknięciu sesji udostępnia dodatkowo listę referencji do zbiorczego UPO.

Przykład w języku C#: KSeF.Client.Tests.Core/E2E/Sessions/SessionStatusE2ETests.cs

// Pobieranie sesji wsadowych
 List<Session> sessions = new List<Session>();
 const int pageSize = 20;
 string? continuationToken = null;
 do
 {
     SessionsListResponse response = await ksefClient.GetSessionsAsync(SessionType.Batch, accessToken, pageSize, continuationToken, sessionsFilter, cancellationToken).ConfigureAwait(false);
     continuationToken = response.ContinuationToken;
     sessions.AddRange(response.Sessions);
 } while (!string.IsNullOrEmpty(continuationToken));

// Pobieranie sesji interaktywnych
 List<Session> sessions = new List<Session>();
 const int pageSize = 20;
 string? continuationToken = null;
 do
 {
     SessionsListResponse response = await ksefClient.GetSessionsAsync(SessionType.Online, accessToken, pageSize, continuationToken, sessionsFilter, cancellationToken).ConfigureAwait(false);
     continuationToken = response.ContinuationToken;
     sessions.AddRange(response.Sessions);
 } while (!string.IsNullOrEmpty(continuationToken));

sessionsFilter to obiekt filtrów znajdujący się tutaj: KSeF.Client.Core/Models/Sessions/SessionsFilter.cs

Przykład w języku Java: SessionIntegrationTest.java

SessionsQueryRequest request = new SessionsQueryRequest();
request.setSessionType(SessionType.ONLINE);
request.setStatuses(List.of(CommonSessionStatus.INPROGRESS));

SessionsQueryResponse sessionsQueryResponse = ksefClient.getSessions(request, pageSize, continuationToken, accessToken();

while (Strings.isNotBlank(activeSessions.getContinuationToken())) {
        sessionsQueryResponse = ksefClient.getSessions(pageSize, sessionsQueryResponse.getContinuationToken(), accessToken);
}

2. Sprawdzenie stanu sesji

Sprawdza bieżący stan sesji.

GET sessions/{referenceNumber}

Zwraca bieżący status sesji wraz z zagregowanymi danymi o liczbie przesłanych, poprawnie i niepoprawnie przetworzonych faktur; po zamknięciu sesji udostępnia dodatkowo listę referencji do zbiorczego UPO.

Przykład w języku C#: KSeF.Client.Tests.Core/E2E/OnlineSession/OnlineSessionE2ETests.cs

SessionStatusResponse openSessionResult = await kSeFClient.GetSessionStatusAsync(referenceNumber, accessToken, cancellationToken).ConfigureAwait(false);

int documentCount = openSessionResult.InvoiceCount;
int successfulInvoiceCount = openSessionResult.SuccessfulInvoiceCount;
int failedInvoiceCount = openSessionResult.FailedInvoiceCount;

Przykład w języku Java: OnlineSessionIntegrationTest.java

SessionStatusResponse statusResponse = ksefClient.getSessionStatus(referenceNumber, accessToken);

3. Pobranie informacji na temat przesłanych faktur

GET sessions/{referenceNumber}/invoices

Zwraca listę metadanych wszystkich przesłanych faktur wraz z ich statusami oraz łączną liczbę tych faktur w sesji.

Przykład w języku C#:

const int pageSize = 50;
string continuationtoken = null;

do
{
    SessionInvoicesResponse sessionInvoices = await ksefClient
                                .GetSessionInvoicesAsync(
                                referenceNumber,
                                accessToken,
                                pageOffset,
                                pageSize,
                                cancellationToken)
                                ConfigureAwait(false);

    foreach (SessionInvoice sessionInvoice in sessionInvoices.Invoices)
    {
        Console.WriteLine($"#{sessionInvoice.InvoiceNumber}. Status: {sessionInvoice.Status.Code}");
    }

    continuationtoken = sessionInvoices.ContinuationToken;
}
while (continuationtoken != null);

Przykład w języku Java: OnlineSessionIntegrationTest.java

SessionInvoicesResponse sessionInvoices = ksefClient.getSessionInvoices(referenceNumber,continuationtoken, pageSize, authToken);

while (Strings.isNotBlank(sessionInvoices.getContinuationToken())) {
    sessionInvoices = ksefClient.getSessions(pageSize, sessionInvoices.getContinuationToken(), accessToken);
}

4. Pobranie informacji o pojedynczej fakturze

Umożliwia pobranie szczegółowych informacji o pojedynczej fakturze w sesji, w tym jej statusu i metadanych.

Należy podać numer referencyjny sesji referenceNumber oraz numer referencyjny faktury invoiceReferenceNumber.

GET sessions/{referenceNumber}/invoices/{invoiceReferenceNumber}

Przykład w języku C#:

SessionInvoice invoice = await ksefClient
                .GetSessionInvoiceAsync(
                referenceNumber,
                invoiceReferenceNumber,
                accessToken,
                cancellationToken);

Przykład w języku Java: QueryInvoiceIntegrationTest.java

SessionInvoiceStatusResponse statusResponse = ksefClient.getSessionInvoiceStatus(sessionReferenceNumber, invoiceReferenceNumber, accessToken);

5. Pobranie UPO dla faktury

Umożliwia pobranie UPO dla pojedynczej, poprawnie przyjętej faktury.

5.1 Na podstawie numery referencyjnego faktury

GET sessions/{referenceNumber}/invoices/{invoiceReferenceNumber}/upo

Przykład w języku C#:

string upo = await ksefClient
                .GetSessionInvoiceUpoByReferenceNumberAsync(
                referenceNumber,
                invoiceReferenceNumber,
                accessToken,
                cancellationToken)

Przykład w języku Java: OnlineSessionIntegrationTest.java

byte[] upoResponse = ksefClient.getSessionInvoiceUpoByReferenceNumber(sessionReferenceNumber, invoiceReferenceNumber, accessToken);

5.2 Na podstawie numeru KSeF faktury

GET sessions/{referenceNumber}/invoices/ksef/{ksefNumber}/upo

Przykład w języku C#:

var upo = await ksefClient
                .GetSessionInvoiceUpoByKsefNumberAsync(
                referenceNumber,
                ksefNumber,
                accessToken,
                cancellationToken)

Przykład w języku Java: OnlineSessionIntegrationTest.java

byte[] upoResponse = ksefClient.getSessionInvoiceUpoByKsefNumber(sessionReferenceNumber, ksefNumber, accessToken);

Otrzymany dokument XML jest:

• podpisany w formacie XADES przez Ministerstwo Finansów
• zgodny ze schematem XSD.

6. Pobranie listy niepoprawnie przyjętych faktur

GET sessions/{referenceNumber}/invoices/failed

Zwraca łączną liczbę odrzuconych faktur w sesji oraz szczegółowe informacje (status i szczegóły błędów) dla każdej niepoprawnie przetworzonej faktury.

Przykład w języku C#:

const int pageSize = 50;
string continuationToken = "";

do
{
    List<SessionInvoicesResponse> sessionInvoices = await ksefClient
                                .GetSessionFailedInvoicesAsync(
                                referenceNumber,
                                accessToken,
                                pageSize,
                                continuationToken,
                                cancellationToken);

    continuationToken = failedResult.Invoices.ContinuationToken

}
while (!string.IsNullOrEmpty(continuationToken));

Przykład w języku Java: DuplicateInvoiceIntegrationTest.java

List<SessionInvoiceStatusResponse> failedInvoicesList = new ArrayList<>();
SessionInvoicesResponse failedInvoices = ksefClient.getSessionFailedInvoices(sessionRef, null, 10, accessToken);
if (failedInvoices.getInvoices() != null && !failedInvoices.getInvoices().isEmpty()) {
    failedInvoicesList.addAll(failedInvoices.getInvoices());
}
while (Strings.isNotBlank(failedInvoices.getContinuationToken())) {
    failedInvoices = ksefClient.getSessionFailedInvoices(sessionRef, failedInvoices.getContinuationToken(), 10, accessToken);
    if (failedInvoices.getInvoices() != null && !failedInvoices.getInvoices().isEmpty()) {
        failedInvoicesList.addAll(failedInvoices.getInvoices());
    }
}

Endpoint umożliwia selektywne pobranie wyłącznie odrzuconych faktur, co ułatwia analizę błędów w sesjach zawierających dużą liczbę faktur.

7. Pobranie UPO sesji

UPO sesji stanowi zbiorcze poświadczenie przyjęcia wszystkich faktur poprawnie przesłanych w ramach danej sesji.

Po zamknięciu sesji, w odpowiedzi na sprawdzenie jej stanu (krok 2 – Sprawdzenie stanu sesji), zwracane są nie tylko informacje o liczbie poprawnie i błędnie przetworzonych faktur, lecz także lista referencji do zbiorczych UPO.

Każdy element tablicy upo.pages[] zawiera numer referencyjny UPO (referenceNumber) oraz link (downloadUrl) umożliwiający jego pobranie:

"upo": {
    "pages": [
        {
            "referenceNumber": "20250901-EU-47FDBE3000-5961A5D232-BF",
            "downloadUrl": "/api/v2/sessions/20250901-SB-47FA636000-5960B49115-9D/upo/20250901-EU-47FDBE3000-5961A5D232-BF"
        },
        {
            "referenceNumber": "20250901-EU-48D8488000-59667BB54C-C8",
            "downloadUrl": "/api/v2/sessions/20250901-SB-47FA636000-5960B49115-9D/upo/20250901-EU-48D8488000-59667BB54C-C8"
        }        
    ]
}

Dysponując tą listą, klient API może pobrać UPO pojedynczo, wywołując endpoint wskazany w polu downloadUrl, tj.
GET /sessions/{referenceNumber}/upo/{upoReferenceNumber}

Otrzymany dokument XML jest zgodny ze schematem XSD i może zawierać maksymalnie 10 000 pozycji faktur.

Przykład w języku C#:

 string upo = await ksefClient.GetSessionUpoAsync(
            sessionReferenceNumber,
            upoReferenceNumber,
            accessToken,
            cancellationToken
        );

Przykład w języku Java: OnlineSessionIntegrationTest.java

byte[] sessionUpo = ksefClient.getSessionUpo(sessionReferenceNumber, upoReferenceNumber, accessToken);

Powiązane dokumenty

• Numer KSeF – struktura i walidacja