Fakturnia Developers Quickstart API reference Polski

KSeF connection

Before you send your first invoice to KSeF, the account needs a configured connection: the certificate Fakturnia uses to authenticate with KSeF on behalf of your company. This page covers managing that connection through the API. Sending invoices is covered in Sending to KSeF.

Required scopes: ksef:read (read status), ksef:configure (write and delete), ksef:test (connection test).

Connection status

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
  }
}

Secrets (certificate and key contents) are never returned. isAuthorized: false with a populated lastError means the last KSeF authentication attempt failed.

Configuring the connection

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": "key-password",
    "environment": "prod"
  }'
Field Meaning
certificateContent the KSeF certificate in PEM format
privateKeyContent the private key in PEM format
privateKeyPassword the private key password
environment prod, test or demo (defaults to match the API environment)

Calling this again overwrites the previous configuration. You issue the certificate in the KSeF application for your company's NIP; Fakturnia uses it only to talk to the KSeF gateway.

On the sandbox environment the connection points at the KSeF test gateway, so you can rehearse the whole flow safely with no legal effect.

Testing the connection

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

The test performs a full KSeF authentication and refreshes isAuthorized, permissions and lastError. Call it after every configuration change, before you start sending invoices.

Deleting the connection

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

After deletion, sending to KSeF stops working until you configure the connection again. Previously issued documents and their KSeF numbers remain unchanged.