What the KSeF connector does
Poland's Krajowy System e-Faktur (KSeF) is the mandatory national platform through which Polish companies issue and receive VAT invoices electronically. Every VAT invoice issued to a Polish company lands in that company's KSeF inbox before it reaches any accounting system.
The VAT4U KSeF connector authenticates to KSeF on your behalf and:
Fetches all e-invoices received by your company (as the buyer) for a date range you choose
Downloads each invoice in its structured XML format (FA(3) schema)
Stores the raw XML files in your VAT4U buffer
Converts the invoice data into a line-item file ready for the VAT4U import wizard
Lets you review, import, and validate the invoices for VAT recovery — all within VAT4U
The connector fetches only invoices where your company is the buyer (invoices received). It does not fetch outgoing sales invoices, neither does any changes in your KSeF account.
Before you begin — what you need
To activate the KSeF connector you need one thing: a KSEF-compatible certificate in P12/PFX format and its password.
The certificate proves to the KSeF API that you are authorised to access that company's invoice inbox. Without it, KSeF will refuse any connection attempt.
You also need:
Your company's NIP (Polish tax identification number, 10 digits, no country prefix)
Access to the VAT4U Connectors page for your company (Administrator role required)
Step 1 — Obtain a KSEF-compatible certificate
There are three types of certificate accepted by KSeF. We recommend Option A for most companies as it is free and purpose-built for API access.
Option A — Free KSEF Certificate from the Ministry of Finance (recommended)
The Polish Ministry of Finance issues free KSEF Certificates specifically for machine-to-machine API access. They are valid for 2 years and available since November 2025.
How to obtain one:
Log in to the e-Urząd Skarbowy portal at eurzad.podatki.gov.pl using your company's authorised representative (via Profil Zaufany, qualified signature, or e-Dowód).
Navigate to KSeF → Zarządzanie certyfikatami (KSeF → Certificate management).
Click Wystaw certyfikat (Issue certificate) and choose Certyfikat KSeF (Typ 1) for access by a natural person acting on behalf of the company, or Typ 2 for a system/application certificate.
The portal generates the certificate and offers a download in PKCS#12 (.p12) format. You will set a password during this step — keep it safe, you will need it in VAT4U.
Save the
.p12file securely.
Important: KSeF Certificates tie access to a specific NIP. Make sure you request the certificate for the correct company NIP. If your company has multiple Polish entities, you need a separate certificate for each one.
Option B — Qualified Electronic Signature (kwalifikowany podpis elektroniczny)
If your company already has a qualified electronic signature issued by a Polish trust service provider (e.g. Certum, EuroCert, Sigillum, KIR Szafir), you can use the same certificate for KSeF API access.
How to export it as P12:
Qualified signature certificates are usually stored on a USB cryptographic token. To use one with VAT4U you need to export the certificate and private key to a P12 file:
Open your signature management software (e.g. Certum SimplySign, ProCertum CardManager, or the token management app from your provider).
Find the certificate associated with your company.
Use the Export function and select PKCS#12 (.p12 / .pfx) format.
Set a strong password during export — this is what you will enter in VAT4U.
Save the exported
.p12file.
Note: Not all qualified signature providers allow private key export (some tokens are non-exportable by design). If export is blocked, use Option A or C instead.
Option C — Qualified Electronic Seal (pieczęć elektroniczna)
If your company uses a qualified electronic seal (typically issued for automated signing processes), it can also be used with KSeF. The process for obtaining a P12 export is the same as Option B — contact your seal provider for export instructions.
Step 2 — Activate the KSeF connector in VAT4U
In VAT4U, go to your company page and click the Connectors tab.
Find the KSeF card in the connector grid and click it.
Click Activate KSeF integration.
Fill in the connection form:
Field | What to enter |
Company NIP | Your 10-digit Polish NIP (e.g. |
Environment | Choose Production for your live KSeF inbox. Use Test only if you are connecting to the KSeF test environment ( |
P12/PFX Certificate file | Click the file picker and select the |
Certificate password | Enter the password you set when the certificate was created or exported. |
Click Save connection details.
VAT4U immediately runs a connection test. If successful, the status badge changes to Active and a green checkmark appears. If the test fails, double-check your NIP, certificate file, and password.
Security note: Your certificate file and password are stored encrypted in VAT4U's database. The password is never displayed again after saving — if you lose it, upload a new certificate.
Step 3 — Pull invoices on demand
Once the connector is active you can fetch invoices at any time.
On the KSeF connector panel, click Start on-demand extraction.
Enter an extraction name (e.g.
KSEF January 2024). This name appears in the extraction list so you can identify the batch later.Set the date range:
From — the earliest issue date of invoices to fetch
To — the latest issue date
The default range is the previous calendar month.
Click Start extraction.
VAT4U queues the job. It will:
Authenticate to KSeF with your certificate
Query all invoices received in the selected date range
Download each invoice XML from KSeF
Store the XMLs in your VAT4U buffer
Build a line-item CSV from the invoice data
You can monitor the status in the Extraction list table. Refresh the table using the Refresh button. Statuses cycle through: QUEUED → PROCESSING → FINISHED (or FAILED if an error occurred).
Processing time depends on the number of invoices. A few hundred invoices typically complete in 2–5 minutes.
Step 4 — Import invoices into VAT4U
Once an extraction reaches FINISHED status:
Click More in the extraction row → Import to VAT4U.
VAT4U copies the CSV into your import area and opens the Import Wizard pre-configured for KSeF data (line items grouped by invoice number).
In the Import Wizard, review the column mapping. The most important fields are pre-mapped:
Invoice date, invoice number, currency
Supplier name and VAT number
Net amount, VAT amount, gross amount
VAT rate code
Linked XML document path
Adjust any mappings if needed, then click through the wizard to complete the import.
The invoices appear in your VAT4U expense list ready for compliance checks and VAT recovery processing.
You can also click Download CSV to save the raw extraction file for your own records or to import manually at a later time.
Step 5 — Schedule automatic extractions (optional)
Instead of triggering extractions manually each month, you can schedule VAT4U to run them automatically.
Click Schedule periodic extractions on the KSeF connector panel.
Set a name prefix (e.g.
KSEF Auto). The actual extraction name will beKSEF Auto - 01.01.2024 to 31.01.2024.Choose a frequency:
Frequency | When it runs | Date range fetched |
Weekly | On a chosen day each week | Previous 7 days |
Monthly | On a chosen day each month | Previous calendar month |
Quarterly | On a chosen day of the first month of each quarter | Previous calendar quarter |
Set the day of the period on which VAT4U should run the extraction (e.g. day 5 of each month means extractions start on the 5th).
Click Set schedule. The button changes to show the next scheduled run date.
The scheduled extraction runs automatically in the background. You will see it appear in the extraction list once it starts. To cancel the schedule, click the schedule button again → Cancel schedule.
Understanding the extraction table
Column | Meaning |
Id | Internal extraction ID |
Extraction name | The name you gave the extraction (or auto-generated for scheduled runs) |
Date | When the extraction was triggered |
Started by | The VAT4U user who triggered it (or |
Status |
|
Line items | Total number of invoice line rows in the CSV |
Linked imports | Import wizard sessions linked to this extraction (click the edit icon to link or update) |
Parameters | Click the info icon to see the date range used for this extraction |
Troubleshooting
Connection test fails immediately after saving
Double-check that the NIP matches the company registered with KSeF for this certificate
Confirm the password is exactly as set during certificate creation or export
Check the environment — if you have a test certificate, select Test; a production certificate will fail against the test environment and vice versa
Make sure the certificate has not expired (KSEF Certificates are valid for 2 years; qualified signatures vary by provider)
Extraction status stays QUEUED for a long time
Your VAT4U worker queue may be busy. Check Report → Running Jobs for any stuck jobs
Contact your VAT4U administrator
Extraction fails (status: FAILED)
Common causes:
The certificate has expired since the connection was tested — re-upload a new certificate
The KSeF API is temporarily unavailable (check status.ksef.mf.gov.pl if available)
The NIP in the connector config no longer matches the certificate (e.g. after a company restructuring)
If the failure persists, check Report → Running Jobs, find the failed KSEF job, and inspect its error log.
Some invoices are missing from the extraction
KSeF returns invoices by acquisition date (the date KSeF accepted the invoice), not by the invoice issue date. If a supplier issued an invoice on January 31 but KSeF processed it on February 2, it will appear in a February extraction, not January. Expand the date range slightly if you suspect missing invoices near period boundaries.
I do not have a qualified signature or seal
Use Option A (free KSEF Certificate from the Ministry of Finance). It requires only a Profil Zaufany account for the authorised representative — no cryptographic hardware token is needed.
Certificate renewal
KSEF Certificates expire after 2 years. Qualified signature certificates vary by provider (typically 1–3 years).
When your certificate is about to expire:
Obtain a new certificate following the same steps as above
In VAT4U, go to the KSeF connector → Show connection details → Edit
Upload the new
.p12file and enter its passwordClick Save connection details — VAT4U runs a connection test automatically
The old certificate is replaced immediately; in-progress extractions are not affected
Frequently asked questions
Does VAT4U store my invoice XMLs permanently? Yes — the raw FA(3) XML files are stored in your VAT4U buffer and linked to each expense after import. They serve as the original invoice document.
Can I use the same certificate for multiple companies in VAT4U? No. Each KSEF certificate is bound to a specific NIP. If you manage multiple Polish entities, each needs its own certificate and its own KSeF connector activation in VAT4U.
Can I fetch invoices for a period before KSeF became mandatory? The connector only fetches invoices that are in KSeF. Invoices issued before the KSeF mandatory date for your supplier category were not submitted to KSeF and are not available through this connector.
Is the connection secure? Yes. Communication with KSeF uses TLS 1.2+. Your certificate password is encrypted in VAT4U's database and never transmitted in plain text. The certificate private key never leaves your server after upload.
What happens to the extracted data if I deactivate the connector? Previously extracted invoices and their imports remain in VAT4U untouched. Deactivating the connector only removes the stored credentials — no data is deleted.
The KSeF API is returning errors I don't understand KSeF error codes are documented by the Polish Ministry of Finance at the official KSeF developer portal. The raw error message is logged in VAT4U's Running Jobs report for the failed extraction.