KSeF API specifications

The KSeF API is a REST API hosted on ksef.mf.gov.pl, exposing three usage channels — Sesja Interaktywna (interactive), Sesja Wsadowa (batch), and Common (lookup). Authentication by token hierarchy, JSON format with base64-embedded FA(2) XML.

Environments and endpoints

The ministry operates three distinct environments for KSeF:

• Production (Produkcja). ksef.mf.gov.pl — the legal reference environment. Every invoice that transits there receives a legally valid numer KSeF.
• Pre-production (Przedprodukcyjna). ksef-test.mf.gov.pl — production mirror environment for vendor integration testing. No legal value. The NIPs used must be real.
• Demo (Demonstracja). ksef-demo.mf.gov.pl — sandbox with fictitious NIPs and generated data. Ideal for training and early development.

Authentication — OAuth 2.0 hierarchy

KSeF uses a three-level hierarchy, inspired by OAuth 2.0 but specific to the ministry:

1. AuthorizationToken. Primary token generated once by the taxpayer, in the KSeF portal (human interface) or via XAdES signature by e-IDAS certificate. Valid 24 months, default scope fakturujący on the owning NIP.
2. SessionToken. Obtained by InitToken in exchange for the AuthorizationToken. Valid for a 4-hour sliding window. Used to chain invoice operations without paying the auth cost again.
3. AccessToken (contextual alias). For delegations (e.g. external accountant acting on behalf of the taxpayer). Links the AuthorizationToken to a specific Uprawnienie (right) on a third-party NIP.

POST /api/online/Session/InitToken HTTP/1.1
Host: ksef.mf.gov.pl
Content-Type: application/octet-stream
Content-Encoding: base64

PFNlc3Npb25Ub2tlblJlcXVlc3QgeG1sbnM9Imh0dHA6Ly9rc2VmLm1mLmdvdi5wbC8iPgogIDxJ
ZGVudGlmaWVyVHlwZT5vbmlwPC9JZGVudGlmaWVyVHlwZT4KICA8SWRlbnRpZmllcj41MjYwMjUw
Mjc0PC9JZGVudGlmaWVyPgogIDxBdXRob3JpemF0aW9uVG9rZW4+ZXk...PC9BdXRob3JpemF0
aW9uVG9rZW4+CjwvU2Vzc2lvblRva2VuUmVxdWVzdD4=

HTTP/1.1 201 Created
Content-Type: application/json

{
  "timestamp": "2026-05-19T08:42:11Z",
  "referenceNumber": "20260519-SE-3F4B7A2D9C-DA",
  "sessionToken": {
    "token": "eyJhbGciOiJSUzI1NiIs...",
    "context": {
      "nip": "5260250274",
      "name": "Spółka Sprzedaży Sp. z o.o.",
      "schemaVersion": "1-0E"
    }
  }
}

Interactive flow — Sesja Online

The interactive flow is designed for on-the-fly invoice issuance. This is the preferred mode for ERPs in direct integration and web portals.

1. POST /api/online/Session/InitToken — open the session, retrieve SessionToken
2. POST /api/online/Invoice/Send — submit the FA(2) invoice (base64 in invoiceBody)
3. GET /api/online/Invoice/Status/{ref} — retrieve status and numer KSeF
4. POST /api/online/Session/Terminate — close the session (frees server resources)

POST /api/online/Invoice/Send HTTP/1.1
Host: ksef.mf.gov.pl
SessionToken: eyJhbGciOiJSUzI1NiIs...
Content-Type: application/json

{
  "invoiceHash": {
    "hashSHA": {
      "algorithm": "SHA-256",
      "encoding": "Base64",
      "value": "9c1185a5c5e9fc54612808977ee8f548b2258d31"
    },
    "fileSize": 4892
  },
  "invoicePayload": {
    "type": "plain",
    "invoiceBody": "PD94bWwgdmVyc2lvbj0iMS4wIi..."
  }
}

HTTP/1.1 201 Created
Content-Type: application/json

{
  "elementReferenceNumber": "20260519-SE-3F4B7A2D9C-DA",
  "processingDescription": "Przyjęte",
  "referenceNumber": "20260519-IN-7C8A3D4E5F-AA",
  "timestamp": "2026-05-19T08:42:17Z"
}

The transactional status is in processingDescription. Three main values:

• Przyjęte — invoice accepted by validator, numer KSeF assigned in referenceNumber
• Odrzucone — invoice rejected by validator, error code in statusCode
• W trakcie przetwarzania — asynchronous processing in progress, request to repeat after 1-2 seconds

Batch flow — Sesja Wsadowa

Wsadowa mode allows sending a packet of invoices grouped in a signed ZIP archive, processed asynchronously by KSeF. Preferred mode for ERP vendors handling large volumes.

1. Local preparation. Build a ZIP archive containing each FA(2) invoice as an individual XML file (one file = one invoice). Limit: 50 invoices per archive, maximum size 100 MB.
2. Hash and encryption. SHA-256 hash of each included XML file. AES-256-CBC encryption of the archive with a random symmetric key, itself RSA-encrypted with the KSeF public certificate.
3. POST /api/batch/Session/Init. Submit the manifest (invoice list + hashes + encrypted key). KSeF replies with a deposit URL and a BatchSessionReferenceNumber.
4. PUT on the deposit URL. Upload the encrypted ZIP archive.
5. POST /api/batch/Session/Close. Trigger processing.
6. Polling GET /api/common/Status/{ref}. Track status. Target latency: 5 to 30 minutes depending on volume.

Limits and quotas

Error codes 21xxx

KSeF error codes follow a 21xxx convention. Partial catalogue of common errors:

Common pitfalls

• Wrong base URL. The test environment (ksef-test) and demo (ksef-demo) are often confused. Verify the NIPs used — real ones for test, fictitious ones for demo. A mistake is rejected with code 21200.
• Base64 encoding with line breaks. Some base64 libs insert breaks every 76 chars (RFC 2045 MIME). KSeF only accepts base64 without line breaks (strict RFC 4648).
• Missing Content-Length. On POST with binary body, KSeF requires an exact Content-Length. HTTP libs using Transfer-Encoding: chunked are rejected.
• Binary attachments. KSeF only accepts pure XML. Any attachment (PDF, image) must be referenced outside KSeF and transmitted via another channel. External cloud storage links are accepted in FaWiersz/DodatkoweInfo.
• Polish diacritics. ą, ć, ę, ł, ń, ó, ś, ź, ż must be UTF-8 encoded (never Windows-1250 or ISO 8859-2). KSeF rejects misencoded characters with code 21420.

Cross-links

• Poland hub — full KSeF mandate
• KSeF mandatory 2026
• FA(2) — structured invoice format
• Numer KSeF — legal UUID
• e-Doręczenia — associated notification
• OAuth 2.0 — RFC 6749 (IETF)
• ksef.mf.gov.pl — developer portal
• KSeF API documentation (FA(2))