Skip to content

Connect to KSeF

This guide describes how to connect an organisation in xTool to KSeF (Krajowy System e-Faktur), the Polish National e-Invoicing System.

After the connection is active, xTool can send structured invoices in KSeF FA(3) format and receive inbound invoices from KSeF.

What you need

  • Access to the xTool web app and the organisation you want to connect.
  • Permission to manage integrations. Viewing the page requires read integrations. Sending documents to KSeF is a separate permission, held by Member and Administrator but not by Viewer. See Organisation and users.
  • The company’s NIP (10 digits).
  • A KSeF authentication certificate (type 1) issued for that NIP:
  • private key file in PEM form (.key or .pem, the file starts with -----BEGIN)
  • certificate file (.crt or .pem, PEM or DER)
  • the key password, if the private key is encrypted (KSeF sets one when you generate the certificate; leave the field empty for an unencrypted key)

xTool does not use KSeF tokens. Only a type 1 authentication certificate works. An offline (type 2) certificate cannot be used to connect.

Certificate validity

A KSeF certificate is typically valid for two years from the issue date (or from the start date you chose when applying). When it expires, disable the integration and connect again with a new certificate.

Get a KSeF authentication certificate

Issue the certificate in the official Taxpayer Application (Aplikacja Podatnika KSeF 2.0) for the same environment that your xTool instance uses.

xTool environment Taxpayer Application
Production https://ap.ksef.mf.gov.pl
Test https://ap-test.ksef.mf.gov.pl
Demo / pre-production https://ap-demo.ksef.mf.gov.pl

A certificate from test KSeF does not work against production, and the other way around.

Your xTool instance is bound to one KSeF environment, chosen when the instance is deployed. The web app does not show which one — ask Support if you are not sure.

Official background: KSeF certificates.

  1. Open the Taxpayer Application for the matching environment and sign in (Trusted Profile, qualified electronic signature, or qualified electronic seal).
  2. Authenticate in the company NIP context you will use in xTool.
  3. Go to Certificates → Apply for a certificate (Certyfikaty → Wnioskuj o certyfikat).
  4. Enter a certificate name and a password, then click Generate.
  5. Save the downloaded .key file immediately. You cannot download the private key again.
  6. For certificate purpose, choose Authentication in KSeF (Uwierzytelnienie w systemie KSeF). Do not choose the offline / issuer-verification option.
  7. Submit the application, refresh the status, then click Download certificate. Save the .crt file.

Store the .key file, the .crt file, and the password securely. The Ministry of Finance cannot recover a lost private key or password.

The password created in the Taxpayer Application usually must be at least 15 characters and include an uppercase letter, a lowercase letter, a digit, and a special character.

Connect in xTool

Do this once per organisation.

  1. Sign in to xTool and select the organisation.
  2. Open Channels → KSeF.
  3. Click Enable.

  4. Fill in the form:

    Field What to enter
    NIP Company tax identification number, exactly 10 digits
    Private Key File The .key or .pem file from the Taxpayer Application, in PEM form
    Certificate File The .crt or .pem file from the Taxpayer Application
    Key Password Optional. The password you set when generating the certificate. Leave empty if the private key is not encrypted

  5. Click Save.

On success, the page shows the NIP and when the integration was enabled.

If authentication fails, nothing is saved. Check the NIP, certificate type, files, password, and that the certificate belongs to the same KSeF environment as this xTool instance.

After connecting

  • Send from the web app — Create or upload a document in format ksef_fa.invoice.3_0.xml. Open it under Documents → Outbound and choose Send → Send via KSeF. The action only appears for documents in that format.
  • Send via API — POST /api/v2/documents/{document_id}/send with {"transaction_type": "send.ksef"}. See API reference and Transactions.
  • Send via SFTP — Upload a file with +fa3 in the name, for example 68451+fa3.xml. xTool converts it to KSeF FA(3) and submits it to KSeF automatically; no action in the web app is needed. See Send and receive via SFTP.
  • Receive — xTool imports inbound KSeF invoices for connected organisations twice a day. They appear under Documents → Inbound as receive.ksef.
  • Status — If the KSeF page shows KSeF authentication failed, the certificate has usually expired or been revoked. Disable the integration and connect again with a valid certificate.

The PDF preview in xTool is for display only. It is not the official KSeF visualisation. Download the official PDF from the Taxpayer Application if you need it.

Disconnect

You can remove the KSeF connection at any time.

  1. Open Channels → KSeF.
  2. Click Disable and confirm.

Sending and receiving via KSeF stop for this organisation. Documents already in xTool are not deleted.

To connect again, you must upload the certificate files once more.

Common problems

Situation What it means What to do
KSeF authentication failed KSeF rejected the certificate, NIP, or environment. Use a type 1 authentication certificate for this NIP, from the same KSeF environment as xTool. Re-enter the key password.
Failed to load key/certificate The private key cannot be read as PEM, the key and certificate do not belong together, or the password is wrong. Upload the .key and .crt that were generated together; the private key must be in PEM form. Enter the password set in the Taxpayer Application, or leave it empty if the key is not encrypted.
KSeF configuration for organisation … already exists This organisation is already connected. The web app hides Enable in that case, so you only see this error when calling the API. Use Disable first if you need to replace the certificate.
Certificate expired KSeF certificates last about two years. Issue a new type 1 certificate and connect again.
Wrong Taxpayer Application Test, demo, and production certificates are not interchangeable. Generate the certificate in the environment that matches this xTool instance.

Next steps