README.md

KSeF Python SDK – dokumentacja

Dokumentacja opisuje publiczne API biblioteki ksef-client-python (import: ksef_client) oraz scenariusze (workflow) wspierające typowe procesy: uwierzytelnianie, 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.2.1.

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 .[xml,qr]

• xml – podpis XAdES (lxml, xmlsec)
• qr – generowanie PNG z kodami QR (qrcode, pillow)

Struktura SDK

Biblioteka udostępnia dwa poziomy użycia:

1. Klient API (cienka warstwa) – KsefClient / AsyncKsefClient oraz podklienci (.auth, .sessions, …). Metody odpowiadają endpointom KSeF i zwracają głównie surowy JSON (dict).
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.

Nawigacja

• Start
• Konfiguracja klienta
• Błędy i retry

Referencja API (endpointy):

• KsefClient i AsyncKsefClient
• client.auth
• client.sessions
• client.invoices
• client.lighthouse
• client.permissions
• client.certificates
• client.tokens
• client.limits
• client.rate_limits
• client.security
• client.testdata
• client.peppol

Workflows:

• Uwierzytelnianie
• Sesja interaktywna (online)
• Sesja wsadowa (batch)
• Eksport (pobieranie paczek)

CLI:

• Specyfikacja ksef CLI

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

• Usługi (ksef_client.services)
• Utils (ksef_client.utils)

Przykłady (skrypty):

• Przykłady