Stacking
PL/EN
Start
ksef2
GitHub

SDK Overview

Understand the main objects, workflow boundaries, and nouns used by ksef2.

Edit this pagev0.22.2 · b4b3eb9
On this page

ksef2 is organized around a few long-lived entry points and short-lived KSeF workflows. The root Client or AsyncClient chooses the environment and owns transport configuration. Authentication turns that root client into an authenticated client for one taxpayer context. Sessions are then opened only for workflows that KSeF models as sessions.

Use this section when you need to understand the shape of a KSeF workflow before writing code. Use the how-to guides when you already know the task and want the SDK calls.

See also:

  • Foundations: Start with root clients, authenticated clients, environments, and lifecycle ownership.
  • Authentication and security: Understand login context, authenticating subject, certificates, encryption, and XAdES.
  • Invoice workflows: Follow sessions, invoice processing, UPO, metadata queries, downloads, and exports.
  • Administration: Understand tokens, permission operations, certificates, limits, and PEPPOL lookup.

How the SDK maps the official API

The official KSeF API documentation groups work into access, interactive sending, batch sending, status and UPO, invoice retrieval, tokens, permissions, certificates, limits, public encryption certificates, and PEPPOL. The SDK keeps the same conceptual boundaries and exposes them as branches on the root or authenticated client.

Official API areaSDK view
Accessclient.authentication creates an authenticated client for one context.
Interactive and batch sendingauth.online_session() and auth.batch_session() own sending-session state.
Status and UPOSession clients and auth.invoice_sessions inspect remote processing and confirmations.
Invoice retrievalauth.invoices owns metadata queries, exports, direct downloads, and package download.
Tokens, permissions, certificates, limitsAdministrative branches on the authenticated client.
Public dataRoot-client branches such as client.encryption, client.peppol, and TEST data.

The low-level raw branches exist for custom protocol work, diagnostics, and exact KSeF payload debugging. They are public, but they are not the normal starting point for application code.

Main nouns

NounWhat it means in the SDK
Root clientThe unauthenticated client that owns environment and HTTP transport.
Authenticated clientA client branch bound to redeemed KSeF access and refresh tokens for one context.
Online sessionA short-lived sending context for individual encrypted invoice submissions.
Batch sessionA short-lived sending context for prepared encrypted batch packages.
Invoice serviceThe authenticated branch for metadata queries, exports, direct downloads, and export package download.
Reference numberA handle returned by KSeF for sessions, invoices, exports, tokens, permissions, and other asynchronous work.
KSeF numberThe identifier assigned after KSeF accepts and processes an invoice.
UPOOfficial confirmation available after a session or invoice reaches the required processed state.

What belongs where

Use the root client for public lookup and setup:

  • client.authentication to start authentication.
  • client.encryption to inspect public encryption certificates.
  • client.peppol to query public PEPPOL provider data.
  • client.testdata in Environment.TEST only.

Use the authenticated client for context-specific work:

  • auth.online_session() and auth.batch_session() for sending.
  • auth.invoices for metadata, exports, and downloads.
  • auth.tokens, auth.permissions, auth.certificates, and auth.limits for administrative workflows.
  • auth.sessions and auth.invoice_sessions for session management and history.
  • Environments: Choose TEST, DEMO, or PRODUCTION and keep state scoped to that environment.
  • Clients and lifecycle: Understand root clients, authenticated clients, sessions, and export handles.
  • Authentication methods: Choose token, XAdES, TEST certificate, or profile-based authentication.
  • Sessions: Understand online, batch, authentication, and historical invoice sessions.
  • Invoice lifecycle: Trace invoice submission through processing, KSeF number assignment, retrieval, and UPO.
  • Client and service API: Use the generated API reference when you need the full object and method inventory.
  • Official KSeF API guide: Source documentation for the KSeF 2.0 API concepts.