Referencja operacji

Ta strona zapisuje zachowania operacyjne ważne dla integracji produkcyjnych. Nie jest walkthrough wysyłki ani uwierzytelniania.

TransportConfig

TransportConfig jest używany tylko wtedy, gdy SDK tworzy wewnętrznego klienta httpx. Jeśli przekażesz http_client, ten klient posiada timeouty HTTP, pool, TLS, proxy, trust_env, HTTP/2, custom transport i event hooki.

TransportConfig(
    timeouts=TimeoutConfig(),
    pool=ConnectionPoolConfig(),
    retry=RetryConfig(),
    tls=TlsConfig(),
    proxy_url=None,
    trust_env=True,
    http2=True,
    auto_refresh_tokens=True,
    error_format="problem-details",
)

auto_refresh_tokens i error_format nie konfigurują httpx, więc działają także wtedy, gdy przekażesz własny http_client.

TimeoutConfig

TimeoutConfig kontroluje pojedynczy request HTTP. Nie kontroluje tego, jak długo SDK odpytuje stan workflow KSeF.

ConnectionPoolConfig

TlsConfig

RetryConfig

RetryConfig kontroluje middleware retry SDK. Obejmuje błędy transportu i ponawialne odpowiedzi HTTP dla ponawialnych typów requestów.

Opóźnienie retry jest wykładnicze:

min(initial_delay * backoff_multiplier ** (attempt - 1), max_delay)

max_delay ogranicza tylko eksponencjalne backoffy. Nagłówek Retry-After (sekundy albo data HTTP) jest stosowany dokładnie, gdy mieści się w max_retry_after. Gdy go przekracza, SDK nie śpi i nie ponawia: poddaje się natychmiast i rzuca KSeFRateLimitError z prawdziwą wartością z nagłówka, żeby aplikacja mogła przełożyć pracę. Sufit chroni proces przed wiecznym oczekiwaniem na Retry-After rzędu wielu godzin.

Sufit ogranicza jedno zaśnięcie, nie cały request. Jeśli KSeF powtórzy ten sam Retry-After przy każdej próbie, pojedynczy request czeka maksymalnie (max_attempts - 1) * max_retry_after, zanim się podda. Przy domyślnych wartościach to 240 sekund, bo SDK śpi 120 sekund dwa razy. Zmniejsz max_attempts albo max_retry_after, gdy handler requestu nie może tyle czekać.

Ponawialne requesty

SDK ponawia tylko kształty requestów, które są wystarczająco bezpieczne do powtórzenia na poziomie transportu.

Ponawialne grupy POST:

Wysyłka faktury, nadawanie uprawnień, enrollment certyfikatu, generowanie tokenu, otwieranie sesji online i otwieranie sesji batch nie są ponawiane przez middleware retry SDK. Zapisz zwrócone referencje i wznawiaj przez status zamiast tworzyć te operacje ponownie w ciemno.

Redeem tokenu uwierzytelnienia także nigdy nie jest ponawiany, ponieważ KSeF zwraca parę access/refresh tylko raz. Utrata odpowiedzi redeem rzuca KSeFAuthTokenRedemptionError z outcome_ambiguous=True; nie powtarzaj tej operacji automatycznie.

Odświeżanie access tokenu

Klienci uwierzytelnieni odświeżają access token samodzielnie, używając refresh tokenu z uwierzytelnienia albo z AuthenticationResumeState, z którego zostali wznowieni.

Jedno odświeżenie to nie pełne ponowne uwierzytelnienie: SDK powtarza oryginalny request raz z odświeżonym tokenem. Jeżeli ten powtórzony request dostanie znowu 401, KSeFAuthError trafia do aplikacji i to ona decyduje, czy uwierzytelnić się ponownie, czy zgłosić błąd.

auth.auth_tokens, auth.access_token i auth.resume_state() zawsze zwracają bieżące tokeny, więc po długo trwającej pracy zapisz resume_state() ponownie.

Gdy refresh token wygasł albo KSeF go odrzucił, request rzuca KSeFAuthenticationExpiredError, podklasę KSeFAuthError. Jedynym wyjściem jest ponowne uwierzytelnienie. Jeśli refresh token już wygasł, ale access token ma jeszcze ważność, requesty nadal używają access tokenu, dopóki KSeF go nie odrzuci. Błędy transportu i inne błędy wywołania odświeżenia są propagowane bez zmian.

Odświeżanie nigdy nie dotyczy jednorazowego redeem uwierzytelnienia ani transferów presigned do zewnętrznego storage (upload części batch, pobieranie eksportów). Używają osobnych ścieżek i nie niosą tokenu bearer.

Aby zarządzać tokenami samodzielnie, wyłącz to zachowanie. Wygasłe tokeny ujawnią się wtedy jako KSeFAuthError, a client.authentication.refresh() pozostaje dostępne.

client = Client(Environment.PRODUCTION, transport_config=TransportConfig(auto_refresh_tokens=False))

Timeouty pollingu workflow

Helpery pollingowe używają argumentów timeout i poll_interval. Są to deadline'y workflow, nie timeouty requestu HTTP. Gdy zostanie rzucony timeout pollingu, zdalny workflow KSeF może nadal zakończyć się później.

Po timeoutcie wznów polling zapisanymi identyfikatorami. Nie traktuj lokalnego deadline'u jako dowodu, że zdalna operacja się nie udała.

Rate limit

Odpowiedzi KSeF 429 są klasyfikowane jako KSeFRateLimitError. Wyjątek udostępnia:

Dla 429 middleware retry stosuje dokładnie wartość Retry-After, gdy mieści się ona w max_retry_after, śpi i ponawia do max_attempts razy. Gdy nagłówek przekracza sufit, middleware poddaje się natychmiast: bez spania, bez ponawiania, a request kończy się KSeFRateLimitError z prawdziwą wartością nagłówka w retry_after. Sufit ogranicza każde zaśnięcie z osobna, więc powtarzający się nagłówek może trzymać request przez (max_attempts - 1) * max_retry_after, czyli domyślnie 240 sekund.

Co nadal należy do aplikacji: KSeFRateLimitError oznacza, że SDK już się poddał, więc zaplanuj pracę na później zamiast ponawiać na oślep. Używaj retry_after do planowania pracy w tle. W request handlerach lepiej zwrócić albo zakolejkować pracę do ponowienia niż usypiać request.

Granice sekretów i logowania

Nie loguj:

• access tokenów;
• refresh tokenów;
• wartości tokenów KSeF;
• kluczy prywatnych;
• haseł PEM albo PKCS#12;
• surowego XML faktury, chyba że polityka retencji na to pozwala;
• zserializowanego stanu sesji online albo batch.

Przydatne pola logów produkcyjnych:

Wznawialny stan workflow

Większość workflow KSeF zaczyna się referencją i kończy przez polling albo późniejsze pobranie. Zapisz referencję przed czekaniem.

Powiązana referencja

• Cykl życia klienta: Sprawdź konstruktory, własność gałęzi, zamykanie i błędy lifecycle.
• Obsługa błędów: Sprawdź klasy wyjątków SDK, błędy API KSeF i timeouty.
• Konfiguracja klienta: Zastosuj te ustawienia w przykładach setupu sync i async.
• Status i UPO: Zrozum statusy, dokumenty UPO, polling i lokalne deadline'y.