Dokumentacja

1. Certyfikat klienta (mTLS)

API nie używa haseł, tokenów ani kluczy API — uwierzytelnienie odbywa się na poziomie połączenia TLS certyfikatem klienta wystawionym przez KSeF Partner CA. Klucz prywatny generujesz u siebie i nigdy go nam nie wysyłasz.

Najprościej skorzystać z generatora w przeglądarce. Jeśli wolisz OpenSSL:

openssl genrsa -out partner.key 2048
chmod 600 partner.key
openssl req -new -key partner.key -out partner.csr \
    -subj "/CN=Twoja Firma API/O=Twoja Firma Sp. z o.o./C=PL"
cp partner.csr KSC-XXXX-XXXX.txt

2. Wysyłka CSR na csr@ksef.click

• Wyślij wiadomość z adresu e-mail podanego przy rejestracji konta.
• W temacie wpisz kod konta (np. KSC-7QX4-M2RD) — znajdziesz go w panelu Moje konto.
• Dołącz CSR jako załącznik .txt (zawartość pliku zaczyna się od -----BEGIN CERTIFICATE REQUEST-----).
• Akceptujemy klucze RSA od 2048 bitów oraz EC P-256 i P-384. Każdy CSR musi mieć nowy klucz.

3. Co dostaniesz w odpowiedzi

• partner.crt — Twój certyfikat klienta (ważny 365 dni, extendedKeyUsage = clientAuth),
• partner-ca.crt — certyfikat Partner CA, który wystawił Twój certyfikat (przydaje się do zbudowania pełnego łańcucha, np. w pliku .p12),
• pakiet integracyjny: instrukcja, kontrakt OpenAPI, kolekcja Postmana, klient C# i PHP, test dymny,
• identyfikator partnera (partnerId) i odcisk SHA-256 certyfikatu.

4. Pierwsze wywołania

# Kim jestem: certyfikat, limity, liczba firm, czy produkcja jest włączona
curl --cert partner.crt --key partner.key https://api.ksef.click/api/v1/me

# Stan KSeF w poszczególnych środowiskach
curl --cert partner.crt --key partner.key https://api.ksef.click/api/v1/status

# Firmy, do których masz dostęp (companyId do kolejnych wywołań)
curl --cert partner.crt --key partner.key https://api.ksef.click/api/v1/companies

Serwer api.ksef.click ma publiczny certyfikat Let's Encrypt — nie podawaj --cacert partner-ca.crt przy wywołaniach (ten plik służy do weryfikacji Twojego certyfikatu klienta, nie serwera). Łącz się zawsze po nazwie hosta i pilnuj poprawnego czasu systemowego.

5. Model dostępu

Certyfikat identyfikuje partnera, a partner obsługuje wiele firm — dlatego companyId jest wymagany w każdej operacji zapisu. Uprawnienia (can_send, can_sync, can_read) są nadawane osobno dla każdej firmy. Każda firma należy do jednego środowiska KSeF: test, demo albo production.

6. Limity

7. Kontakt

Pytania o integrację i włączenie produkcji: kontakt@ksef.click. Adres csr@ksef.click obsługuje automat — wysyłaj tam wyłącznie pliki CSR.