Skip to content

Python-KSEF Documentation

A Python library for the Polish KSEF (National e-Invoice System, Krajowy System e-Faktur).

Early Development

This library is in early alpha development. The API may change between versions.

Features

  • Token Authentication - Authenticate using KSeF tokens
  • XAdES Authentication - Authenticate using qualified certificates
  • Send Invoices - Submit invoices to KSEF with encryption
  • Download Invoices - Retrieve invoice XML by KSEF reference number
  • FA(3) Schema - Full support for the latest invoice schema

Quick Start

Installation

pip install ksef

Or with uv:

uv add ksef

Send an Invoice

from datetime import date, datetime, timezone
from decimal import Decimal

from ksef.auth.token import TokenAuthorization
from ksef.client import Client
from ksef.constants import Environment
from ksef.models.invoice import (
    Address, Invoice, InvoiceData, InvoiceType,
    Issuer, IssuerIdentificationData, Subject, SubjectIdentificationData,
)
from ksef.models.invoice_annotations import (
    InvoiceAnnotations, TaxSettlementOnPayment, SelfInvoicing,
    ReverseCharge, SplitPayment, FreeFromVat,
    IntraCommunitySupplyOfNewTransportMethods,
    SimplifiedProcedureBySecondTaxPayer, MarginProcedure,
)
from ksef.models.invoice_rows import InvoiceRow, InvoiceRows

# Authenticate
auth = TokenAuthorization(token="your-token", environment=Environment.TEST)
auth.authorize(nip="1234567890")
client = Client(authorization=auth, environment=Environment.TEST)

# Create invoice
invoice = Invoice(
    issuer=Issuer(
        identification_data=IssuerIdentificationData(
            nip="1234567890",
            full_name="My Company Sp. z o.o.",
        ),
        address=Address(
            country_code="PL",
            city="Warszawa",
            street="Przykładowa",
            house_number="1",
            apartment_number=None,
            postal_code="00-001",
        ),
        email="contact@example.com",
        phone="+48 123456789",
    ),
    recipient=Subject(
        identification_data=SubjectIdentificationData(nip="0987654321"),
    ),
    invoice_data=InvoiceData(
        currency_code="PLN",
        issue_date=date.today(),
        issue_number="FV/2026/001",
        sell_date=date.today(),
        total_amount=Decimal("1230.00"),
        invoice_type=InvoiceType.REGULAR_VAT,
        invoice_rows=InvoiceRows(rows=[
            InvoiceRow(name="Consulting services", tax=23),
        ]),
        invoice_annotations=InvoiceAnnotations(
            tax_settlement_on_payment=TaxSettlementOnPayment.REGULAR,
            self_invoice=SelfInvoicing.NO,
            reverse_charge=ReverseCharge.NO,
            split_payment=SplitPayment.NO,
            free_from_vat=FreeFromVat.NO,
            intra_community_supply_of_new_transport_methods=IntraCommunitySupplyOfNewTransportMethods.NO,
            simplified_procedure_by_second_tax_payer=SimplifiedProcedureBySecondTaxPayer.NO,
            margin_procedure=MarginProcedure.NO,
        ),
    ),
    creation_datetime=datetime.now(tz=timezone.utc),
)

# Send invoice
response = client.send_invoice(nip="1234567890", invoice=invoice)
print(f"Submitted! Reference: {response.reference_number}")

Documentation

Environments

Environment URL Purpose
Environment.TEST api-test.ksef.mf.gov.pl Testing and development
Environment.DEMO api-demo.ksef.mf.gov.pl Demo/sandbox
Environment.PRODUCTION api.ksef.mf.gov.pl Production (live invoices)