KSeF (Poland's national e-invoicing system)

Complaia connects a Polish sales entity (your invoicing company) to KSeF, Poland's national e-invoicing system. It sends the entity's invoices and corrections there, and brings back the KSeF number and the official confirmation of receipt. You connect an entity once, in a step-by-step wizard. After that, issuing an invoice for a company buyer also sends it.

Where to find it: Finance → Sales entities — open a Polish entity and click Configure KSeF integration. Sending happens on an issued invoice under Finance → Invoicing.

Poland only

Everything on this page applies only to sales entities whose country is Poland. For any other entity the KSeF sections, buttons and messages are not shown. A company without a Polish entity does not see the KSeF permissions in the role editor either.

When you'll use it

• Connecting a Polish company to KSeF for the first time.
• Trying the connection on the demo environment, then moving to production.
• Sending an invoice, checking what KSeF decided, downloading the confirmation.
• Issuing an invoice in offline mode, when you need to hand it over before it reaches KSeF.
• Finding out why an invoice was refused or rejected, and fixing it.
• Disconnecting an entity or replacing its certificate.

Key concepts

Environments

The wizard offers three choices:

Choice	What it is	Legal effect
Production	The real system. Needs a production certificate.	Yes, this is filing.
Demo (pre-production)	A copy of the real system for trying things out. Needs its own certificate.	None.
No KSeF	The entity sends nothing to KSeF.	—

An entity connected in the past to the older test environment may still show it. It is no longer offered.

Accepted on demo is not filed

An invoice sent to the demo environment comes back Accepted with a KSeF number, but it has not been filed. The invoice form and the invoice page warn you about it. When the entity later moves to production, such an invoice is not sent there. It stays an invoice outside KSeF, and you change it with a correction.

Connected means a certificate is stored

An entity is Connected from the moment a KSeF certificate is stored for it, uploaded by you or generated by the automatic method. Choosing an environment in the wizard changes nothing by itself. Removing the certificate disconnects the entity. A certificate belongs to one environment, so changing the environment means replacing the certificate.

What is sent and what is not

Document	Sent to KSeF?
Invoice or correction for a Company buyer, including a foreign company	Yes
Invoice or correction for an Individual	Never. See below.
Pro forma	Never
Document under the EU One-Stop Shop (OSS) scheme	Never. See OSS returns.
Invoice in a foreign currency without an exchange rate	Not by Complaia. See What Complaia does not send.

An invoice in a foreign currency with an exchange rate of the National Bank of Poland (NBP) is sent, with the VAT shown in PLN. An invoice with an exempt (zw) line is sent, with the exemption basis. See VAT on invoices.

Consumer invoices are never sent

An invoice whose Buyer type is Individual does not go to KSeF, because the obligation covers sales to businesses. Its page shows a note instead of the KSeF card. You give the document to the customer as a PDF. Consumer invoices have their own numbering series.

What connecting changes on an invoice

• For a company buyer, the Issue button becomes Issue & send to KSeF. One click issues the invoice and sends it.
• Before a number is assigned, the invoice is checked against the KSeF pre-check. A document that would fail it is not issued and uses no number.
• An invoice that goes to KSeF cannot be e-mailed or downloaded until it has been sent, unless you issue it in offline mode. The PDF then carries the KSeF QR code.
• Cancel invoice is not available for documents in KSeF. Once KSeF has accepted a document, it cannot be reverted to draft or deleted either. A correction is the only way to change it.
• An invoice sent to KSeF later than its issue date enters KSeF as an offline invoice, with the issue date from the invoice.

The pre-check

Complaia checks the document itself before anything is sent. The same check runs when you issue and when you send. It looks at:

Part	What must be true
Seller	A valid Polish tax number, the same one the KSeF connection uses. Country Poland. A name and a full address.
Buyer	A name, a full address and a country. For a buyer in Poland, a valid Polish tax number if one is given. An EU VAT number, if given, must start with an EU country code.
Lines	Every line has a name and a quantity above zero. Every line has a rate that KSeF accepts, or a code. An exempt line needs an exemption basis.
Correction	The corrected invoice is in KSeF and has a KSeF number, and the correction has a reason.

When the check fails while you issue, the dialog The invoice was not issued lists what to fix. When it fails while you send, the dialog Invoice needs corrections does the same.

What Complaia does not send to KSeF

An invoice in a currency other than PLN, with a taxed line, must show its VAT in PLN. If the invoice has no NBP exchange rate, Complaia cannot do that, so it does not send the invoice.

Do not issue the same invoice again elsewhere

The invoice keeps its number and stays issued. The form and the invoice page show the note The system will not send this invoice to KSeF, with the reason and the next steps. Do not issue the same invoice again in another program: two documents would have one number.

Offline mode

Normally an invoice goes to KSeF right after it is issued (Standard mode). In Offline24 mode the invoice gets its number and two QR codes at once, so you can hand it to the buyer before it reaches KSeF. You then send it to KSeF yourself, from the invoice page, no later than the next business day.

• Offline24 needs a KSeF Offline certificate on the entity. See Get the Offline certificate.
• Complaia does not send offline invoices on its own. The invoice page shows the deadline, and the list shows the invoice under KSeF: needs attention once it is late.
• When the Ministry of Finance announces that KSeF is unavailable or has failed, the law gives more time. The deadline shown in Complaia still counts from the issue date.
• An offline invoice that has already reached the buyer must be sent to KSeF. It cannot be reverted, cancelled or deleted.

Needs attention

When some of your documents need action in KSeF, the invoice list shows two views: All and KSeF: needs attention, with a count. The second view lists those documents, and each row says why:

Reason	What to do
Not sent	Send the invoice from its page.
Rejected	Read the reason on the invoice page, fix the data and send again.
Past the sending deadline	An offline invoice is late. Send it now.
Needs technical correction	KSeF rejected the file of an offline invoice. See Fix a rejected offline invoice.
New version for the buyer	The buyer has a printout of a different file than the one in KSeF. Send them the document again.

The screen

The wizard

📷 Screenshot to add: the KSeF integration wizard on the Environment step, with the Production, Demo and No KSeF cards

Configure KSeF integration opens a page with the status (Connected or Not connected) and a five-step wizard. Above the steps, Learn more about the KSeF integration opens a short introduction.

Step	What you do there
Environment	Choose Production, Demo (pre-production) or No KSeF.
Configurator	Answer a few questions: how many companies you have, the type of business, whether the company has a qualified electronic seal, and whether you connect KSeF to other systems too. Skip configurator takes you straight to Authentication.
Method	Read the recommended method, manual or automatic, with the reason. Click Use this method or I want to choose another method.
Authentication	Connect with the Manual method (upload a certificate) or the Automatic method (sign a file with a Trusted Profile). You can switch between the two here.
Summary	See the connection: environment, Certificate issued to, Valid until, and a link to log in to KSeF. Here you can Switch to production or Disconnect integration, and manage the KSeF Offline certificate.

An entity that is already connected opens on Summary. The earlier steps are locked until you disconnect.

The KSeF card on an invoice

📷 Screenshot to add: an issued invoice with the KSeF card showing status Accepted, the KSeF number and the Download UPO button

An issued invoice or correction of a connected entity, for a company buyer, has a KSeF card. It shows:

• the Status:

Status	Meaning
None	Not sent.
Pending	Being sent right now.
Sent	KSeF has taken the invoice for processing and has not decided yet.
Accepted	KSeF accepted it and assigned a number, shown in the card. Check the note about the environment.
Rejected	KSeF refused it. Reason for failure shows why.
Error	The attempt did not go through. Reason for failure shows why.

• the Mode, for an invoice issued in offline mode, and the KSeF sending deadline;
• the actions that fit the current state: Send to KSeF (production) or Send to KSeF (demo), Refresh KSeF status, Download UPO, Fix and send as technical correction or Assign a new number. The UPO is KSeF's official confirmation of receipt.

Instead of the card, the invoice can show a note: KSeF is disabled for this entity, the buyer is an individual, or the system will not send this invoice.

Common tasks

Connect with a certificate: the manual method

Before you start

You need the Finance: KSeF configuration permission, and a KSeF certificate with its private key and key password, generated in the KSeF Taxpayer App. The Authentication step explains how.

1. Go to Finance → Sales entities, open the entity and click Configure KSeF integration.
2. On Environment, choose Demo (pre-production) to try things out, or Production to file for real. Click Next.
3. Answer the Configurator and click Next, or click Skip configurator.
4. On Method, click Use this method or I want to choose another method.
5. On Authentication, choose Manual method.
6. Under Certificate (.crt/.pem), click Choose certificate. Under Private key (.key), click Choose key. Each file may be up to 1 MB.
7. Type the Key passphrase. It is required.
8. Click Upload certificate. The entity is now connected.
9. Click Test connection. On success you see Connection works with the environment, the certificate and its expiry date.
10. Click Finish.

If you uploaded the wrong files, click Remove certificate on the same step. It deletes them and disconnects the entity again.

Connect automatically: with a Trusted Profile

The automatic method is in beta. Try it on the demo environment first. Instead of uploading a certificate, you sign a file, and Complaia obtains and stores the certificate for you.

1. Open the wizard, choose the environment and go to Authentication. Choose Automatic method.
2. Click Download XML file. A file is saved to your computer.
3. Click Sign at gov.pl. Upload that file there, sign it with your Trusted Profile and download the signed version.
4. Back in the wizard, click Choose the signed file (or drag the file in) and click Finish and connect. On success the wizard moves to Summary.

Do steps 2 to 4 without a long break, because the downloaded file expires. If the connection fails, click Try again to start over with a new file, or Switch to the manual method.

Test the connection

Test connection, on the Authentication step, signs in to KSeF with the stored certificate without sending any invoice. It is available once a certificate is uploaded.

Get the Offline certificate

You need this only if you want to issue invoices in offline mode.

1. Open the wizard of the connected entity and go to Summary.
2. In KSeF Offline certificate, click Get from KSeF. KSeF processes the request. This can take a few minutes.
3. If the request is still pending, click Check the request later.

Alternatively, click Upload certificate and upload an Offline certificate and its private key downloaded from the KSeF Taxpayer App.

The section shows whether the certificate is valid and until when. Remove certificate deletes it from Complaia only. It stays valid in KSeF.

Send an invoice

While issuing. For a connected entity and a company buyer:

1. Open the draft and click Issue & send to KSeF, or use the same button in the header of the form.
2. Confirm. Complaia issues the invoice and sends it.

What can happen next:

Outcome	What you see	State of the invoice
Accepted	Invoice issued and sent to KSeF.	Issued. KSeF status Accepted.
Taken for processing	A message that KSeF accepted the invoice for processing and the number is not assigned yet.	Issued. KSeF status Sent. Refresh the status in a moment. Do not send it again.
Rejected, or refused by the pre-check	A message that KSeF rejected the invoice, and that it is a draft again and its number was released.	Back to Draft. Fix the data and issue it again.
A temporary failure	A message that the invoice was issued but sending failed.	Issued. Send it from the invoice page. Complaia does not retry on its own.
Not sent by Complaia	A message that the system did not send it to KSeF.	Issued, not sent. See What Complaia does not send.

In offline mode. In the issue dialog, open Other issuing modes and choose Offline24. Confirm with Issue offline. Then send the invoice from its page before the deadline.

From the invoice. On an issued invoice that has not been sent, or whose sending failed:

1. Click Send to KSeF (production) or Send to KSeF (demo).
2. Confirm Send to KSeF?

Check the status and download the confirmation

1. Open the invoice. If the status is Sent, click Refresh KSeF status. Complaia also checks invoices that are waiting for a decision by itself, about every 15 minutes.
2. Once the status is Accepted, click Download UPO. The confirmation is saved as an XML file.

Fix a rejected offline invoice

KSeF sometimes rejects the file of an offline invoice because a field contains characters it does not accept. Such an invoice may already be with the buyer, so it keeps its number and its issue date.

1. Open the invoice and click Fix and send as technical correction.
2. The dialog lists the fields with characters that KSeF does not accept. Click Remove disallowed characters.
3. Click Send technical correction.

A technical correction cannot change the content of the invoice. If the problem is in the content, the dialog says so. Then contact support.

Give the document a new number

If KSeF already has an invoice with the same number from this seller, the document cannot be sent. Click Assign a new number. The document gets the next number in its series and goes back to sending. The old number stays taken for good. If the document has already left the system, Complaia asks you to confirm, because the buyer may have it under the old number.

Move from demo to production

1. Open the wizard of the connected entity. On Summary, click Switch to production.
2. In the dialog Switch to production?, decide whether to tick Also revoke this certificate in KSeF (via API). Then click Switch to production. The demo certificate is removed.
3. Connect with a production certificate, manually or automatically, and test the connection.

Between step 2 and step 3 the entity is not connected, and invoices issued in that time are not sent. Finish the switch without a break.

Invoices accepted on demo are not sent to production afterwards.

Disconnect an entity

1. Open the wizard. On Summary, click Disconnect integration.
2. In the dialog Turn off KSeF?, decide whether to tick Also revoke this certificate in KSeF (via API):
   • A certificate that is not revoked stays active in KSeF. It keeps taking one of a limited number of certificate places.
   • If you leave the box unticked, you agree to revoke the certificate yourself in the KSeF Taxpayer App.
3. Click Turn off KSeF.

After that, the stored certificate is removed, the entity's invoices stop going to KSeF, and the wizard returns to Environment. To connect again, go through the wizard again.

When it doesn't work

What you see	Why	What to do
A message that Complaia connects only entities from Poland	The entity's country is not Poland.	Nothing. KSeF does not apply.
You do not have permission to manage the KSeF certificate.	You can open the wizard but lack Finance: KSeF configuration.	Ask for the permission, or hand the setup to someone who has it.
The upload of the certificate is refused	The file is not a valid certificate, the key cannot be read with the passphrase, or the two files do not belong together.	Check the two files and the passphrase.
Connection test failed	KSeF refused the sign-in. A common cause is a certificate from the other environment.	Check the certificate, the key, the passphrase and the environment.
The authorization file has expired. Download a new XML file and sign it again.	Too much time passed between downloading and uploading the file.	Click Try again and repeat the steps.
The signed file does not match the authentication in progress.	You uploaded a file other than the one just downloaded.	Download the file again and sign exactly that one.
The invoice was not issued, with a list	The pre-check failed. No number was used.	Fix the listed data and issue again.
A message that KSeF rejected the invoice and it is a draft again	KSeF refused the invoice right after issuing.	Fix the data and issue again.
A message that the invoice goes to KSeF but has not been sent yet	You tried to e-mail or download it before sending.	Send it to KSeF first, or issue it in offline mode.
A KSeF submission is already in progress.	You sent the same invoice again, or a send is still running.	Wait, then use Refresh KSeF status.
KSeF request limit	KSeF limits the number of requests per company. Sending and refreshing are paused until the time shown.	Wait for the countdown.
A message that KSeF already has an invoice with this number	The number is taken in KSeF.	Click Assign a new number.
Offline24 is not offered, or a message about the Offline certificate	The entity has no valid Offline certificate for its environment.	Get the Offline certificate.
The invoice was accepted by production KSeF, so it is legally in circulation…	You tried to revert or delete an accepted invoice.	Issue a correction.
An invoice sent to KSeF cannot be cancelled. Issue a correction, for example to zero.	You tried to cancel a document in KSeF.	Correct it to zero.
A correction is refused because the corrected invoice is not in KSeF	The corrected invoice was not sent, was rejected, is waiting for a decision, or is an offline invoice without a KSeF number yet.	Send the corrected invoice first and wait until KSeF accepts it.
UPO is available only after KSeF accepts the invoice.	The status is not Accepted yet.	Refresh the status first.
There is no KSeF card on the invoice	The buyer is an individual, the document is a pro forma, an OSS document or a draft, or the seller is not a Polish entity.	Nothing to fix.
My accountant says nothing was filed, yet the invoice is Accepted	It was accepted on the demo environment.	Move to production, then issue the invoice again on production, or correct it.

Permissions

To do this	You need
Send an invoice, refresh its status, download the UPO, send a technical correction	Finance: KSeF
Open the entity and the KSeF wizard	Finance: settings
Upload, test, remove or revoke a certificate; use the automatic method; manage the Offline certificate; switch environment; disconnect	Finance: KSeF configuration
Give a document a new number	Finance: issue invoices

The built-in Accountant role has Finance: KSeF and Finance: settings, but not Finance: KSeF configuration. Someone with that permission has to connect the entity.

Related

• Sales entities — the entity's country, tax number and other settings
• Invoicing — issuing, reverting to draft and the consumer series
• Corrections & cancellation — the only way to change an invoice KSeF has accepted
• VAT on invoices — rates, codes and the exemption basis
• OSS returns — why OSS documents do not go to KSeF
• Glossary — the short definition