KSeF: How to Connect Your Sales System via Token and API

As of 2026, the National e-Invoicing System stops being optional. This guide shows, step by step, how to technically connect a sales system to KSeF: choose an authentication method (a token or a certificate), connect to the 2.0 API, issue an invoice in the FA(3) structure, and test everything in the test environment before you go live.

What determines your deadline and what you actually need to connect

To connect your sales system to KSeF, you need three things at once: an authentication method (an authorization token or a KSeF certificate), integration with the KSeF 2.0 API, and generating invoices in the FA(3) structure in XML format. That is the complete answer to the question “how do I connect it” — the rest of this article breaks each of these elements down to its fundamentals.

First, though, the deadline, because it determines when you need to have this ready. As of February 1, 2026, the target version of the system is in force: the only accepted invoice structure is FA(3), and the only working interface is the KSeF 2.0 API. The older FA(2) and API 1.0 are being phased out. What matters to every seller: the obligation to receive invoices in KSeF applies to all taxpayers as early as February 2026 — even if you yourself only have to start issuing them in April.

The thresholds and dates are approximate — before you plan your rollout, verify them against the current legislation and at ksef.podatki.gov.pl. If you are only just getting to grips with the topic from the business side, start with our overview KSeF 2026 for e-commerce sellers, and focus here on the technical layer.

Authentication: token, KSeF certificate or seal

Before your system sends anything, it has to prove to KSeF that it is acting on behalf of your company. Three related concepts come into play here: authentication (who you are), authorization (what permissions you have), and the automation key (what you sign subsequent API requests with). The order is fixed: the business owner first logs in with a “strong” method, grants permissions, and only then generates a token or certificate for the integration.

That “strong” method for the first login is the Trusted Profile (Profil Zaufany), a qualified electronic signature (a natural person, by PESEL/NIP) or a qualified electronic seal (an organization, by NIP). This entire process is handled by the Certificates and Permissions Module (MCU), launched on November 1, 2025.

Permissions are granted separately for different actions — the right to issue invoices, to view and receive them, and to manage permissions (the administrative role) are usually kept apart. A sales-system integration needs the permission to issue and receive, assigned to the entity or person on whose behalf you will generate the token or certificate. Decide up front who in the company owns this configuration — that person will unlock and revoke access when you change software providers.

The KSeF authorization token

This is the most convenient method for “system-to-system” integration. You generate the token once (after authenticating with a strong method), and it then serves to sign subsequent API requests — without reaching for a signature or certificate each time. Two things to keep in mind: tokens from KSeF 1.0 do not work in KSeF 2.0 (you have to generate a new one), and the 2.0 tokens themselves expire on December 31, 2026. As of January 1, 2027, KSeF certificates replace them. So treat the token as a transitional solution — and as a secret: keep it out of your code repository, rotate it, and restrict access.

The KSeF certificate (type 1 and type 2)

KSeF certificates are available from the MCU as of November 1, 2025, valid for a maximum of 2 years and renewable. This is not a qualified certificate within the meaning of eIDAS, but it is recognized inside KSeF. It comes in two types: type 1 serves an authentication function (like a signature/seal when dealing with the API), while type 2 is used to digitally sign the QR codes on invoices issued in offline mode. This is the target solution — if you are building an integration for years to come, it is worth basing it on a type 1 certificate from the start rather than on an expiring token.

Seal, qualified signature and Trusted Profile

These methods are used mainly for the first login and for granting permissions. A qualified electronic seal authenticates the entire organization (by NIP) rather than a specific person — convenient for a company where several people maintain the integration. The Trusted Profile is the simplest route for a sole proprietorship.

The FA(3) structure: what changes compared with FA(2)

As of February 1, 2026, the only valid invoice structure is FA(3). If your system currently generates XML in FA(2), you have to update the mapping. The most important differences:

