KSeF API 2.0 Guide

1. Environments

KSeF provides three distinct environments. Always use TEST or DEMO for development.

2. Authentication

Each API session requires token authentication. The full flow uses RSA-OAEP encryption of the token with the KSeF public key.

Full flow (API token)

1. GET  /security/public-key-certificates     → RSA keys
2. POST /auth/challenge                        → challenge + timestampMs
3. RSA-OAEP(token|timestampMs)                 → encrypt with "KsefTokenEncryption" key
4. POST /auth/ksef-token                       → challenge + encryptedToken
   → authenticationToken + referenceNumber (HTTP 202)
5. GET  /auth/{referenceNumber}                → poll until code=200
6. POST /auth/token/redeem                     → exchange → accessToken

Required headers for authenticated calls

Authorization: Bearer {accessToken}
Accept: application/json
Content-Type: application/json

Public keys

GET /security/public-key-certificates returns 2 certificates:

No fingerprint field in the response (contrary to the documentation).

3. Online Session (interactive)

For sending invoices without attachments, one at a time.

1. POST /sessions/online                           → open session
2. POST /sessions/online/{ref}/invoices             → send invoice
3. GET  /sessions/{ref}/invoices/{invoiceRef}        → check status
4. POST /sessions/online/{ref}/close                → close session

Opening a session

{
  "formCode": {"systemCode": "FA (3)", "schemaVersion": "1-0E", "value": "FA"},
  "encryption": {
    "encryptedSymmetricKey": "RSA-OAEP(aes_key, cert_SymmetricKeyEncryption)",
    "initializationVector": "base64(iv_16_bytes)"
  }
}

The client generates the AES-256 key and IV, encrypts the key with RSA, and sends both.

Sending an invoice

{
  "invoiceHash": "base64(SHA256(xml_raw))",
  "invoiceSize": 2048,
  "encryptedInvoiceHash": "base64(SHA256(xml_encrypted))",
  "encryptedInvoiceSize": 2064,
  "encryptedInvoiceContent": "base64(AES-256-CBC(xml_raw))"
}

AES-256-CBC encryption with PKCS#7 padding. Same key/IV as the session.

4. Batch Session (wsadowa)

For sending invoices with or without attachments, in bulk (ZIP).

1. Create ZIP containing XML invoices (faktura_1.xml, faktura_2.xml, ...)
2. Encrypt ZIP with AES-256-CBC + PKCS#7 (NO IV prepend)
3. POST /sessions/batch           → open session, receive upload URL
4. PUT  {uploadUrl}               → upload encrypted ZIP (raw bytes)
5. POST /sessions/batch/{ref}/close  → close and start processing
6. GET  /sessions/{ref}           → poll session status
7. GET  /sessions/{ref}/invoices  → accepted invoices
8. GET  /sessions/{ref}/invoices/failed → rejected invoices

Opening a batch session

{
  "formCode": {"systemCode": "FA (3)", "schemaVersion": "1-0E", "value": "FA"},
  "batchFile": {
    "fileSize": 1078,
    "fileHash": "base64(SHA256(zip_raw))",
    "fileParts": [{
      "ordinalNumber": 1,
      "fileSize": 1088,
      "fileHash": "base64(SHA256(zip_encrypted))"
    }]
  },
  "encryption": {
    "encryptedSymmetricKey": "...",
    "initializationVector": "..."
  }
}

Per-invoice results

After closing the batch session, each invoice is processed independently. Check results via two separate endpoints.

GET /sessions/{ref}/invoices          → accepted invoices (with ksefNumber)
GET /sessions/{ref}/invoices/failed   → rejected invoices (with processingCode + error)

Processing is parallel: accepted and rejected invoices may appear in a different order than in the ZIP.

5. Processing Codes

API responses use processing codes (processingCode) to indicate request status. The same code may have slightly different meanings depending on the endpoint (auth, session, invoice, export).

Progression (100-299)

Errors (400-550)

Source : Issue #526, OpenAPI spec, api-changelog.md

6. Limits

Verifiable via GET /limits/context.

7. Attachments (Zalacznik)

Prerequisites

• 1.Activation : POST /testdata/attachment with {"nip": "..."} (TEST env). In PROD: declaration via e-Urząd Skarbowy.
• 2.Batch session required : online mode rejects attachments (code 415).

Verification

GET /permissions/attachments/status (authenticated)

{"isAttachmentAllowed": true}
// or with revocation date:
{"isAttachmentAllowed": true, "revokedDate": "2026-12-31T23:59:59+00:00"}

XML Structure

'<Zalacznik>' is a direct child of '<Faktura>' (not '<Fa>'), with structured content:

<Faktura xmlns="http://crd.gov.pl/wzor/2025/06/25/13775/">
  <Naglowek>...</Naglowek>
  <Podmiot1>...</Podmiot1>
  <Podmiot2>...</Podmiot2>
  <Fa>...</Fa>
  <Zalacznik>
    <BlokDanych>
      <MetaDane>
        <ZKlucz>Key</ZKlucz>
        <ZWartosc>Value</ZWartosc>
      </MetaDane>
      <Tabela>
        <Opis>Table description</Opis>
        <TNaglowek>
          <Kol Typ="txt"><NKom>Column 1</NKom></Kol>
          <Kol Typ="int"><NKom>Column 2</NKom></Kol>
        </TNaglowek>
        <Wiersz>
          <WKom>Value 1</WKom>
          <WKom>42</WKom>
        </Wiersz>
      </Tabela>
    </BlokDanych>
  </Zalacznik>
</Faktura>

Column types: txt, int, dec, date.

Attachment error codes

8. Testdata endpoints (TEST env)

No authentication required. These endpoints allow configuring the test environment.

9. Information endpoints

Authenticated endpoints to check the status of your account and invoices.

10. Known Issues

Points of attention when integrating with the KSeF API, based on our real-world tests:

Useful Links

• 🔗 KSeF Documentation (GitHub CIRFMF)
• 🔗 KSeF OpenAPI Specification
• 🔗 Official KSeF Portal (podatki.gov.pl)