KSeF API integration, built for the phase you're actually in

Poland's mandatory e-invoicing is already live for large and mid-size taxpayers. Map invoice generation to the FA(3) schema, integrate the KSeF 2.0 REST API with real offline-mode handling, and reconcile KSeF numbers against JPK_VAT — before the 2027 grace period ends.

Check your phase Scope the integration

Two of three mandatory phases are already in force

KSeF became mandatory in stages rather than on one date. Large taxpayers went first, most other VAT-registered businesses followed two months later, and only the micro-entrepreneur phase and a full ban on correction notes outside KSeF remain ahead. A grace period softens enforcement through the end of 2026 — it does not remove the filing obligation.

Phase	Who it covers	Status on review date
Phase 1 — 1 February 2026	Large taxpayers with turnover above PLN 200 million in 2024 — roughly 4,200 businesses	Live and mandatory
Phase 2 — 1 April 2026	All other VAT-registered businesses, excluding micro-entrepreneurs	Live and mandatory
Grace period — through 31 December 2026	Any taxpayer: invoices outside KSeF tolerated if monthly sales covered are PLN 10,000 or less; no KSeF-specific penalty for usage errors	Active, ends 31 December 2026
Phase 3 — 1 January 2027	Micro-entrepreneurs; cash-register receipts with buyer NIP move fully into KSeF; standalone correction notes prohibited system-wide	Upcoming

Only e-invoices count

Poland's derogation means a document is only a valid invoice for VAT purposes once it carries a KSeF number. Implementing Decision 2022/1003.

2027 has real teeth

Reported KSeF-specific penalties reach up to 100% of the VAT on a non-compliant invoice once the grace period ends on 1 January 2027. Build for that date, not the lenient one.

Refunds move faster

Standard VAT refund timing is expected to shorten from 60 to 40 days for KSeF-compliant filers — but deduction rights attach on submission, so a slow pipeline still delays cash.

KSeF is national; ViDA is the EU-wide layer above it

Don't architect only for FA(3) and call the e-invoicing problem solved. KSeF governs domestic Polish invoicing under a country-specific derogation. A separate EU reform governs cross-border reporting, on a different timeline and a different schema.

KSeF today

Domestic B2B/B2G invoicing inside Poland, on the FA(3) XML schema, authorized by a special derogation from the general EU invoicing rules. Council derogation.

ViDA from 2030

Mandatory structured e-invoicing and near-real-time digital reporting for intra-EU B2B transactions from 1 July 2030, on the EN 16931 semantic standard. Directive (EU) 2025/516.

Design the mapping layer now

A Polish supplier invoicing a German or French buyer will eventually need output compatible with EN 16931-based formats — the same standard family behind France and Germany's Factur-X/ZUGFeRD approach — alongside its domestic FA(3) filing. Model invoice data once, internally, and generate FA(3) and EN 16931 output from that shared model instead of building two disconnected pipelines when ViDA's deadline gets closer.

Authenticate deliberately — KSeF 1.0 tokens don't carry over

KSeF 2.0 is a REST API (current version 2.0.0) with a public demo environment for integration testing before production. The Ministry of Finance publishes open-source client libraries, but the authentication model is a clean break from KSeF 1.0.

Choose an authentication method

Qualified electronic signature, qualified electronic seal, a KSeF-specific certificate issued through the MCU module, or another accepted electronic identification method.

Do not reuse KSeF 1.0 tokens

They are not compatible with KSeF 2.0 and are not migrated automatically — re-issue and re-test credentials for the new API.

Build against the demo environment first

Validate FA(3) generation, submission, and response handling against the public demo API before pointing at production.

Use official client libraries where they fit

The Ministry of Finance maintains open-source .NET, PHP and Java libraries covering the full KSeF 2.0 API surface — evaluate them before hand-rolling a client.

Separate identity from invoicing logic

Keep authentication/session handling as its own module so a credential rotation doesn't require touching invoice-generation code.

