Uwierzytelnij się

Uwierzytelnianie zamienia głównego Client w klienta uwierzytelnionego. Klient główny wybiera środowisko KSeF, a metoda uwierzytelnienia wybiera kontekst, w którym działa aplikacja.

Zmienne środowiskowe

Te nazwy są używane w przykładach i przez profile ksef2-cli:

export KSEF2_ENV=test
export KSEF2_NIP=5261040828
export KSEF2_TOKEN=podmien-na-prawdziwy-token-ksef

SDK czyta KSEF2_PROFILE i KSEF2_CONFIG, gdy używasz client.authentication.with_profile(). Przy bezpośrednim uwierzytelnianiu tokenem albo certyfikatem trzymaj granicę konfiguracji jawną w aplikacji:

import os

from ksef2 import Environment

environment_name = os.environ.get("KSEF2_ENV", "test").upper()
environment = Environment[environment_name]

Poniższe przykłady metod zakładają, że client jest otwartym klientem bazowym dla wybranego środowiska. W skryptach preferuj context manager, na przykład with Client(Environment.TEST) as client:.

Wybierz metodę

Z tokenem KSeF

Użyj tokenu KSeF, gdy aplikacja ma już ważny token dla danego kontekstu. Token działa w TEST, DEMO i PRODUCTION.

import os

auth = client.authentication.with_token(
    ksef_token=os.environ["KSEF2_TOKEN"],
    nip=os.environ["KSEF2_NIP"],
    context_type="nip",
)

Certyfikat TEST

Certyfikat generowany przez SDK jest przeznaczony do lokalnego developmentu i działa tylko z Environment.TEST.

import os

auth = client.authentication.with_test_certificate(
    nip=os.environ["KSEF2_NIP"],
)

Z PEM XAdES

Użyj plików PEM, gdy certyfikat i klucz prywatny są zapisane oddzielnie.

import os

from ksef2.xades import load_certificate_from_pem, load_private_key_from_pem

password = os.environ.get("KSEF2_KEY_PASSWORD")
cert = load_certificate_from_pem("company.pem")
private_key = load_private_key_from_pem(
    "company.key",
    password=password.encode() if password else None,
)

auth = client.authentication.with_xades(
    nip=os.environ["KSEF2_NIP"],
    cert=cert,
    private_key=private_key,
)

Z PKCS#12

Użyj archiwum PKCS#12/PFX, gdy certyfikat i klucz prywatny są w jednym pliku.

import os

from ksef2.xades import load_certificate_and_key_from_p12

password = os.environ.get("KSEF2_P12_PASSWORD")
cert, private_key = load_certificate_and_key_from_p12(
    "company.p12",
    password=password.encode() if password else None,
)

auth = client.authentication.with_xades(
    nip=os.environ["KSEF2_NIP"],
    cert=cert,
    private_key=private_key,
)

Profile kompatybilne z CLI

ksef2-cli i SDK używają tego samego lokalnego pliku profili. Profil przechowuje niesekretne ustawienia: środowisko, NIP, metodę uwierzytelnienia, ścieżki certyfikatów, ustawienia pollingu i nazwę zmiennej środowiskowej z sekretem. Nie zapisuje wartości tokenów ani haseł certyfikatów.

ksef2 profile create test-company \
  --env test \
  --nip 5261040828 \
  --test-cert

ksef2 profile create prod-token \
  --env production \
  --nip "$KSEF2_NIP" \
  --token-env KSEF2_TOKEN

Wybierz aktywny profil dla kolejnych komend CLI:

ksef2 profile use prod-token
ksef2 --json profile current

Albo wybierz profil dla jednej powłoki lub jednej komendy:

export KSEF2_PROFILE=prod-token
ksef2 --json auth login

ksef2 --profile test-company --json auth login

Kolejność wyboru profilu jest taka sama w CLI i SDK:

1. Jawna nazwa profilu.
2. KSEF2_PROFILE.
3. active_profile w lokalnym pliku konfiguracji.

Użyj KSEF2_CONFIG albo config_path="...", gdy plik profili nie znajduje się w domyślnej lokalizacji ~/.config/ksef2/config.toml. Istniejące pliki ~/.config/ksef2-cli/config.toml nadal są odczytywane jako zgodność wsteczna.

Użyj istniejącego profilu w kodzie SDK:

from ksef2 import Client, Environment

with Client(Environment.PRODUCTION) as client:
    auth = client.authentication.with_profile()

    # Aby zamiast tego jawnie wybrać profil:
    # auth = client.authentication.with_profile("prod-token")

Środowisko klienta bazowego musi zgadzać się ze środowiskiem wybranego profilu.

Utwórz albo zaktualizuj ten sam plik profili z kodu SDK:

from ksef2 import Environment
from ksef2.profiles import Profile, ProfileStore, TokenProfileAuth

store = ProfileStore.default()
store.save(
    "prod-token",
    Profile(
        environment=Environment.PRODUCTION,
        nip="5261040828",
        auth=TokenProfileAuth(token_env="KSEF2_TOKEN"),
    ),
    activate=True,
    overwrite=True,
)

Klient asynchroniczny używa tego samego pliku profili i tej samej kolejności wyboru:

from ksef2 import AsyncClient, Environment

async with AsyncClient(Environment.PRODUCTION) as client:
    auth = await client.authentication.with_profile("prod-token")

Zobacz też:

• Użyj profili: Twórz profile przez ksef2-cli, uwierzytelniaj się przez with_profile() i zarządzaj profilami przez ProfileStore.
• Uwierzytelnianie w CLI: Użyj tych samych przepływów tokenu, certyfikatu TEST, PEM XAdES, PKCS#12 i profili z poziomu ksef2-cli.

Zalecany przepływ

1. Umieść sekrety w zmiennych środowiskowych.

   Użyj KSEF2_TOKEN, KSEF2_KEY_PASSWORD albo KSEF2_P12_PASSWORD.

2. Trzymaj niesekretne ustawienia w jednym miejscu.

   Dla w pełni własnych konfiguracji użyj konfiguracji aplikacji. Jeśli to samo środowisko obsługujesz też z terminala, skorzystaj z profili ksef2-cli.

3. Utwórz klienta bazowego dla środowiska.

   Użyj Client(Environment.TEST), Client(Environment.DEMO) albo Client(Environment.PRODUCTION).

4. Uwierzytelnij się raz i przekaż klienta do przepływów.

   Klient uwierzytelniony przechowuje tokeny dostępu i udostępnia moduły przepływów.

Błędy

Błędy sklasyfikowane przez SDK łap przez KSeFException. Błędy transportu HTTP łap osobno.

import httpx

from ksef2 import Client, Environment, KSeFException

try:
    with Client(Environment.TEST) as client:
        auth = client.authentication.with_test_certificate(nip="5261040828")
except KSeFException as exc:
    print(exc)
except httpx.HTTPError as exc:
    print(f"Transport failed: {exc}")

Następne przepływy

• Wysyłanie faktur: Otwórz sesję online albo batch po uwierzytelnieniu.
• Wyszukiwanie faktur: Pobierz metadane faktur z filtrami i paginacją.
• Pobieranie faktur: Pobierz przetworzone faktury albo szyfrowane paczki eksportu.