ksef2 0.2.0

Python SDK and Tools for Poland's KSeF (Krajowy System e-Faktur) API

Python SDK and Tools for Poland's KSeF (Krajowy System e-Faktur) v2.0 API.

Installation

uv add ksef2

Requires Python 3.12+.

Quick Start

from ksef2 import Client, Environment, FormSchema
from ksef2.core.xades import generate_test_certificate

VALID_NIP = "5261040828"

client = Client(Environment.TEST)

# XAdES Authentication (TEST environment) - generates self-signed certificate automatically
cert, private_key = generate_test_certificate(VALID_NIP)
tokens = client.auth.authenticate_xades(
    nip=VALID_NIP,
    cert=cert,
    private_key=private_key,
)

# Send invoice
with client.sessions.open_online(
    access_token=tokens.access_token.token,
    form_code=FormSchema.FA3,
) as session:
    with open("invoice.xml", "rb") as f:
        result = session.send_invoice(f.read())
    print(result.reference_number)

# Sessions also support manual management:
session = client.sessions.open_online(
    access_token=tokens.access_token.token,
    form_code=FormSchema.FA3,
)
try:
    with open("invoice.xml", "rb") as f:
        result = session.send_invoice(f.read())
    print(result.reference_number)
finally:
    session.terminate()

Token Authentication

For production, or when you have a pre-generated KSeF token:

from ksef2 import Client, Environment

client = Client(Environment.TEST)

tokens = client.auth.authenticate_token(
    ksef_token="your-ksef-token",
    nip=VALID_NIP,
)
print(tokens.access_token.token)

Development

just sync          # Install all dependencies (including dev)
just test          # Run unit tests
just regenerate-models  # Regenerate OpenAPI models

Other commands

just integration   # Run integration tests (requires KSEF credentials in .env)
just coverage       # Calculate API coverage (updates coverage.json)
just fetch-spec     # Fetch latest OpenAPI spec from KSeF

API Coverage

The SDK currently covers 33 of 77 KSeF API endpoints (43%). Calculated via scripts/api_coverage.py. See individual feature docs for endpoint details:

• Authentication
• Invoices
• Sessions
• Tokens
• Test Data
• Limits

License

MIT