Zarządzaj certyfikatami · ksef2 SDK dokumentacja

Użyj auth.certificates do rejestracji, wyszukiwania, pobierania i cofania certyfikatów KSeF. SDK wysyła CSR i żądania cyklu życia. Narzędzia certyfikatowe nadal odpowiadają za generowanie i przechowywanie kluczy prywatnych.

Sprawdź limity i dane rejestracji

limits = auth.certificates.get_limits()

# CertificateLimitsResponse
# {
#   "can_request": true,
#   "enrollment_limit": 10,
#   "enrollment_remaining": 9,
#   "certificate_limit": 10,
#   "certificate_remaining": 8
# }

subject = auth.certificates.get_enrollment_data()

# CertificateEnrollmentData
# {
#   "common_name": "Example subject",
#   "iso_country_code": "PL",
#   "organization_identifier": "VATPL-5261040828"
# }

python

Użyj danych rejestracji podczas budowania CSR w narzędziach certyfikatowych.

Zarejestruj certyfikat

Wyślij CSR i zapisz zwróconą referencję rejestracji.

csr = """-----BEGIN CERTIFICATE REQUEST-----
...
-----END CERTIFICATE REQUEST-----"""

enrollment = auth.certificates.enroll(
    certificate_name="billing-service",
    certificate_type="authentication",
    csr=csr,
)

# CertificateEnrollment: udostępnia każde pole odpowiedzi rejestracji
# {
#   "reference_number": "20260625-CERT-...",
#   "timestamp": "2026-06-25T10:00:00Z"
# }

python

enroll() zwraca uchwyt CertificateEnrollment. Poczekaj, aż KSeF wyda certyfikat:

status = enrollment.wait(timeout=60.0, poll_interval=2.0)

python

wait() zgłasza KSeFCertificateEnrollmentFailedError, gdy KSeF odrzuci albo anuluje wniosek, oraz KSeFCertificateEnrollmentTimeoutError, gdy nie zakończy się na czas. Aby sprawdzić status jednorazowo bez czekania, wywołaj enrollment.get_status() albo auth.certificates.get_enrollment_status(reference_number=...), gdy zapisałeś tylko numer referencyjny:

status = auth.certificates.get_enrollment_status(
    reference_number=enrollment.reference_number,
)

# CertificateEnrollmentStatusResponse
# {
#   "status_code": 200,
#   "status_description": "Completed",
#   "certificate_serial_number": "0123456789ABCDEF"
# }

python

Wyszukaj, pobierz i cofnij

Wyszukaj

for certificate in auth.certificates.list(status="active"):
    print(certificate.serial_number, certificate.name, certificate.valid_to)

python

Pobierz

result = auth.certificates.retrieve(
    certificate_serial_numbers=["0123456789ABCDEF"],
)

for certificate in result.certificates:
    print(certificate.serial_number, certificate.certificate_type)

python

Cofnij

auth.certificates.revoke(
    certificate_serial_number="0123456789ABCDEF",
    reason="key_compromise",
)

python

Zalecany przepływ

Sprawdź limity certyfikatów i rejestracji.
Pobierz dane podmiotu do rejestracji.
Wygeneruj klucz prywatny i CSR poza SDK.
Wyślij rejestrację i zapisz numer referencyjny.
Poczekaj na wydanie, pobierz certyfikat i zapisz go z kluczem prywatnym.
Cofnij certyfikaty, które nie są już ważne albo których klucz prywatny mógł zostać naruszony.

Następne przepływy

Użyj pomocników XAdES: Ładuj materiał certyfikatu i uwierzytelniaj się przez XAdES.
Certyfikaty: Zrozum role certyfikatów w uwierzytelnianiu, podpisie i rejestracji.
Uwierzytelnianie: Użyj wydanego materiału certyfikatu do uwierzytelniania SDK.