ksef2 1.0.0 to pierwsze wydanie, które traktuje udokumentowane, aplikacyjne
ścieżki importu jako kontrakt kompatybilności dla linii 1.x.
SDK obecnie celuje w wersję OpenAPI KSeF 2.8.1.
Nieoficjalne SDK. ksef2 jest utrzymywane społecznościowo. Nie jest publikowane, zatwierdzane ani wspierane przez Ministerstwo Finansów. Oficjalna dokumentacja KSeF pozostaje źródłem prawdy dla zachowania API.
Oficjalna dokumentacja API KSeF v2 — Używaj dokumentacji Ministerstwa Finansów jako źródła prawdy dla zachowania API.
Stabilne w 1.0
Stabilnym kontraktem jest udokumentowana publiczna powierzchnia SDK, a nie każdy moduł, który da się zaimportować z repozytorium.
| Powierzchnia | Kontrakt 1.0 |
|---|---|
ksef2 | Klienci root, środowiska, konfiguracja transportu, FormSchema, __version__ i publiczne wyjątki. |
ksef2.clients | Konkretne klasy klientów sync i async do adnotacji typów i zaawansowanego konstruowania. |
ksef2.models | Publiczne modele SDK dla requestów, response'ów, filtrów, paginacji, tokenów, uprawnień, sesji, batchy i faktur. |
| Wysokopoziomowe moduły klientów | client.authentication, client.encryption, client.peppol, client.testdata oraz moduły uwierzytelnione: auth.invoices, auth.tokens, auth.permissions, auth.certificates, auth.collective_identifiers, auth.limits. |
| Przepływy identyfikatorów zbiorczych | auth.collective_identifiers generuje identyfikator zbiorczy dla wskazanych faktur, odpytuje identyfikatory strona po stronie, rozwiązuje identyfikatory dołączone do jednej liczby KSeF oraz wymienia faktury w wybranych identyfikatorach zbiorczych. |
| Pomocniki sesji | Przepływy sesji online i batch do wysyłki, pollingu, UPO i wznawialnych referencji KSeF. |
ksef2.xades | Ładowanie certyfikatów, generowanie certyfikatów TEST, lokalne pomocniki podpisu XAdES i LocalSigner. |
ksef2.profiles | Pomocniki konfiguracji profili zgodnych z lokalnymi profilami ksef2-cli. |
ksef2.fa3 | Publiczny builder faktur FA(3), drafty buildera i publiczne modele domenowe FA(3) używane przez przepływy buildera. |
ksef2.renderers | Opcjonalne lokalne pomocniki renderowania faktur XSLT/PDF po instalacji dodatku pdf. |
Dokładną granicę kompatybilności opisuje strona interfejsu publicznego.
Publiczne, ale niższopoziomowe
ksef2.raw i ksef2.raw.mappers są publicznymi API dla zaawansowanych
integracji. Ich ścieżki importu należą do kontraktu 1.x, ale kształty modeli
schema-native podążają za sprawdzoną wersją OpenAPI Ministerstwa Finansów.
Używaj ksef2.raw, gdy potrzebujesz kontroli na poziomie endpointów,
dokładnych payloadów w kształcie OpenAPI, własnej obsługi szyfrowania albo
debugowania protokołu. Większość kodu aplikacyjnego powinna korzystać z
modułów wysokiego poziomu.
Poza kontraktem 1.x
Nie buduj kodu aplikacji na tych ścieżkach:
- każdej ścieżki modułu z komponentem poprzedzonym podkreśleniem, na przykład
ksef2._corelubksef2._clients.base(ścieżka modułu bez podkreślenia jest publiczna, a każda ze znakiem podkreślenia jest prywatna); - repozytoryjnych
scripts/*; - internali wygenerowanych schem poza
ksef2.raw.speciksef2.raw.supp.
Dawne ścieżki ksef2.core, ksef2.domain, ksef2.infra i ksef2.services,
wraz z podmodułami, nadal działają jako wycofywane aliasy. Emitują
DeprecationWarning raz dla danej rodziny pakietów, wskazując zamienniki. Dawne nazwy metod także
działają przez całe 1.x. Usunięcie jest możliwe nie wcześniej niż w 2.0.0.
Zmiana nazw modułów prywatnych nie usuwa dawnych importów w 1.0.
Poradnik migracji pokazuje importy, wysyłkę/oczekiwanie/UPO oraz wyszukiwanie. Python zwykle ukrywa ostrzeżenia, więc włącz je w testach.
Powiązane strony
- Kontrakt publicznego API: Przejrzyj stabilne importy i granice internal dla kodu aplikacyjnego.
- API niskiego poziomu: Zrozum wspieraną powierzchnię endpointów raw i kontrakt modeli zależnych od schemy.
- Operacje: Przejrzyj retry, timeouty, rate limity, granice logowania i wznawialne referencje.