What changed in KSeF API 2.0?
The Ministry of Finance maintains the technical documentation publicly, together with official open-source client libraries in C# and Java. Four differences from version 1.0 require a design decision rather than a configuration change.
- Authentication is separated from session initiation. The JWT access token is reusable between sessions, which simplifies connection pooling but makes deliberate management of the token lifecycle necessary.
- Encryption is mandatory in both modes — batch and interactive. In version 1.0 it was optional for interactive sessions. This is the most common cause of failed migrations, and it fails late, in integration testing, rather than at build time.
- The batch mode processes invoices independently instead of rejecting the whole batch at the first error. That changes error handling: after a partial failure the batch must not be resent as a whole.
- Naming has been unified to REST conventions.
The first of those has a second-order effect worth designing for. Because the access token now survives the session, a restarted process can re-authenticate cheaply — but it inherits a session whose outcome it does not know. Record the session identifier alongside the operation identifier, so that after a restart the integration can ask what happened to that session rather than assume it never started. It is the same question the idempotency rules ask about a single document, one level up.
How does authentication work, and which method suits a server integration?
Five methods are available.
| Method | Use |
|---|---|
| Qualified electronic signature (XAdES) | A natural person holding a qualified signature |
| KSeF token | Automated processes; encrypted with RSA-OAEP SHA-256 |
| Natural person certificate | XAdES path, identification by PESEL or NIP |
| Qualified electronic seal | The entity; identification by NIP |
| Profil Zaufany | XAdES path |
The flow is uniform: fetch a challenge, sign or encrypt it, submit it, then exchange the result for a JWT access token together with a refresh token valid for seven days. mObywatel, the Polish state identity application, was added as a route from February 2026.
For a server-to-server integration the natural choices are the KSeF token or a qualified electronic seal. Plan rotation from the outset: from 1 January 2027 token validity becomes configurable within a range of 1 to 365 days with automatic renewal, but no integration should be built on the assumption that a credential is permanent. For a foreign-headquartered group there is a procurement point here as well — a qualified seal is obtained from a qualified trust service provider, which is a procurement exercise with its own lead time rather than something the integration team can arrange in a sprint.
Do KSeF certificates carry permissions?
A property to establish before designing any access control: KSeF certificates carry no permissions at all. Permissions are administered separately. The certificate serves only to confirm identity.
Two mutually exclusive types exist:
- Authentication — keyUsage Digital Signature, used to authenticate.
- Offline — keyUsage Non-Repudiation, used to sign the second QR code on invoices issued in an offline mode, including tryb offline24 (the elective offline mode), niedostępność (announced unavailability) and awaria (announced failure).
Certificates are issued from a PKCS#10 request using RSA 2048 or the NIST P-256 curve. An organisation that expects to use the offline modes must have an Offline certificate issued before it is needed — which, in practice, is a fact usually discovered in the middle of an incident. The consequence for group access governance is sharper still: an access review that inspects certificates alone tells you nothing about who can issue an invoice, because the permission that matters was granted somewhere else entirely.
Which environments are available, and what may you put in them?
| Environment | Address | Characteristics |
|---|---|---|
| Test | api-test.ksef.mf.gov.pl/docs/v2 | Also carries release-candidate versions of new features |
| Pre-production (Demo) | api-demo.ksef.mf.gov.pl/docs/v2 | Configuration matching production |
| Production | api.ksef.mf.gov.pl/docs/v2 | — |
Real invoices and the real data of real entities must not be used in the test and demo environments; random NIP numbers should be used instead. That constraint is worth flagging early to a group IT function, because copying a slice of production into a lower environment is standard practice in most large organisations and is not available here. Demo is the right place for performance testing and failure scenarios, because it reproduces the production configuration.
Which patterns belong in the integration from the first day?
A durable operation identifier before the first call
Assigned deterministically from the source document and identical across every retry. Without it there is no way to answer the question of whether a document has already been accepted — which is where duplicates come from.
State persisted before the call, not after it
The state submission started
must be durable before the request leaves the process. A system that records only on response has no trace of the attempts that never came back.
Query rather than retry
After a timeout the default reaction must be a status check, not a resubmission. Standard retry policies in HTTP libraries are actively harmful in this context and have to be switched off deliberately for issuing operations. In a group, that switch usually lives in a shared gateway rather than in your code.
Local validation before submission
Validating against the FA(3) logical structure on your own side eliminates the most common rejections and reduces the number of calls. Note that FA(3) applies to correcting invoices as well, including corrections to original documents issued earlier under FA(2) or FA(1).
Control of the P_1 field
KSeF treats only P_1 as the date of issue. A divergence between P_1 and the moment the document was actually created is a silent source of missed deadlines in the offline modes. Validating it belongs in the integration layer, and it matters more in a group whose scheduler runs on a different clock or a different working calendar from the Polish entity.
Settling batches document by document
Since the batch mode processes invoices independently, the result has to be settled per document. Code that checks only the status of the whole batch will miss individual rejections — or, worse, resend the lot.
How should errors be classified?
| Category | Example | Response |
|---|---|---|
| Permanent | Structural error, invalid NIP | Do not retry. Route for correction. |
| Transient | Rate limit exceeded, momentary unavailability | Retry after a delay, following a status check. |
| Unresolved | Timeout, dropped connection | Status query only. Never resubmit. |
The third category is the one absent from most implementations: unresolved outcomes are treated as transient and retried. Throughout 2026 that choice costs nothing, because there is no penalty for errors during the transitional period. From 1 January 2027 the consequences become financial, when the penalties in art. 106ni of the VAT Act begin to apply — up to 100% of the tax shown on an invoice issued outside KSeF, and up to 18.7% of the total amount due where no tax is shown. See KSeF penalties from 1 January 2027.
What about rate limits and throughput?
Rate limits are to be raised from 1 January 2027, along with other changes announced by the Ministry of Finance after the June 2026 consultations. Until then, design your own queueing with rate control rather than relying on handling a refusal. The queue pays for itself twice: it is also the natural place to attach approval checkpoints, and the natural place to hold documents while an offline mode is in force.
What should you test on demo before go-live?
Demo reproduces the production configuration, which makes it the only environment where a failure scenario means anything. Six are worth running deliberately, because each corresponds to one of the failure modes above and none of them appears in a functional test plan by default.
- A timeout with no response. Confirm the integration moves the document to a status query and does not resubmit. This is the test most implementations fail.
- A process restart mid-submission. Stop the worker between the request leaving and the response arriving, then check that the document is recognised as in flight rather than as unprocessed.
- A partially failed batch. Confirm the result is settled document by document and that the batch is not resent whole.
- An expired or revoked credential. Check that the failure is classified as permanent and reaches a named owner, rather than being retried into a rate limit.
- A rate limit. Confirm your own queue paces the work, rather than relying on refusals to pace it for you.
- An offline mode. Verify that an Offline certificate exists, that the second QR code is produced, and that the deadline clock for the mode starts when the document is issued rather than when someone remembers.
Run all six with random NIP numbers, since real data is not permitted here. For a group, that argues for building one synthetic FA(3) data set and reusing it across entities, rather than negotiating a data-masking exception per subsidiary.
Whose credentials is the integration actually using?
This is where a group integration diverges from a domestic one, and it is a scoping question before it is a technical one.
The obligation to issue faktury ustrukturyzowane (structured invoices) attaches to the Polish taxpayer, and the test is establishment in Poland rather than Polish VAT registration. A taxpayer with neither a seat nor a fixed establishment in Poland is outside the issuing obligation; a foreign-established company with a Polish fixed establishment is inside it where that establishment participates in the supply. The limit is inherited from EU law: Article 218 of the VAT Directive, as amended by Council Directive (EU) 2025/516 of 11 March 2025, allows a Member State to require electronic invoices only from taxable persons established within its territory. Scoping is set out in full under automating KSeF invoicing.
Four consequences follow for the integration itself.
- Credentials are per taxpayer, and someone must own them. If the ERP is operated centrally and the KSeF token belongs to the Polish entity, decide explicitly who holds it, who rotates it and who is accountable when it is used. That is an intercompany control question, and it is answered badly by default.
- Sessions do not aggregate. A group platform serving several Polish entities holds several credential sets and authenticates per taxpayer. Design the connection pool around that from the start rather than retrofitting a tenant boundary later.
- Permission administration is invisible to your code. Because certificates carry no permissions, the effective right to issue is granted in KSeF administration, outside your repository and outside your change control. Include it in the access review explicitly, or it will not be reviewed at all.
- The evidence has to be readable by people who do not read Polish. Error codes, offline-mode decisions and approval records should be stored as structured fields with bilingual definitions, not as free text in a Polish-language ticketing queue. The audit trail is what an inspection reads.
There is a structural point behind all four. Poland runs a clearance model: the state validates the invoice and assigns its identifier before the document is in circulation. Germany's E-Rechnung obligation is a format obligation on invoices exchanged directly between the parties, with no central system to authenticate to; France routes invoices and reporting through certified platforms. A group integration component built for either of those has no concept of a state-issued identifier, a session, or an outcome that is unknown — and all three are load-bearing here. The glossary carries the local vocabulary for each market.
What changes when an AI agent drives the integration?
The failure modes above are all recoverable when a deterministic process meets them, because the response is written down in advance. An agent decides its response from its reading of the error, and an unresolved outcome is exactly the case where that reading is least reliable. Three requirements follow: the operation identifier is assigned outside the model; the error classification is enforced by the integration layer rather than inferred by the agent; and the model and configuration version in force at the time of each call is recorded, because otherwise the behaviour cannot be reproduced at all. The general treatment is under approving AI actions and AI agent audit trails.
In practice
BarzelVault sits between the integration and KSeF: it applies policy and approval thresholds ahead of execution and issues a signed audit receipt for each call. The receipt is written before the request leaves the system, which is the part of the record that cannot be reconstructed afterwards.
Frequently asked questions
What changed in API 2.0?
Authentication separated from session initiation, mandatory encryption in both modes, independent processing of invoices in batch mode, and REST-conformant naming. It has applied since 1 February 2026.
Is encryption mandatory?
Yes, in the batch and the interactive mode. That is a change from API 1.0, where it was optional for interactive sessions.
Which environments are available?
Test, pre-production demo and production. Real data must not be used in the first two; use random NIP numbers.
How long is a token valid?
Authentication returns a JWT access token and a refresh token valid for seven days. From 1 January 2027 KSeF token validity is to be configurable between 1 and 365 days.
Does a KSeF certificate grant permissions?
No. It confirms identity; permissions are administered separately. The Authentication and Offline certificate types are mutually exclusive.
What should happen after a timeout?
A status query, never a resubmission. The invoice may already have been accepted and assigned a numer KSeF.
Related reading
- Duplicates and retries in KSeF
- Automating KSeF invoicing
- The KSeF audit trail
- KSeF penalties from 1 January 2027
- Governed workflow automation
- Register of corrections
In practice
The control has to run before the invoice becomes irreversible.
An accepted structured invoice can be corrected but never deleted, and from the penalty date every defect has a price. Barzel puts the approval threshold, the duplicate check and the signed record in front of submission, so the process can be defended on the day an auditor or the tax authority asks.
95 days leftKSeF penalties apply from 1 January 2027
BarzelVault
The AI action firewall: decide what an agent may do before it does it.
- Approval thresholds and policy checks enforced before execution; human approvals that expire and escalate.
- Cryptographically signed audit receipts: trigger, inputs, policy version, approver, outcome.
- Credential isolation, spend and action limits, and an emergency kill switch.
Free tier: 10,000 calls a monthPaid plans from $199 a monthLive on MCPize
BarzelOps
Governed workflow automation across the systems that run the business.
- Durable, idempotent execution: a timeout is retried once, never filed twice.
- Human approval checkpoints that pause the workflow and resume it.
- Isolation per entity or client, signed evidence receipts and a portable manifest; HubSpot, Xero, Gmail, Google Drive and Slack.
Free tier: 100 calls a dayPaid plans from $19 a monthLive on MCPize
Enterprise: written quote by email within two business days. No sales call.
Sources
- Ministerstwo Finansów, KSeF 2.0 integration guide — authentication, sessions and the overview of key changes, github.com/CIRFMF/ksef-api.
- Ministerstwo Finansów, Certyfikaty KSeF (KSeF certificates) — github.com/CIRFMF/ksef-docs.
- Ministerstwo Finansów, Pierwsze konsultacje po częściowym wdrożeniu KSeF — podsumowanie, 11 June 2026.
- Ministerstwo Finansów, Broszura informacyjna dotycząca struktury logicznej FA(3), 4 March 2026.
- Ministerstwo Finansów, Zakres obowiązkowego KSeF — ksef.podatki.gov.pl.
- Ustawa z dnia 11 marca 2004 r. o podatku od towarów i usług (Polish VAT Act), art. 106ga, art. 106ni — ISAP.
- Council Directive (EU) 2025/516 of 11 March 2025 amending Directive 2006/112/EC as regards VAT rules for the digital age — amended Article 218.
This article is for information and does not constitute tax or legal advice. The Polish text of the instruments cited is the binding one.