KSeF integration: how the KRONENWERK KSeF 2.0 module works

KRONENWERK contains a KSeF 2.0 module that authenticates with a taxpayer's KSeF token, opens an online session, submits FA(3) invoices encrypted under the Ministry's key, polls for the KSeF number, retrieves the UPO and reads incoming invoices. The module is built and tested against the Ministry's environments, but it has not been used against the production KSeF, and KRONENWERK does not currently sell subscriptions to Polish companies until that is proven. For transmission the status is NOT YET READY. Your integration would use the ordinary API around it — customers, drafts, webhooks — and nothing KSeF-specific is exposed on the API.

What KSeF is, in one paragraph

KSeF (Krajowy System e-Faktur) is Poland's central clearance system: a structured invoice in the FA(3) schema is submitted to the Ministry of Finance's system, which validates it, assigns a KSeF number and returns an official receipt (UPO, urzędowe poświadczenie odbioru). Until that number exists the file is not legally an invoice. This makes Poland different from Germany, where a compliant file sent by any route discharges the obligation, and from Belgium, where the route is the Peppol network. Background is on KSeF explained; the schema on FA(3); the hub at e-invoicing in Poland.

What the KRONENWERK KSeF 2.0 module does

The module implements the KSeF API 2.0 as published in the Ministry's OpenAPI specification (paths and field names copied from there, not remembered). It works per taxpayer: every call is made in the context of one NIP with that taxpayer's KSeF token, and access tokens are cached per NIP and refreshed before they expire.

Two of the Ministry's authentication methods exist; the module uses the KSeF token method, in which a JSON document carrying a previously obtained system token is sent rather than an XML request signed with XAdES. The token belongs to the company and is issued to it inside KSeF; KRONENWERK stores it sealed and uses it only to authenticate. The Ministry documents both methods and notes that self-signed certificates are accepted only in the test environment.

Why it is environment-dependent and not yet ready

The Ministry publishes three environments, and the module is configured against exactly one of them at a time:

KRONENWERK's module has been exercised against the Ministry's non-production environments. It has not been used against the production KSeF, where a submission is a legal act that another party's tax position depends on. Until a real submission with a real UPO has been made and verified, KRONENWERK marks transmission NOT YET READY and does not sell subscriptions to Polish companies. This is a statement about proof, not about code coverage: the difference between "the client passes its tests" and "the Ministry accepted our invoice" is the one that matters, and it is the one still outstanding.

FA(3) generation itself — producing the XML from a draft's facts and validating it against the schema — is SUPPORTED WITH LIMITATIONS: the document is produced, but a FA(3) file without a KSeF number is not an invoice, so its usefulness is bounded by the transmission status above.

How a developer would use the API around it

Nothing on the KRONENWERK API is KSeF-specific. If the Polish route becomes available, an integration looks exactly like one for any other country: the KSeF work is inside issuance and transmission, both of which stay in the product.

1. Create the Polish customer with POST /customers, including country: "PL" and the buyer's NIP in vatId. FA(3) identifies the buyer by NIP, and a customer without one cannot be invoiced through KSeF.
2. Start the draft with POST /invoices/drafts and an Idempotency-Key.
3. A person completes and issues the draft in the product. The Polish module renders FA(3) XML and validates it; the number is spent and invoice.issued is queued.
4. The person transmits the issued invoice from the product. The module authenticates with the company's KSeF token stored in Settings → Delivery, opens a session, submits, polls, closes, and stores the KSeF number and UPO. An unknown outcome blocks resending until a reconciliation query has asked KSeF whether it already holds the document.
5. Your endpoint receives invoice.issued, later invoice.paid or invoice.cancelled. The KSeF number, the UPO and the transmission state are shown in the product and are not on the API today.

What the company must configure, when the route is available: legal entity master data with its NIP (derived from the tax number), the KSeF token entered in Settings → Delivery — KRONENWERK validates it immediately by making an authenticated call with the very token it just stored, and refuses to keep a token that does not work — and, for your integration, an API key with customers:write, customers:read, invoices:write, invoices:read and companies:read plus a webhook endpoint. The general API mechanics are on the accounting API page and invoice API page.

KSeF API 2.0 basics, with sources

If you are evaluating a direct integration instead, the Ministry's material is the primary source and this is where to start.

• Integrator guide: the Ministry's guide (dated 5 May 2026 in the current revision) covers authentication, permissions, KSeF certificates, offline modes, QR codes, interactive and batch sessions, invoice retrieval, incremental retrieval, KSeF token management, encryption keys, limits and test data, with examples in C# and Java from its open-source reference clients. github.com/CIRFMF/ksef-docs.
• OpenAPI: each environment serves its own specification under /docs/v2; the test one is at api-test.ksef.mf.gov.pl/docs/v2. Errors are RFC 7807 problem documents with detail and an errors[] list.
• Authentication: obtain a challenge (valid ten minutes), then either send an XML AuthTokenRequest signed with XAdES using a qualified certificate or a KSeF certificate, or send a JSON document with a KSeF token; poll the status; redeem a JWT access token and a refresh token. The authenticating party must hold at least one active permission for the chosen context (a NIP, an internal identifier or an EU VAT composite identifier). uwierzytelnianie.md.
• Sessions: an interactive session takes invoices one at a time and returns a status per invoice; closing the session triggers generation of a collective UPO. A batch session is documented separately for bulk submission. Public keys for encrypting the session key and the KSeF token are published by the Ministry and rotate.
• Environments and maintenance: TEST and DEMO must never receive production invoices or real party data; the Ministry schedules maintenance on the test environments from 16:00 to 18:00 and publishes API-affecting changes in its changelog. srodowiska.md.

The KSeF guide for developers goes deeper into the schema and the session model.

How KRONENWERK handles this

NOT YET READY for transmission. The KSeF 2.0 module — token authentication, session, FA(3) submission, UPO retrieval and receiving — is built and environment-dependent, and it has not been used against the production KSeF. KRONENWERK currently does not sell subscriptions to Polish companies until that is proven, and nothing on this page should be read as implying government or production acceptance. FA(3) generation is SUPPORTED WITH LIMITATIONS. The API exposes no KSeF-specific endpoint, event or field; when the route is proven, integrations will use the same customer, draft and webhook calls as everywhere else. The Poland country page is at Poland; the product's e-invoicing scope is on e-invoicing.