Stacking
PL/EN
Start
ksef2
GitHub

Client Setup

Create ksef2 sync and async clients, configure transport behavior, and choose authenticated branches.

Edit this pagev0.22.2 · b4b3eb9
On this page

The root Client owns HTTP transport configuration and exposes unauthenticated public branches. Authenticate once for a KSeF context, then pass the authenticated client into workflow code.

Choose sync or async

Client is the synchronous root client and AsyncClient is its async twin. They expose the same API; with AsyncClient you use async with and await the calls.

Sync

from ksef2 import Client, Environment

with Client(Environment.TEST) as client:
    auth = client.authentication.with_test_certificate(nip="5261040828")
python

Async

from ksef2 import AsyncClient, Environment

async with AsyncClient(Environment.TEST) as client:
    auth = await client.authentication.with_test_certificate(nip="5261040828")
python

Use Environment.DEMO or Environment.PRODUCTION outside local TEST workflows.

Manage lifecycle

The root client owns SDK-managed HTTP resources. Prefer a context manager for scripts and jobs:

from ksef2 import Client, Environment

with Client(Environment.TEST) as client:
    auth = client.authentication.with_test_certificate(nip="5261040828")
python

If a framework asks for a yielded dependency, put the yield inside the dependency function and close the client in finally:

from collections.abc import Iterator

from ksef2 import Client, Environment

def get_client() -> Iterator[Client]:
    client = Client(Environment.TEST)
    try:
        yield client
    finally:
        client.close()
python

Async applications use the same boundary with async with:

from ksef2 import AsyncClient, Environment

async with AsyncClient(Environment.TEST) as client:
    auth = await client.authentication.with_test_certificate(nip="5261040828")
python

Online and batch sessions are lifecycle boundaries too. Use a session context manager so the SDK closes the remote session when the block exits:

from ksef2 import FormSchema

with auth.online_session(form_code=FormSchema.FA3) as session:
    status = session.send_invoice(invoice_xml).wait()
python

When credentials live in a CLI-compatible profile, create the root client for the profile environment and authenticate through with_profile():

from ksef2 import Client, Environment

client = Client(Environment.PRODUCTION)
auth = client.authentication.with_profile("prod-token")
python

Public root branches

The root client is useful before authentication:

certificates = client.encryption.get_certificates()
providers = client.peppol.list().first_page()
python

The TEST-only branch is also on the root client:

client.testdata.create_subject(
    nip="5261040828",
    subject_type="vat_group",
    description="Sandbox company",
)
python

Authenticated branches

After authentication, use the branch that matches the task:

invoices = auth.invoices
batch = auth.batch
tokens = auth.tokens
permissions = auth.permissions
certificates = auth.certificates
limits = auth.limits
sessions = auth.sessions
invoice_sessions = auth.invoice_sessions
python

  1. Read environment and transport settings in your application boundary.

  2. Create one root client for the selected KSeF environment.

  3. Use root branches only for public lookup or TEST data setup.

  4. Authenticate once for the context that owns the operation.

  5. Pass the authenticated client to invoice, token, permission, certificate, limits, and session workflows.

Reference