Sending Invoices
This page covers everything about sending invoices to KSeF, from creating invoices through confirmation, issuing correction invoices, handling foreign currency, offline mode, and what you get after submission
On This Page
Creating an Invoice
Standard Invoicing Workflow
The KSeF module works with invoices you create through Dolibarr's normal invoicing workflow. You don't need to do anything KSeF-specific when creating the invoice - just create it the way you normally would. Common paths to creating an invoice:
From scratch - go to Billing -> Customer Invoices -> New Invoice, select the customer, add line items
From a sales order - open a validated sales order and use the "Create Invoice" button. This carries over the customer, line items, and links the invoice to the order
From a shipment - create an invoice from a completed shipment record
As a recurring/template invoice - set up a template and generate invoices from it
The module hooks into the invoice after creation. Whatever method you use, the KSeF workflow is the same once the invoice exists.
KSeF-Specific Fields
The module adds a couple of extra fields to invoices worth reviewing before submission:
Date of Sale - an extrafield added by the module. By default it's auto-populated based on your configured source (linked delivery/order date or invoice date - see Getting Started for details). You can override it manually on any invoice before submission
KSeF exclusion - if the customer is excluded from KSeF submissions, the KSeF button won't appear on their invoices
Bank Account on Invoices
If you send invoices with bank transfer as the payment method and want your bank account details (IBAN) to appear on the invoice, you need to assign a bank account to the invoice. Dolibarr can auto-fill this for you:
1. Go to Banks | Cash and make sure your bank account has the IBAN filled in. SWIFT/BIC and bank name are optional but recommended.
2. On the customer's Third Party card, set a default bank account. This will auto-fill on new invoices for that customer.
3. When creating an invoice with bank transfer payment, verify the Default Bank Account dropdown shows the correct account.
4. If the bank account is set and the payment method is bank transfer, the IBAN will be included in the KSeF XML automatically.
Submitting to KSeF
Once your invoice is ready, you'll see a KSeF action button on the invoice page. Which button you see depends on the invoice's state:
For Draft Invoices: Validate and Upload
If the invoice is still in draft, you'll see "Validate and Upload to KSeF". This validates (finalizes) the invoice in Dolibarr and immediately submits it to KSeF in one step, but you shoul be sure your invoice is correct before doing this.
For Validated Invoices: Upload to KSeF
If the invoice is already validated, you'll see "Upload to KSeF". This submits the validated invoice without changing its Dolibarr status. The button also adapts based on prior submission attempts:
No prior submission - the standard "Upload to KSeF" button
Pending - the button is disabled with a spinner while KSeF is still processing
Failed or Rejected - a yellow "Retry Submission" button appears (with the error in a tooltip), along with a green "Create Offline Invoice" fallback
Offline - a "Submit Online" button appears. If the offline deadline is less than 8 hours away, a countdown badge warns you
Accepted - no submission button. The Modify button is also disabled to prevent changes to a legally submitted invoice
What Happens During Submission
When you click the button:
1. The module builds an FA(3) XML invoice from the Dolibarr data, including all configured optional fields
2. The XML is signed with your token or certificate
3. The signed XML is sent to the KSeF API
4. KSeF returns a reference number and begins processing
5. The module checks for acceptance - this usually takes a few seconds but can take longer during high-traffic periods
After submission, a KSeF tab appears on the invoice showing the submission history.
Backdated Invoice Detection
If you submit an invoice with a date before today (common when creating invoices retroactively), the module detects this and shows a confirmation dialog. The dialog explains the invoice is backdated, how many days behind the current date it is, and the deadline by which it must be submitted online.
You can cancel or proceed with creating an offline invoice. During "Validate and Upload", the invoice is validated first, then the backdating dialog appears.
In general, invoices cannot be backdated with KSeF, and it's better to adjust the Date of Sale while issuing the invoice on the current date.
When Submission Fails
If a submission fails - connection error, KSeF rejection, or timeout - the module shows a failure dialog with the error details and three options: Close, Try Again, or Create Offline Invoice (fall back to offline mode with certificate signing). The offline option shows the best estimate of the deadline by which the invoice must eventually be submitted online (although it cannot guarantee accuracy in all possible cases).
During "Validate and Upload", the module validates the invoice first before attempting submission - so even if submission fails, you don't lose the validation. The failure dialog appears on the already-validated invoice.
If the offline certificate isn't configured and you try to create an offline invoice, the module tells you which components are missing (certificate file, private key, or password) with a link to the settings page.
Invoice Statuses
After submitting, the invoice gets a KSeF status:
Accepted - KSeF has assigned a KSeF number to the invoice. This is the final, successful state. The invoice is in the national system and legally valid. The KSeF number appears on the invoice page and is clickable - it links directly to the invoice on the KSeF verification portal.
Pending - submitted but KSeF hasn't finished processing it yet. Usually brief, but can take longer during peak times. The scheduled job checks automatically, or you can refresh manually.
Timeout - the submission was sent but the response didn't arrive in time. This doesn't necessarily mean the submission failed - KSeF may have accepted it. The module treats timeouts like pending submissions and checks for the result automatically. Don't retry immediately unless you've confirmed on the KSeF portal that the invoice wasn't received.
Rejected / Failed - KSeF did not accept the invoice. Error details are on the KSeF tab. Common causes: XML validation errors, duplicate invoice numbers, authentication issues. The module shows a yellow "Retry Submission" button and a green "Create Offline Invoice" fallback. Submissions can be retried up to 30 times before being marked as permanently failed.
Offline (Waiting for Online Submission) - the invoice was created while KSeF was unavailable (see Offline Invoices below). It's stored locally with a deadline for when it needs to be submitted online.
Correction Invoices
Correction invoices (faktury korygujące) work through Dolibarr's standard credit note workflow. If you issue a credit note against an invoice that was submitted to KSeF, the module automatically associates the correction with the original invoice's KSeF number in the XML. To create a correction:
1. Open the original (already submitted) invoice
2. Use Dolibarr's "Create credit note" function
3. Fill in the correction details
4. Submit the credit note to KSeF using the same KSeF button
The correction XML references the original invoice's KSeF number, linking them in the national system.
On modifying submitted invoices: Once an invoice has been accepted by KSeF, the Modify button is disabled - the submitted version is the legally binding one. For offline invoices that haven't been submitted online yet, the module shows a warning with the offline deadline but still allows modification. For failed submissions, modification is allowed with an informational note. If you need to change an accepted invoice, issue a correction instead.
Foreign Currency Invoices
If you invoice in EUR, USD, or any other foreign currency, KSeF requires an NBP (National Bank of Poland) exchange rate. The module handles this, but there are a few things to know.
Polish tax law requires using the NBP exchange rate from the last working day before the invoice date. The module fetches this from the NBP Web API using the date of invoice. On the invoice page for a foreign currency invoice, you'll see a button to fetch the NBP rate. Click it and the module will:
1. Query the NBP API for the correct rate based on the invoice date
2. Store the rate and the rate date on the invoice
3. Display both on the invoice page
Submission is blocked until the NBP rate is fetched. The KSeF button won't work without it - this prevents submitting with missing exchange rate data, which would cause rejection. Once the NBP rate is fetched, the module also disables Dolibarr's built-in multicurrency rate refresh button on that invoice to prevent accidentally overwriting the NBP rate with a different source.
Rate Application Mode - The NBP rate will usually differ slightly from the rate Dolibarr used when creating the invoice. The "NBP Rate Application Mode" setting (configured in Getting Started) controls which side is preserved - either PLN amounts stay and foreign currency is recalculated, or vice versa.
Prerequisites:
The Multicurrency module must be enabled in Dolibarr
The invoice must have a non-PLN currency set
The customer's currency should be configured on their third party card
Offline Invoices
When KSeF is unavailable (planned maintenance or unexpected outage, or just your internet stopped working), the module can still issue invoices. Instead of sending the invoice to KSeF immediately, the module:
1. Generates the FA(3) XML as usual
2. Signs it with your offline certificate (separate from your authentication token/certificate - see Getting Started)
3. Stores the signed invoice locally
4. Adds a QR II code to the invoice for verification
5. Sets a deadline for when the invoice must be submitted online once KSeF is available again
The invoice gets an "Offline" status and can be used immediately - it's legally valid even before it reaches KSeF, because it's signed with the offline certificate.
Submitting Offline Invoices Online
Once KSeF is back online, offline invoices need to be submitted. You can do this manually by opening the invoice and clicking "Submit Online", or the scheduled job handles it automatically (see Automation & Extra Features).
The "Submit Online" button shows a countdown badge when the deadline is less than 8 hours away. If the deadline has passed, the button is replaced with a red "Deadline Passed" indicator - at that point you'll need to create a new invoice or a technical correction.
The submission uses the original signed XML, preserving the hash. The module doesn't regenerate or re-timestamp the XML, which would break the signature.
Requirements for offline invoices:
An offline signing certificate must be configured in the module settings (separate from the authentication certificate)
The offline certificate must be valid (check the expiry date on the About page)
Offline submission deadlines vary. The module defaults to calculating the next working day as the submission deadline, but the actual deadline depends on the type of outage (planned maintenance, ordinary outage, or user-side issue). The module handles this based on the information available, but always check official guidance from the Ministry of Finance just in case.
After Acceptance
Once KSeF accepts an invoice, several things become available:
KSeF Number - The invoice gets a unique KSeF number (e.g. 1234567890-20260330-ABCDEF123456-78). This appears on the invoice page and is clickable - it opens the invoice on the KSeF verification portal.
KSeF-Style PDF - A PDF that matches the visual style of invoices as shown in the KSeF application. This is generated automatically after successful submission or offline creation, so you usually don't need to do anything. A "Generate KSeF PDF" button on the invoice page lets you regenerate it if needed. The PDF uses your company logo (from Home → Setup → Company/Organization) and respects the logo height setting from Setup → PDF. It includes the appropriate QR codes: a standard verification QR for online invoices, or dual QR codes (OFFLINE + CERTYFIKAT) for offline invoices.
QR Codes on Standard PDFs - If you have "Add QR code to PDF" enabled in the module settings, your regular Dolibarr invoice PDFs will also include a KSeF verification QR code and the KSeF number after acceptance. Your standard printable invoices automatically show the KSeF verification information without needing the separate KSeF-style PDF.
XML and UPO Downloads - From the KSeF tab on any submitted invoice, you can download:
- The submitted XML - the actual FA(3) XML that was sent to KSeF
- UPO (Urzędowe Poświadczenie Odbioru) - the official receipt of submission from KSeF
Customer Exclusions
Some customers shouldn't have their invoices sent to KSeF - generic B2C customers without NIP and other cases. You can exclude customers in two ways:
From the module settings - add customers to the exclusion list in the KSEF Configuration page
From the third party card - use the KSeF exclusion field directly on the customer's record
When a customer is excluded, the KSeF button simply doesn't appear on their invoices. The invoices are created and managed normally in Dolibarr - they just skip the KSeF step.
Advance Payment Invoices
The module handles advance payment invoices (faktury zaliczkowe) by treating them as deposit invoices in Dolibarr. These are submitted to KSeF the same way as standard invoices - the FA(3) XML builder includes the appropriate advance payment fields and type markers.
Checking Submission Status
Three places to monitor your KSeF submissions:
KSeF Tab on Individual Invoices - Every submitted invoice has a KSeF tab showing the full submission history - each attempt with its timestamp, status, environment (Test/Demo/Production), KSeF number, attempt count, and error details. You can also download the submitted XML and UPO directly from this tab.
Submissions Status - Shows the history of all invoices which have been uploaded. You can download the submitted XML and UPO directly here as well.
KSeF Page (Click the KSeF header of the module) - shows recent submissions across all invoices both incoming and outgoing.
Tips and Common Issues
2026 is a transitional year. Penalties for KSeF non-compliance don't apply yet, so this is the time to test, get comfortable, and work out any issues with your workflow.
Test before going live! Send a few invoices in Test or Demo and verify the XML output, the KSeF-style PDF, and the QR codes all look correct before switching to Production.
Check the KSeF tab after submission if the KSeF number and "Accepted" Status don't appear for more details.
Correction invoices or deleting and re-sending invoices in test/demo. Invoice numbers persist between sessions in test and demo environments on the KSeF side. If you get Error 440 (duplicate invoice number), that number was already used in a previous session. Change it and try again. It's not a good practice to delete invoices in production after submission so it's unlikely to happen here.