The Ministry of Finance's official technical repository hosts the current API version, schema files and client libraries — treat it as the source of truth over any third-party summary. CIRFMF KSeF API documentation.

One invoice, three pieces of proof

A submitted invoice isn't just accepted or rejected — it generates a specific set of artifacts your system needs to capture and store, and a rejected or out-of-system invoice needs its own handling path.

Artifact	What it is	Where it's used
FA(3) XML	The KSeF 2.0 logical invoice structure every submission must conform to	Generated from your invoicing data model before submission
KSeF number	Unique identifier issued on successful submission	Must appear in JPK_VAT reporting; proof the invoice is valid for VAT purposes
UPO	Urzędowe poświadczenie odbioru — the official confirmation of receipt	Legal evidence of submission; retain alongside the invoice
QR codes	One linking to the KSeF document, one verifying issuer authenticity	Printed/displayed on the invoice — buyers still verify through KSeF itself
Designation code (OFF / BFK / DI)	Marks an invoice issued outside KSeF under a permitted exception	Used in place of a KSeF number for reporting that invoice

Design for KSeF being unavailable, not just for it working

A production integration that assumes the API is always reachable will eventually miss a filing. KSeF 2.0 defines two resilience modes; the integration needs a queue that respects both.

Offline24 mode

Issue an invoice outside the live system when needed, then submit it to KSeF by the next business day — the obligation is deferred, not removed.

Emergency mode

Covers a full system outage on the Ministry's side; check current guidance for the applicable submission window before assuming next-business-day applies.

Durable local queue

Persist unsent invoices with retry logic that survives an outage of hours or days, not just seconds.

Reconciliation job

Run a scheduled job that confirms every locally queued invoice eventually received a KSeF number and UPO, and alerts on anything still pending.

Controls that survive a tax audit, not just a demo

KSeF-specific penalties activate from January 2027. Build controls now that make every filed invoice, and every exception to normal filing, defensible after the fact.

Pre-submission validation

Validate generated FA(3) XML against the current schema before sending — catch structural errors before they become rejected submissions.

KSeF number reconciliation

Reconcile every KSeF number against JPK_VAT records each reporting period; flag any invoice missing its number.

Exception-code control

Review every invoice carrying an OFF/BFK/DI designation code against its claimed exemption basis.

Offline-queue monitoring

Alert when an offline24 invoice approaches its next-business-day submission deadline unsent.

Correction-note readiness

Prepare for standalone correction notes being prohibited outside KSeF from January 2027 — route all corrections through the system.

Credential rotation

Track authentication-method expiry (qualified signature, seal, or KSeF certificate) separately from invoicing logic.

Get one invoice type through end-to-end first

Prove the full chain — generation, submission, KSeF number, UPO, JPK_VAT reconciliation — on your highest-volume invoice type before expanding to corrections, exceptions and less common document types.

Confirm your phase and scope
Determine which mandatory phase applies, which invoice types you issue, and which exemptions might apply to any of them.
Choose authentication and environment
Select an authentication method and validate it against the KSeF 2.0 demo environment before touching production.
Build the FA(3) mapping
Map your invoicing data model to the FA(3) schema, with versioned mapping rules and test cases against known-good invoices.
Integrate submission and confirmations
Implement the REST API calls, capture KSeF numbers and UPOs, and build the offline24 queue and emergency-mode handling.
Connect JPK_VAT reconciliation
Reconcile filed KSeF numbers against JPK_VAT reporting on a schedule, with alerting on gaps.
Go live in phases
Cut over your highest-volume invoice type first, then expand to corrections, exceptions and any remaining document types.

Acceptance criteria for the integration

Schema-valid

Every generated invoice passes FA(3) validation before submission, not after a rejection.

Traceable

A reviewer can move from a JPK_VAT entry to its KSeF number, UPO and original submission payload.

Outage-safe

Offline24 and emergency-mode invoices are queued, tracked to their submission deadline, and confirmed once KSeF is reachable again.

Reconciled

