Polish e-invoicing (KSeF) for international software teams: what your product needs
Gideon Awolesi ·
If your product issues or receives invoices for companies in Poland, it now has to work with KSeF, the national e-invoicing system run by the Ministry of Finance. Since 1 February 2026, the largest companies have issued their invoices through it, every other VAT payer joined on 1 April 2026, and the smallest businesses join on 1 January 2027. We built our own invoicing app, InvoiceRate, on the KSeF API, so this guide covers what your team needs to know, in the order you'll run into it.
01Who has to use KSeF
KSeF applies to taxpayers based in Poland, and to foreign companies with a fixed establishment in Poland that takes part in the sale. A foreign company with no fixed establishment in Poland is generally outside the mandate, even if it has a Polish VAT number, and it can use KSeF voluntarily. The Ministry of Finance published guidance on fixed establishments on 28 January 2026, so check it, or ask your tax adviser, before you decide.
For a software team, the more useful question is who your customers are. If you sell an ERP, an accounting tool, or an invoicing product to companies in Poland, they need it to send invoices to KSeF and to pull the invoices they receive from it.
02Authentication and permissions
Every call to the KSeF API needs a JWT access token. You get one by authenticating in a context, usually the company's NIP, either with a document signed with a XAdES signature or with a KSeF token generated earlier. There's also a context for EU companies identified by a Polish NIP and an EU VAT number together.
KSeF then checks that the person or system authenticating has at least one active permission in that context. Permissions are granted inside KSeF by the company, so your onboarding has to explain how to grant them, because that's where a lot of new users get stuck.
03The FA(3) invoice schema
Invoices are sent as XML in the FA(3) structure. Production and the pre-production demo environment accept FA(3), along with the PEF structures for public procurement. The older FA(2) schema is only accepted on the test environment. KSeF treats the date in the P_1 field as the issue date, so make sure your product fills it in from the right place.
Once KSeF accepts an invoice, it assigns a KSeF number. That number is how the invoice is identified from then on, so store it, and show it to your users.
04Offline modes and QR codes
The Ministry's documentation describes three ways to issue an invoice when it can't go to KSeF in real time. In offline24 mode, the taxpayer can choose to issue offline and send it by the next working day. In offline mode, when KSeF is announced as unavailable, invoices go in by the next working day after it's back. In emergency mode, after an announced failure, they go in within seven working days.
An invoice issued offline needs two QR codes on its printed or PDF version: code I, so anyone can check the invoice in KSeF, and code II, which confirms the issuer's identity with a KSeF certificate. Invoices issued online need code I. Your product generates them locally, so this is a design and a development task, not something KSeF does for you.
05Test environments
There are three environments: TEST for integration, DEMO for final validation in conditions close to production, and PROD. On TEST, self-signed certificates are allowed, so several integrators can authenticate as the same company and the data isn't isolated. Use random NIPs there, never real data.
Plan for the differences too. The NIP checksum is only verified in production, and the rate limits on the test environment are ten times higher than in production, so a flow that works on TEST can still fail when you go live.
06The screens your users will need
Beyond the integration, KSeF adds screens to your product that didn't exist before: connecting a company to KSeF, the status of each invoice while it's processed, the KSeF number once it's accepted, rejected invoices with copy people can act on, and invoices issued offline that still need to be sent. These are the screens where your Polish users decide if they trust the product.
We collected the most common API error codes, with suggested user messages, in our KSeF API error codes reference. If you'd like us to review your KSeF flows before your customers do, our Product Readiness Review checks the UX and the architecture in two weeks, from €2,500.