Skip to content

README.md

Latest commit

 

History

History
94 lines (64 loc) · 3.46 KB

README.md

File metadata and controls

94 lines (64 loc) · 3.46 KB

KSeF Python SDK – dokumentacja

Dokumentacja opisuje publiczne API biblioteki ksef-client-python (import: ksef_client) oraz scenariusze (workflow) wspierające typowe procesy: uwierzytelnianie, generowanie XML FA(3), sesje wysyłkowe (online/batch) i eksport faktur.

Opis kontraktu API (OpenAPI) oraz dokumenty procesowe i ograniczenia systemu znajdują się w ksef-docs/.

Kompatybilność SDK: KSeF API v2.6.0.

Publiczny kontrakt SDK używa typowanych modeli ksef_client.models. Payloady requestów są typed-only, a wiele metod klientów zwraca modele odpowiedzi zamiast surowych dict. Jeśli migrujesz starszą integrację, zobacz migration-typed-model-api.md.

Wymagania

  • Python >= 3.10
  • Dostęp do środowiska KSeF (TEST/DEMO/PROD) i odpowiednie dane uwierzytelniające

Instalacja (lokalnie)

W katalogu projektu:

pip install -e .

Opcjonalne dodatki (extras):

pip install -e .[cli,xml,fa3,qr]
  • cli – komenda ksef i zależności CLI (typer, rich, keyring)
  • xml – podpis XAdES (lxml, xmlsec)
  • fa3 – walidacja XSD dla XML FA(3) (lxml)
  • qr – generowanie PNG z kodami QR (qrcode, pillow)

Jeżeli pracujesz tylko z API Pythona, pip install -e . wystarcza. Do pracy z CLI użyj pip install -e .[cli] albo pełnego zestawu extras.

Struktura SDK

Biblioteka udostępnia trzy poziomy użycia:

  1. Klient API (cienka warstwa) – KsefClient / AsyncKsefClient oraz podklienci (.auth, .sessions, …). Metody odpowiadają endpointom KSeF, przyjmują typowane modele requestów z ksef_client.models i w wielu przypadkach zwracają typowane modele odpowiedzi. Wyjątki dotyczą endpointów binarnych lub pomocniczych.
  2. Scenariusze (workflow) – klasy z ksef_client.services, m.in. AuthCoordinator, OnlineSessionWorkflow, BatchSessionWorkflow, ExportWorkflow. Warstwa workflow łączy kilka wywołań API z operacjami lokalnymi (szyfrowanie, ZIP) i porządkuje typowe przepływy.
  3. Dokumenty FA(3) – moduł ksef_client.documents.fa3 buduje faktury, serializuje XML i opcjonalnie waliduje XSD przed wysyłką online/batch.

Nawigacja

Referencja API (endpointy):

Workflows:

Dokumenty FA(3):

CLI:

Usługi / utils (zaawansowane, ale publiczne):

Przykłady (skrypty):