• Binary attachments — you can attach, for example, an acceptance protocol or a specification to the invoice (this was impossible in FA(2)).
• A new “employee” role in the Podmiot3 (Entity3) node.
• Refined payment-term fields — more precision for split and multiple due dates.
• Extended character limits in the names of goods and services (the P_7 field).
• Support for local-government units (JST) and VAT groups — new entity scenarios.

The key rule: the generated XML must match the XSD schema exactly, 1:1, as published by the Ministry of Finance. The smallest discrepancy means the invoice is rejected, and a rejected invoice does not get a KSeF number — meaning that, as far as the system is concerned, it does not exist. That is why you should not “hand-stitch” the XML: use a library or a layer that maps order data onto the structure, and validate locally against the XSD before sending. You can download the current FA(3) XSD, the OpenAPI (Swagger) specification, the integrator’s manual, and ready-made SDKs (Java, .NET) along with sample code from ksef.podatki.gov.pl. A separate case common in e-commerce — invoices for marketplace orders and receipts — is covered in our article KSeF and selling on Allegro.

In practice, most rejections come not from exotic fields but from the basics: an incorrect or missing buyer NIP, a VAT rate inconsistent with the line item, a wrong date format, or amounts that do not add up to the last grosz. Take care of correcting invoices and advance-payment invoices too — they have their own rules in FA(3), and in e-commerce they show up with returns and prepayments. Map these cases right away instead of bolting them on later “in production”.

The KSeF 2.0 test environment — test before you go live

The Ministry of Finance provides three environments. The sensible scenario is: first the test one (development), then pre-production (acceptance), and finally production. Do not start with production — there, invoices carry real legal effect.

In the test environment you can use self-signed certificates and generate a token without “real” documents, and test activity does not affect production permissions or certificates. If you do not yet have your own integration, the free KSeF 2.0 Taxpayer Application from the MF is suitable for manual verification, and it also has a test version (released in autumn 2025). The addresses are approximate — always confirm them at ksef.podatki.gov.pl, because environment details are updated from time to time.

Step by step: connecting your system via the API

The sequence below assumes you already have a sales system that knows your order and buyer data. The integration’s job is to translate that data into the KSeF language and receive confirmation. Go through the steps in order — skipping permissions or local validation is the most common reason for getting “stuck” on the first submission.

1. Sort out permissions in the MCU. The owner logs in with a strong method (seal / signature / Trusted Profile) and grants permissions — e.g., to issue and receive invoices — to the right people and entities. Without this, neither the token nor the certificate will work.
2. Generate the automation key. In the MCU, create an authorization token or a KSeF type 1 certificate. Store the secret in a safe place (a secrets manager, environment variables), never in code.
3. Download the integration materials. The OpenAPI specification, the XSD schemas for FA(3), the SDKs, and the integrator’s manual are on ksef.podatki.gov.pl.
4. Set up the test environment. Point the base URL at the test address and implement the challenge → signature → token flow: the system fetches a challenge, signs it, and in return gains session access.
5. Open a session in the right mode. An interactive session handles single invoices with immediate validation (a document up to about 1 MB). A batch session is a package of many invoices sent as a ZIP archive split into parts — good for the high volumes typical of e-commerce.
6. Send the FA(3) invoice. Map the order data onto FA(3) XML, validate locally against the XSD, and then send it within the open session.
7. Receive the KSeF number and UPO. After successful validation, the system assigns a KSeF number (35 characters), returned in the UPO — the official confirmation of receipt. Poll for the status (approximately: 150 = in progress, 200 = accepted) and save the KSeF number and UPO with the order.
8. Handle errors and retries. A rejected invoice has no KSeF number — fix the XML and resend it. Build a retry queue and a response log so nothing is lost on transient errors.
9. Move to demo, then to production. Repeat the tests on the pre-production environment, and after the applicable deadline (February 1 or April 1, 2026) switch the configuration to production.

