KsefLab.Client 10.1.2

KsefLab.Client

⚠️ This library is a client for the KSEFLAB.pl API, not a direct client for the official KSeF API (Ministerstwo Finansów).

HTTP client for the KsefLab.pl API.

Formerly published as PikSystems.Ksef.Client (up to version 10.1.1). Renamed to KsefLab.Client to make clear that this client only ever talks to kseflab.pl, never directly to the government KSeF API. Versioning continues from the previous name - this is 10.1.2. Only KsefLab.Client is maintained going forward; PikSystems.Ksef.Client will not receive further releases.

example usage

Install (NuGet)

dotnet add package KsefLab.Client

Usage

using PikSystems.Ksef.Client;
using PikSystems.Ksef.Client.Contracts;

var client = KsefApiClient.Create(
    KsefApiEnvironment.Test,
    "YOUR_API_KEY");

var invoice = new InvoiceRequest
{
    Profile = InvoiceProfile.BasicVat,
    IssueDate = DateTime.UtcNow.Date,
    Currency = "PLN",
    Buyer = new PartyRequest
    {
        Name = "Acme Sp. z o.o.",
        Nip = "1234567890",
        Address = "Warszawa"
    },
    Items = new List<InvoiceItemRequest>
    {
        new InvoiceItemRequest
        {
            Name = "Usługa",
            Quantity = 1,
            NetPrice = 100,
            VatRate = 23,
            Unit = "szt"
        }
    }
};

var created = await client.SendInvoiceAsync(invoice);
var currentMonth = await client.GetInvoicesForCurrentMonthAsync();
var previousMonth = await client.GetInvoicesForPreviousMonthAsync();
var customRange = await client.GetInvoicesByDateRangeAsync(
    new DateOnly(2026, 6, 1),
    new DateOnly(2026, 6, 30));

// status by invoice id
var status = await client.GetInvoiceAsync(created.InvoiceId);

// store KSeF token (Key Vault reference)
await client.StoreKsefCredentialsAsync(new KsefCredentialsRequest
{
    Type = "Token",
    Value = "YOUR_KSEF_TOKEN"
});

You can also create the client explicitly by URL:

var client = KsefApiClient.Create("https://piksystems-dev-api-kseflab.azurewebsites.net", "YOUR_API_KEY");

Available environment URLs:

• KsefApiEnvironment.Test → https://piksystems-dev-api-kseflab.azurewebsites.net
• KsefApiEnvironment.Prod → https://api.kseflab.pl

The client always talks to the KsefLab.pl API, never directly to the government KSeF portal - KsefLab handles the KSeF submission on your behalf.

Invoice Status After Import

You can import invoice metadata and then fetch full status from the API.

var imported = await client.GetInvoicesForCurrentMonthAsync(pageSize: 50);
if (imported.Invoices.Count > 0)
{
    // If you store invoiceId in your system, call by id
    var status = await client.GetInvoiceAsync(created.InvoiceId);
}

Previous Month Import

var previous = await client.GetInvoicesForPreviousMonthAsync(pageOffset: 0, pageSize: 50);

Date Range Import

var range = await client.GetInvoicesByDateRangeAsync(
    new DateOnly(2026, 6, 1),
    new DateOnly(2026, 6, 30),
    pageOffset: 0,
    pageSize: 50,
    direction: "received");

Get By KSeF Number

var statusByNumber = await client.GetInvoiceByKsefNumberAsync("KSEF_NUMBER");

Pagination

GetInvoicesForCurrentMonthAsync, GetInvoicesForPreviousMonthAsync and GetInvoicesByDateRangeAsync accept:

• pageOffset
• pageSize
• direction (passed as query parameter: issued or received)

Automation Tokens (n8n, make.com, curl one-liners)

Every call this client makes is signed with HMAC (timestamp + nonce + body hash) using your API key - fine in .NET, but impractical in tools that have no easy way to compute that signature. Automation tokens are a second, Bearer-only credential you exchange your API key for once; the server accepts them without a signature.

var automation = await client.CreateAutomationTokenAsync(new AutomationTokenRequest
{
    Name = "n8n",
    Scopes = new[] { "invoice:write" } // optional - defaults to your API key's own scopes
});

Console.WriteLine(automation.AutomationToken); // shown once, starts with auto_test_/auto_live_

Paste automation.AutomationToken directly into n8n's or make.com's plain Bearer-token credential field - no signing logic needed on their side. If you build a client against this same automation token yourself, KsefApiClient.Create(environment, automationToken) also works: the library detects the auto_test_/auto_live_ prefix and skips signing automatically.

Revoke a token you no longer want to honor:

await client.RevokeAutomationTokenAsync(automation.TokenId);

Automation-token scopes can only narrow your API key's scopes, never widen them - requesting a scope your key doesn't have returns a 400.

Errors

Non-2xx responses throw HttpRequestException with the response payload.

Notes

• The client signs requests using Authorization + X-KSeF-* headers.
• GetInvoicesForCurrentMonthAsync calls /api/invoices/import.
• GetInvoicesForPreviousMonthAsync calls /api/invoices/import?period=last.
• GetInvoicesByDateRangeAsync calls /api/invoices/import/by-date?dateFrom=...&dateTo=....