Połączenie KSeF

Zanim wyślesz pierwszą fakturę do KSeF, konto musi mieć skonfigurowane połączenie: certyfikat, którym Fakturnia uwierzytelnia się w KSeF w imieniu Twojej firmy. Ta strona opisuje zarządzanie tym połączeniem przez API. Samą wysyłkę faktur opisuje Wysyłka do KSeF.

Wymagane zakresy uprawnień: ksef:read (odczyt stanu), ksef:configure (zapis i usunięcie), ksef:test (test połączenia).

Stan połączenia#

curl -s https://prod.api.fakturnia.pl/external/v1/ksef/connection \
  -H "Authorization: Bearer $TOKEN"

{
  "success": true,
  "data": {
    "isAuthorized": true,
    "hasConnectionConfig": true,
    "connectionType": "CERTIFICATE",
    "environment": "prod",
    "nip": "5252248481",
    "permissions": ["InvoiceWrite", "InvoiceRead"],
    "certificateExpiresAt": "2027-03-01T00:00:00.000Z",
    "lastCheckAt": "2026-07-01T08:12:00.000Z",
    "lastError": null,
    "lastErrorAt": null
  }
}

Sekrety (zawartość certyfikatu i klucza) nie są nigdy zwracane. isAuthorized: false z ustawionym lastError oznacza, że ostatnia próba uwierzytelnienia w KSeF się nie powiodła.

Konfiguracja połączenia#

curl -s -X POST https://prod.api.fakturnia.pl/external/v1/ksef/connection \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "certificateContent": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
    "privateKeyContent": "-----BEGIN ENCRYPTED PRIVATE KEY-----\n...\n-----END ENCRYPTED PRIVATE KEY-----",
    "privateKeyPassword": "haslo-do-klucza",
    "environment": "prod"
  }'

Ponowne wywołanie nadpisuje poprzednią konfigurację. Certyfikat wystawiasz w aplikacji KSeF dla NIP swojej firmy; Fakturnia używa go wyłącznie do komunikacji z bramką KSeF.

Na środowisku sandbox połączenie wskazuje bramkę testową KSeF, więc możesz bezpiecznie przećwiczyć cały przepływ bez skutków prawnych.

Test połączenia#

curl -s -X POST https://prod.api.fakturnia.pl/external/v1/ksef/connection/test \
  -H "Authorization: Bearer $TOKEN"

Test wykonuje pełne uwierzytelnienie w KSeF i aktualizuje isAuthorized, permissions oraz lastError. Wywołaj go po każdej zmianie konfiguracji, zanim zaczniesz wysyłać faktury.

Usunięcie połączenia#

curl -s -X DELETE https://prod.api.fakturnia.pl/external/v1/ksef/connection \
  -H "Authorization: Bearer $TOKEN"

Po usunięciu wysyłka do KSeF przestaje działać do czasu ponownej konfiguracji. Wystawione wcześniej dokumenty i ich numery KSeF pozostają bez zmian.