ksef2

Biblioteka Python do Krajowego Systemu e-Faktur (KSeF 2.0): typowane klienci synchroniczny i asynchroniczny dla API FA(3), bez ręcznego pisania żądań HTTP, pollingu ani obsługi szyfrowania.

What is ksef2?

ksef2 is a community-maintained Python SDK for Poland's KSeF v2 API. It is designed for developers building custom integrations, automations, back-office tools, and invoice-processing pipelines around KSeF without hand-writing HTTP requests, polling loops, or encryption handling.

This project is not published, endorsed, or supported by Poland's Ministry of Finance. Official KSeF documentation remains the source of truth for API behavior.

The SDK currently targets KSeF OpenAPI version 2.9.0.

Install

# standard pip installation
pip install ksef2

# install with uv inside an application project
uv add ksef2

Requires Python 3.12 or newer.

Optional extras:

pip install "ksef2[pdf]"             # local invoice PDF rendering
pip install "ksef2[runtime-checks]"  # optional beartype runtime checks

Runtime checks are disabled unless KSEF2_RUNTIME_CHECKS=1 is set.

The CLI is distributed separately under stacking-hq/ksef2-cli. Install it when you want terminal workflows, scriptable commands, or local profiles:

uv tool install ksef2-cli
# or
pipx install ksef2-cli

Authenticate

Use the authentication method that matches the environment you are working with.

from pathlib import Path

from ksef2 import Client, Environment
from ksef2.xades import (
    load_certificate_from_pem,
    load_private_key_from_pem
)

client = Client(Environment.TEST)

# local TEST workflows can use an SDK-generated certificate.
test = client.authentication.with_test_certificate(nip="5261040828")

# token authentication works when you already have a KSeF token.
token = client.authentication.with_token(
    ksef_token="your-ksef-token",
    nip="5261040828",
)

# DEMO and PRODUCTION can authenticate with an MCU-issued XAdES certificate.
cert = load_certificate_from_pem(Path("company.pem"))
key = load_private_key_from_pem(Path("company.key"))

xades = Client(Environment.DEMO).authentication.with_xades(
    nip="5261040828",
    cert=cert,
    private_key=key,
)

# you can also use CLI profiles to avoid handling certificates and tokens directly in your code
profile = client.authentication.with_profile("test-company")

ksef2-cli profiles

The separate ksef2-cli package provides local profiles for repeated CLI work. Profiles store non-secret defaults such as environment, NIP, authentication method, certificate paths, and the environment variable that contains a secret.

CLI profile setup:

ksef2 profile create prod-token \
  --env production \
  --nip 5261040828 \
  --token-env KSEF2_TOKEN

# profile create activates the new profile by default, use this to switch between contexts
ksef2 profile use prod-token

# example usage of the cli
ksef2 --profile prod-token invoices list \
  --role seller \
  --date-from 2026-01-01T00:00:00Z

These commands add a profile to the local ksef2-cli configuration at ~/.config/ksef2/config.toml. Existing legacy ~/.config/ksef2-cli/config.toml files are still read when present.

# ksef2-cli local profiles
# CLI options override the selected profile for one invocation.
# Store token and password secrets in environment variables.
active_profile = "prod-token"

[profiles.prod-token]
environment = "production"
nip = "5261040828"

[profiles.prod-token.auth]
type = "token"
token_env = "KSEF2_TOKEN"

Use defined profiles in the SDK:

from ksef2 import Client, Environment
from ksef2.profiles import Profile, ProfileStore, TokenProfileAuth

store = ProfileStore.default()
store.save(
    "prod-token",
    Profile(
        environment=Environment.PRODUCTION,
        nip="5261040828",
        auth=TokenProfileAuth(token_env="KSEF2_TOKEN"),
    ),
    activate=True,
    overwrite=True,
)

# match the profile and client environments.
client = Client(Environment.PRODUCTION)

# defaults to the currently active profile in the CLI configuration.
active = client.authentication.with_profile()

# or specify which profile to use explicitly.
seller = client.authentication.with_profile("prod-token")

Send and download an invoice

from pathlib import Path

from ksef2 import Client, Environment, FormSchema

client = Client(Environment.TEST)
auth = client.authentication.with_test_certificate(nip="5261040828")

with auth.online_session(form_code=FormSchema.FA3) as session:
    status = session.send_invoice(Path("invoice.xml").read_bytes()).wait(timeout=60.0)

invoice_xml = auth.invoices.download(status.ksef_number, timeout=120.0)

Path("downloads").mkdir(exist_ok=True)
Path("downloads/invoice.xml").write_bytes(invoice_xml)
print(status.ksef_number)

Use auth.invoices for metadata queries, exports, package downloads, and direct invoice downloads after KSeF assigns invoice numbers.

Documentation

• Online docs: https://docs.stackinghq.com/ksef2/sdk/getting-started/overview/
• Quickstart: https://docs.stackinghq.com/ksef2/sdk/getting-started/quickstart/
• How-to guides: https://docs.stackinghq.com/ksef2/sdk/how-to-guides/overview/
• Public API contract: https://docs.stackinghq.com/ksef2/sdk/reference/public-api/
• Python API reference: https://docs.stackinghq.com/ksef2/sdk/reference/api/ksef2/
• Source docs: docs/en and docs/pl
• Runnable examples: scripts/examples

Development

just sync
just test
just release-check

Additional development tasks live in the justfile, including integration tests, API coverage checks, OpenAPI model regeneration, and release tooling.

For package releases, follow the maintainer release instructions.

Contributing

Issues and pull requests are welcome. Before opening a PR, run the focused test or docs build that covers your change, and update both source docs and examples when behavior changes.

For SDK docs, edit the source catalog under docs/en and docs/pl. The public documentation site syncs from those files.

License

MIT