Blog
Your own system has to talk to KSeF 2.0 — how to connect it
Poland's national e-invoicing system, KSeF, is now mandatory. If your company invoices in Poland — through a local entity, a branch or a subsidiary — and those invoices are created inside software you own, this is your problem to solve. Off-the-shelf invoicing tools already support KSeF. Your ERP, your shop, your industry-specific app does not.
How is connecting your own system different from buying an invoicing product?
Buying a product means using someone else's interface and someone else's invoice database, with people copying data across. Integrating your own system means the invoice stays where it is created, and you add a layer that speaks to the KSeF API. The difference is ownership: field mapping, retries and archiving are on you.
Practical consequences: the invoice goes out at the moment your system approves it; the KSeF number comes back into your database as part of the document; and every edge case your system handles today — corrections, foreign currency, invoicing on behalf of another entity — needs an explicit representation in the structured format.
How much time is actually left?
The obligation is already live. It applied from 1 February 2026 to large entities — those with gross sales above PLN 200 million in 2024 — and from 1 April 2026 to all other businesses. The smallest taxpayers may still invoice outside KSeF until the end of 2026, provided total invoiced sales stay below PLN 10,000 per month.
The date that matters for planning is the sanction window. Between 1 February 2026 and 31 December 2026 there are no penalties: authorities do not impose administrative fines for technical errors, delayed submissions, or mistakes caused by rolling out new processes. From 1 January 2027 penalties reach 100% of the VAT amount on the invoice, and 18.7% of the gross amount for invoices without VAT.
Four months remain. That is a window for a calm rollout, not a reason to wait. Ship now and you can find the cases you did not anticipate in production, at zero financial risk. Start in November and you will be debugging in January, under sanctions.
What do you actually have to build?
Six blocks: authentication and token handling, mapping your data onto the FA(3) structured invoice schema, submission and retrieval of the KSeF number, error handling with retries, an offline fallback, and archiving with the official confirmation (UPO).
Authentication and tokens
Your system authenticates on behalf of a taxpayer and maintains a session. Keep tokens outside the codebase, with access control and rotation. If you invoice for several entities — subsidiaries, or on behalf of another party — design for multiple contexts from day one. Retrofitting that is more expensive than doing it right.
Mapping onto FA(3)
This is the longest part of the work and the one most teams underestimate. Your database has its own fields, tax-rate dictionaries and discount conventions. Go field by field, decide what happens when data is missing, and validate before sending. An invoice stopped by your own validation is always better than one rejected by the API.
Submission and the KSeF number
Submission is asynchronous. You send the document, receive an acknowledgement, and the KSeF number arrives later. The document needs a real state machine — draft, sent, accepted, rejected — visible to the user. A single "sent yes/no" flag will not survive contact with production.
Errors and retries
Separate data errors from technical ones. A data error goes to a human queue; it will never pass on its own. A technical error retries with backoff. The hard rule: a retry must never create a second invoice. Every document needs an identifier that lets you recognise it has already been submitted.
Offline and fallback mode
Assume the network or the API will be unavailable at some point. The system must issue the invoice locally, mark it as pending, and send it once the connection returns — without manual re-entry and without blocking sales. It is the same pattern we use in autoPolar, which computes and stores data offshore with no signal. A queue plus idempotency, nothing exotic — but it has to be designed, not bolted on.
Archiving and UPO
Keep a durable record: the submitted XML, the KSeF number, the UPO and the timestamp. That is your proof the invoice was filed. Store it so it can be reconstructed independently of the application.
How do you test before going live?
Poland's Ministry of Finance has published the KSeF 2.0 API for verification of commercial systems, along with a Demo version of the KSeF 2.0 Taxpayer Application. Test against Demo and use the Taxpayer Application as a reference view to confirm your document looks the way it should. Documentation and environments: ksef.podatki.gov.pl.
A useful test set is not one clean invoice. It is corrections both up and down, advance payments, foreign currency, discounts, VAT exemptions — plus deliberately broken data to see how rejection is handled, and a network cut mid-submission.
Integrator or your own integration?
| Criterion | Third-party integrator | Your own API integration |
|---|---|---|
| Time to first invoice | Short, if your data fits their format | Longer — fields must be mapped |
| Changes in your system | File export or plugin | New layer, document states |
| Unusual documents | As many as the vendor supports | As many as you build |
| Where invoices live | With the vendor | With you |
| Future schema changes | Vendor handles it | You or your contractor |
| Third-party dependency | High — their outage is your outage | Only the KSeF API |
When is building your own integration the wrong call?
- You issue a few dozen standard invoices a month. A ready-made product is cheaper to run.
- Your ERP is a mainstream product in a standard configuration and the vendor already ships a KSeF module.
- You plan to replace the system within a year. Integrate the new one.
- Nobody will watch the error queue after launch. This is not a one-off project — someone has to act on rejected documents.
If any of these apply, we will say so and not push the project.
Who builds it?
A team that can read your existing code and database schema and add an integration layer — not a company selling its own invoicing product. RIDOA is a software house based in Warsaw. The same mechanics run in our own products: BARVEA exchanges data in structured IFC and BCF 2.1 formats under ISO 19650, ClimaBox is firmware, sensors and an app built by the same team, autoPolar runs fully offline.
What we don't do: staff leasing, hosting without a project, or small jobs below our budget threshold. Tell us what system you run and how many invoices you issue monthly — we reply with a scope and a quote within one working day. Contact · Services.