Stacking
PL/EN
Start
ksef2
GitHub

How-to Guide Overview

Choose the right task guide for the public ksef2 SDK surface.

Edit this pagev0.22.2 · b4b3eb9
On this page

Use this section when you already know the SDK shape and want to complete a specific KSeF task. The quickstart shows one end-to-end path; these how-to guides separate the decisions you usually make in production code.

Setup

  • Set up clients: Choose sync or async, public root branches, and authenticated workflow branches.
  • Authenticate: Choose TEST certificates, KSeF tokens, XAdES certificates, environment variables, or CLI-compatible profiles.
  • Use profiles: Share local ksef2-cli profile configuration with SDK authentication and ProfileStore.

Invoice work

  • Build FA(3) invoices: Generate simple public invoice models and sendable FA(3) XML with the fluent builder.
  • Send invoices: Submit FA(3) XML through online sessions or batch sessions, then inspect processing results.
  • Check status and UPO: Poll online or batch status, list session invoices, and retrieve UPO documents.
  • Query invoices: Build metadata filters, page through results, and poll until newly sent invoices are visible.
  • Download invoices: Download one processed invoice by KSeF number or schedule encrypted export packages.

Administration

  • Manage tokens: Generate, list, inspect, and revoke KSeF tokens for automation.
  • Manage permissions: Grant, query, revoke, and monitor KSeF permissions.
  • Manage certificates: Check limits, enroll certificates, retrieve issued material, and revoke certificates.
  • Manage limits: Read and override context, subject, and API rate limits.

Utilities

  • Inspect encryption certificates: Inspect public KSeF certificates used by encrypted invoice and export workflows.
  • Query PEPPOL providers: Query public PEPPOL provider data from the root client.
  • Use TEST data: Create sandbox subjects, permissions, attachment flags, and temporal cleanup fixtures.
  • Use XAdES helpers: Load certificate material, generate TEST certificates, and sign XML.
  • Low-level API: Drop to schema-native endpoint wrappers for custom signing, encryption custody, or payload debugging.

Typical production order

  1. Configure the environment and credentials.

    Use environment variables for secrets and local config for non-secret profile defaults.

  2. Authenticate once for the target context.

    The authenticated client exposes online_session, batch, invoices, tokens, permissions, certificates, and other workflow branches.

  3. Run the workflow branch that owns the task.

    Use public root branches for encryption certificates, PEPPOL lookup, and TEST data. Use authenticated branches for invoices, sessions, tokens, permissions, certificates, and limits.

  4. Poll for KSeF processing or operation status.

    The high-level helpers include polling methods for invoice status, batch completion, permission operations, certificate enrollment, query visibility, and export package readiness.

  5. Persist the business result.

    Store KSeF numbers, session references, operation references, export handles, downloaded XML, token references, certificate serial numbers, and UPO documents according to your application’s retention policy.

Reference

  • Quickstart: Run the first generate, send, confirm, and download workflow.
  • Operations: Map common tasks to SDK branches, polling helpers, and retry boundaries.
  • Public API contract: Review stable imports and public modules exposed by the SDK.
  • Low-level API: Use schema-native endpoint wrappers when a high-level workflow is not enough.