Stacking
PL/EN
Kontakt
ksef2
GitHub
ksef2Open source, MIT

Typowany Python do fakturowania w KSeF 2.0.

ksef2 przejmuje uwierzytelnianie, sesje, szyfrowanie i odpytywanie statusów, więc kod integracji wygląda jak sam proces: logujesz się, wysyłasz faktury FA(3), pobierasz to, co zwraca KSeF.

Przejdź do quickstartuZobacz na GitHubie
pip install ksef2

Wymaga Pythona 3.12 lub nowszego. CLI instalujesz osobno: uv tool install ksef2-cli

send_invoice.py
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)
print(status.ksef_number)

Wszystko pomiędzy Twoim systemem a KSeF.

Klient jest podzielony według zadań. Uwierzytelniasz się raz, a uwierzytelniony klient udostępnia gałąź odpowiedzialną za każde zadanie — każda ma własny poradnik.

2.8.1
Wersja OpenAPI KSeF, pod którą zbudowane jest SDK
83 / 83
Pokrytych endpointów API, sprawdzanych codziennie z opublikowaną specyfikacją
sync + async
Client i AsyncClient mają te same gałęzie i nazwy metod

  • Uwierzytelnianie

    Certyfikaty testowe generowane przez SDK, tokeny KSeF, certyfikaty XAdES wydane przez MCU lub profil współdzielony z ksef2-cli.

    • with_test_certificate
    • with_token
    • with_xades
    • with_profile

  • Sesje interaktywne i wsadowe

    Wysyłaj XML FA(3) pojedynczo albo jako paczkę wsadową, czekaj na przetworzenie i odbierz UPO.

    • online_session
    • batch_session
    • invoice_sessions.download_upo

  • Wyszukiwanie, pobieranie, eksport

    Filtruj metadane faktur, przechodź przez kolejne strony wyników, pobieraj fakturę po numerze KSeF lub zlecaj szyfrowane paczki eksportu.

    • invoices.search
    • invoices.download
    • invoices.export

  • Builder FA(3)

    Twórz gotowy do wysyłki XML FA(3) płynnym, typowanym builderem zamiast pisać XML ręcznie. Szkice można zapisać i wznowić.

    • FA3InvoiceBuilder
    • to_xml

  • Administracja

    Generuj i unieważniaj tokeny, nadawaj i sprawdzaj uprawnienia, wnioskuj o certyfikaty, odczytuj i nadpisuj limity.

    • tokens
    • permissions
    • certificates
    • limits

  • Niskopoziomowe API

    Wrappery endpointów zgodne ze schematem, gdy potrzebujesz własnego podpisu, własnego zarządzania szyfrowaniem lub surowych payloadów do debugowania.

    • client.raw
    • auth.raw
    • ksef2.raw.spec
Faktury FA(3) budowane w Pythonieksef2.fa3
builder = (
    FA3InvoiceBuilder()
    .header(system_info="my app")
    .seller(
        name="ACME S.A.",
        tax_id="1234567890",
        country_code="PL",
        address_line_1="ul. Przykladowa 123",
    )
    .buyer(
        name="XYZ GmbH",
        country_code="DE",
        address_line_1="Unter den Linden 1",
    )
    .standard()
        .issue_place("Warszawa")
        .issue_date(date(2026, 3, 29))
        .invoice_number("FV/2026/03/0001")
        .rows()
            .add_line(
                name="Consulting service",
                supply_date=date(2026, 3, 29),
                unit_of_measure="h",
                quantity=Decimal("10"),
                unit_price_net=Decimal("100.00"),
                vat_rate=VatRate.VAT_23,
            )
        .done()
    .done()
)

xml_text = builder.to_xml()
Otwórz poradnik buildera

Jedna faktura, od początku do końca.

Te same cztery kroki — w Pythonie albo ze skryptu powłoki czy joba CI.

  1. 01

    Uwierzytelnij się

    Wybierz metodę pasującą do środowiska. Sekrety zostają w zmiennych środowiskowych.

    SDK

    login = client.authentication
auth = login.with_token(
    ksef_token=token,
    nip="5261040828",
)

    CLI

    ksef2 --profile test-company \
  auth login
  2. 02

    Otwórz sesję

    Interaktywną dla pojedynczych faktur, wsadową dla wielu. Sesja zamyka się sama po wyjściu z bloku.

    SDK

    with auth.online_session(
    form_code=FormSchema.FA3,
) as session:

    CLI

    ksef2 invoices send \
  invoice-1.xml invoice-2.xml \
  --mode batch
  3. 03

    Wyślij i poczekaj

    Bez ręcznych pętli odpytujących: czekasz, aż KSeF przetworzy fakturę i nada jej numer.

    SDK

    status = session.send_invoice(
    xml,
).wait(timeout=60.0)

    CLI

    ksef2 invoices send \
  invoice.xml --wait
  4. 04

    Pobierz fakturę i UPO

    Pobierz XML faktury i urzędowe poświadczenie odbioru — od razu albo później, z zapisanego potwierdzenia.

    SDK

    auth.invoices.download(
    status.ksef_number,
)

    CLI

    ksef2 invoices upo \
  --receipt invoice-receipt.json

Zacznij od dokumentacji.

SDK i CLI są opisane tutaj, po polsku i po angielsku.

Pakiety

ksef2 jest rozwijane społecznościowo przez Stacking. Nie jest publikowane, zatwierdzane ani wspierane przez Ministerstwo Finansów, a źródłem prawdy o działaniu API pozostaje oficjalna dokumentacja KSeF. Oficjalna dokumentacja API KSeF