KSeF 2.0 Docs

English

Polski
Русский
Українська

English

Polski
Русский
Українська

Appearance

Translation. Original: pobieranie-faktur/pobieranie-faktur.md

Downloading Invoices ​

Downloading Invoice by KSeF Number ​

21.08.2025

Returns an invoice with the specified KSeF number.

GET /invoices/ksef/{ksefNumber}

C# example: KSeF.Client.Tests.Core\E2E\Invoice\InvoiceE2ETests.cs

csharp
string invoice = await ksefClient.GetInvoiceAsync(ksefReferenceNumber, accessToken, cancellationToken);

Java example:

OnlineSessionIntegrationTest.java

java
byte[] invoice = ksefClient.getInvoice(ksefNumber, accessToken);

Downloading List of Invoice Metadata ​

Returns a list of invoice metadata that meets the specified search criteria.

_metadata.json file in the export package
The export package contains a _metadata.json file containing an array of InvoiceMetadata objects (model returned by POST /invoices/query/metadata - "Downloading invoice metadata").

POST /invoices/query/metadata

C# example: KSeF.Client.Tests.Core\E2E\Invoice\InvoiceE2ETests.cs

csharp
InvoiceQueryFilters invoiceQueryFilters = new InvoiceQueryFilters
{
    SubjectType = InvoiceSubjectType.Subject1,
    DateRange = new DateRange
    {
        From = DateTime.UtcNow.AddDays(-30),
        To = DateTime.UtcNow,
        DateType = DateType.Issue
    }
};

PagedInvoiceResponse pagedInvoicesResponse = await ksefClient.QueryInvoiceMetadataAsync(
    invoiceQueryFilters, 
    accessToken, 
    pageOffset: 0, 
    pageSize: 10, 
    cancellationToken);

Java example:

QueryInvoiceIntegrationTest.java

java
InvoiceQueryFilters request = new InvoiceQueryFiltersBuilder()
        .withSubjectType(InvoiceQuerySubjectType.SUBJECT1)
        .withDateRange(
                new InvoiceQueryDateRange(InvoiceQueryDateType.INVOICING, OffsetDateTime.now().minusYears(1),
                        OffsetDateTime.now()))
        .build();

QueryInvoiceMetadataResponse response = ksefClient.queryInvoiceMetadata(pageOffset, pageSize, SortOrder.ASC, request, accessToken);

Initialize Asynchronous Query for Invoice Download ​

Starts an asynchronous process of searching for invoices in the KSeF system based on the provided filters. It is required to provide encryption information in the encryption field, which is used to encrypt the generated invoice packages.

POST /invoices/exports

C# example: KSeF.Client.Tests.Core\E2E\Invoice\InvoiceE2ETests.cs

csharp
EncryptionData encryptionData = CryptographyService.GetEncryptionData();

InvoiceQueryFilters query = new InvoiceQueryFilters
{
    DateRange = new DateRange
    {
        From = DateTime.Now.AddDays(-1),
        To = DateTime.Now.AddDays(1),
        DateType = DateType.Invoicing
    },
    SubjectType = InvoiceSubjectType.Subject1
};

InvoiceExportRequest invoiceExportRequest = new InvoiceExportRequest
{
    Encryption = encryptionData.EncryptionInfo,
    Filters = query
};

OperationResponse invoicesForSellerResponse = await KsefClient.ExportInvoicesAsync(
    invoiceExportRequest,
    _accessToken,
    CancellationToken);

Available DateType and SubjectType values are described here.

Invoices in the package are sorted in ascending order by the date type specified in DateRange during export initialization.

Java example:

QueryInvoiceIntegrationTest.java

java
InvoiceExportFilters filters = new InvoicesAsyncQueryFiltersBuilder()
        .withSubjectType(InvoiceQuerySubjectType.SUBJECT1)
        .withDateRange(
                new InvoiceQueryDateRange(InvoiceQueryDateType.INVOICING, OffsetDateTime.now().minusDays(10), OffsetDateTime.now().plusDays(10)))
        .build();

InvoiceExportRequest request = new InvoiceExportRequest(
        new EncryptionInfo(encryptionData.encryptionInfo().getEncryptedSymmetricKey(),
                encryptionData.encryptionInfo().getInitializationVector()), filters);

InitAsyncInvoicesQueryResponse response = ksefClient.initAsyncQueryInvoice(request, accessToken);

Check Status of Asynchronous Invoice Download Query ​

Retrieves the status of a previously initialized asynchronous query based on the operation identifier. Enables tracking the progress of query processing and downloading ready packages with results, if they are already available.

GET /invoices/exports/{referenceNumber}

C# example: KSeF.Client.Tests.Core\E2E\Invoice\InvoiceE2ETests.cs

csharp
InvoiceExportStatusResponse exportStatus = await KsefClient.GetInvoiceExportStatusAsync(
    exportInvoicesResponse.ReferenceNumber,
    accessToken);

Java example:

QueryInvoiceIntegrationTest.java

java
InvoiceExportStatus response = ksefClient.checkStatusAsyncQueryInvoice(referenceNumber, accessToken);