KSeF numbers and JPK_VAT records are reconciled on a schedule with alerting on any mismatch.

Exception-aware

OFF/BFK/DI-coded invoices are the deliberate exception, not the default fallback for a flaky integration.

ViDA-ready

The internal invoice data model can also produce EN 16931-compliant output without a second, disconnected build.

KSeF integration FAQ

Is KSeF actually mandatory yet, or is this still upcoming?

It's live. Large taxpayers (turnover above PLN 200 million in 2024) have been required to issue B2B invoices through KSeF since 1 February 2026. Nearly all other VAT-registered businesses, excluding micro-entrepreneurs, followed on 1 April 2026. As of this page's 2 September 2026 review, both phases are already in force — only the micro-entrepreneur phase, effective 1 January 2027, and the full prohibition on correction notes outside KSeF, remain ahead.

Does KSeF cover consumer (B2C) invoices?

No. The mandate applies to invoices required under Polish VAT rules for B2B and B2G transactions. Standard consumer-facing invoices and several specific exemptions — toll-motorway NIP receipts, passenger-transport tickets, EUROCONTROL air-traffic-control services, exempt financial and insurance services, and certain non-established foreign entities — sit outside the mandatory scope. Confirm exemption status per transaction type rather than assuming a blanket B2C carve-out covers every case.

What happens if KSeF is down when we need to invoice?

KSeF 2.0 includes an offline24 mode: an invoice can be issued outside the live system and must be submitted to KSeF by the next business day. A separate emergency mode covers a full system outage. Neither mode removes the obligation to submit — it defers the submission window, so the integration needs a queue that survives a multi-hour or multi-day outage without losing invoices.

Can we still send invoices outside KSeF at all?

Until 31 December 2026, invoices issued outside KSeF are tolerated if the monthly sales they cover don't exceed PLN 10,000, and errors in KSeF usage during this window carry no KSeF-specific penalty. From 1 January 2027, that grace period ends and KSeF-specific penalties — reported as up to 100% of the VAT on a non-compliant invoice — apply. Build for the post-2027 rules now rather than treating the grace period as a permanent fallback.

What does a business actually receive back from KSeF?

A successfully submitted invoice gets a unique KSeF number, which must also appear in the taxpayer's JPK_VAT reporting, plus a UPO (urzędowe poświadczenie odbioru) — an official confirmation of receipt. Invoices issued outside the system in permitted cases carry a designation code (OFF, BFK, or DI) instead of a KSeF number so downstream reporting can distinguish them.

Does the EU's ViDA reform replace KSeF?

No. KSeF is a Polish national system authorized by a country-specific derogation (Council Implementing Decision (EU) 2022/1003) from the general EU VAT invoicing rules. ViDA, under Directive (EU) 2025/516, introduces a separate EU-wide structured-invoicing and digital-reporting regime for intra-EU B2B transactions starting 1 July 2030, built on the EN 16931 semantic standard. The two run in parallel: KSeF governs domestic Polish invoicing; ViDA governs cross-border reporting. A system built only around FA(3) will still need an EN 16931-compliant path for cross-border transactions.

Do KSeF 1.0 tokens or integrations carry over to KSeF 2.0?

No. KSeF 1.0 authentication tokens are not compatible with KSeF 2.0 and are not migrated automatically. Re-authenticate using a qualified electronic signature, a qualified electronic seal, a KSeF-specific certificate issued through the MCU module, or another accepted electronic identification method, and re-test against the KSeF 2.0 API before relying on it in production.

Primary sources and status

Reviewed 2 September 2026. Phases 1 and 2 of the KSeF mandate were already in force on the review date; Phase 3 (1 January 2027) and the end of the penalty grace period (31 December 2026) had not yet occurred. ViDA (Directive (EU) 2025/516) is in force but its e-invoicing/digital reporting pillar applies from 1 July 2030. Yarify's integration architecture and delivery sequence are engineering recommendations, not tax or legal advice — confirm exemptions, penalties and deadlines with a tax adviser for your specific situation.