If you want the invoice to be created automatically when an order’s status changes (e.g., “paid” or “shipped”), treat the KSeF connection as part of a broader order automation — otherwise you will add manual work for your team rather than remove it.

Operating modes: online, offline24 and emergency

KSeF provides several modes, and for a high-traffic store this is not a curiosity but part of your continuity plan:

• Online (default) — the invoice goes to KSeF immediately, and you get the KSeF number right away.
• Offline24 — you issue the invoice without a connection (an OFF prefix, two QR codes, the second signed with the seller’s certificate) and submit it to KSeF by the next business day at the latest.
• Emergency — triggered by an official MF announcement during a system outage; you submit the invoices within a window of up to 7 business days from the end of the outage (the deadlines are approximate — verify them at rollout).

The practical takeaway: plan for offline-mode handling in your code so that an outage on the KSeF side does not halt invoicing and shipments in your store.

Maintaining the integration: what to plan for the long run

Connecting to KSeF is not a one-off project but something you have to maintain. Plan a few things up front. First — secret rotation: the token expires at the end of 2026, and a certificate is valid for up to two years, so you need a renewal calendar to keep the integration from stopping overnight. Second — status monitoring: every submission should end with a confirmed KSeF number, and anything stuck “in progress” or rejected must land on a visible list to be handled. Third — logging and archiving: keep the sent XML, the KSeF number, and the UPO, because that is your proof of issuance in the event of an audit. Fourth — a regression environment: when the MF updates the schema or the API, check the change on the test environment before it touches production.

The most common mistakes when connecting (checklist)

• Using an old token from KSeF 1.0 — it won’t work in 2.0; generate a new one.
• Hand-stitching XML instead of mapping — a minor error means rejection and no KSeF number.
• Testing straight on production — start with the test environment.
• Not having permissions granted in the MCU before generating the token.
• Treating the token as a permanent solution — remember the December 31, 2026 expiry and the switch to a certificate.
• Not saving the KSeF number and UPO with the order — that is your proof of issuance.
• Ignoring the obligation to receive — it applies to everyone as early as February 2026.
• No plan for an outage and offline mode.

For a store selling across several channels, the hardest part is not the API itself but wiring it into the rest of the workflow: an order from Allegro or Shopify, correct buyer data, the right VAT rate, and issuing FA(3) at the right moment. Multichannel-class tools — including the upcoming Nimo — are ultimately meant to take this workflow off your hands, so the seller doesn’t have to maintain their own KSeF integration; how such KSeF invoice handling is meant to look is something we describe separately. Whatever tool you choose, the principle is the same: test everything on the test environment before your invoices start carrying legal effect.

Frequently asked questions

Do I need a certificate, or is a token enough?

Until the end of 2026, an authorization token is enough for automation via the API. As of January 1, 2027, tokens expire and KSeF certificates replace them, so an integration built for the long term is worth basing on a type 1 certificate from the start.

How does FA(3) differ from FA(2)?

FA(3) is the only valid structure as of February 1, 2026. It adds, among other things, binary attachments and an “employee” role, refines the payment-term fields, and extends character limits. The invoice must match the MF’s XSD schema exactly, or it will be rejected.

Where should I test the integration?

Start in the KSeF 2.0 test environment (approximately api-test.ksef.mf.gov.pl and the ap-test.ksef.mf.gov.pl application), and then move to pre-production (demo). Test activity does not affect production data. Confirm the current addresses at ksef.podatki.gov.pl.

What are the KSeF number and the UPO?

The KSeF number is a unique identifier (35 characters) assigned after successful validation — it confirms that the invoice is in circulation. The UPO is the official confirmation of receipt in which that number is returned. Save both with the order as proof of issuance.

From when do I have to issue invoices in KSeF?

The largest (gross sales above PLN 200 million in 2024) from February 1, 2026, all other businesses from April 1, 2026, and the smallest issuers from January 1, 2027. Receiving invoices in KSeF applies to everyone as early as February 2026.