Skip to content

Client Setup

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

Section titled “Choose sync or async”
from ksef2 import Client, Environment


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

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

Public root branches

Section titled “Public root branches”

The root client is useful before authentication:

certificates = client.encryption.get_certificates()
providers = client.peppol.query()

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

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

Authenticated branches

Section titled “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
Section titled “Recommended flow”

  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

Section titled “Reference”