Open source e-invoicing for Poland's KSeF

How open source e-invoicing for Poland's KSeF works in a self-hosted ERP

A self-hosted ERP connects to KSeF through a controlled integration layer, and the company keeps the invoice record and the evidence of every submission. In practice, Odoo or ERPNext produces the invoice data, a transformation step builds the FA(3) structured invoice, a submission service sends it to the National e-Invoice System and receives the KSeF number, and the ERP stores that number against the original document. DeployOpen plans, implements, documents and tests this chain inside the client's own infrastructure. DeployOpen does not issue certifications or attestations, and it does not decide which mandate applies to a given company. Before any design work, the reader should confirm the KSeF go-live dates for their company category, the current FA(3) technical specification and any changes to authentication methods in the official Ministry of Finance KSeF documentation, since these change over time and must not be taken from a secondary summary.

The integration has three parts that need an owner each. The first is the ERP-side invoice generation, where Odoo's Polish e-invoicing module or an ERPNext configuration must be checked against the FA(3) fields the company actually uses, including VAT rates, corrections and multi-company setups. The second is the connection to KSeF itself, which needs a service identity, a credential store with restricted access and logging of every API call. The third is the reconciliation loop: each KSeF number must be written back to the matching sales invoice, and each incoming invoice must be matched to a purchase record before it is posted. Teams often underestimate that last step. Ask the implementation partner to show how a rejected submission, a timeout and a duplicate submission are each recorded, retried or escalated, and who signs off the outcome.

The decisions that matter most are who holds the credentials, where the XML and the KSeF numbers are archived, and how the ERP is tested before production. Keep the submission logs, the generated FA(3) files and the acknowledgement records in a store the finance team can retrieve independently of the ERP. Confirm the retention period that applies to the company under Polish tax rules with its tax advisor, since that period is not covered here. Plan a test environment with anonymized data and a full run of the submission path before go-live. A written scope should state which document types are covered, which ERP version and module set are in scope, and what evidence DeployOpen will hand over, so that the company's auditors and tax team receive a clear and reproducible record.

Which KSeF obligations the ERP must cover and how to configure each one

This table maps each KSeF obligation to the ERP function that has to deliver it and the Odoo or ERPNext setting that usually covers it. Use it as a design checklist and confirm each row against the official KSeF materials before design is frozen. The US FTC Safeguards Rule and SEC Rule 17a-4 do not apply to Polish companies and are not used as comparison points here.

Requirement	What the ERP function must do	How to configure it in Odoo or ERPNext
Issue FA(3) structured invoices for sales	Generate FA(3) XML from posted sales invoices, validate it before submission, and store the exact XML sent.	Odoo: use the Polish e-invoicing module if it supports FA(3) in your version. ERPNext: map fields in a custom app, with server scripts only on self-hosted benches.
Receive and parse incoming KSeF invoices	Retrieve incoming invoices from KSeF, parse them into purchase documents, and flag parse or match failures for review.	Odoo: schedule the import and map purchase journals. ERPNext: run a scheduled job in a custom app and use Data Import only for backfills, a few thousand records at a time.
Authenticate to the KSeF API	Use the credential types the official KSeF API documentation accepts, store them in a secrets store, rotate them, and limit which service account can submit.	Odoo: confirm where the module stores credentials and restrict access by group. ERPNext: keep keys in site configuration or a vault, not in Server Scripts.
Store the KSeF number on each invoice	Save the KSeF number on the document at submission, make it searchable, and block later edits to it.	Odoo: add a read-only field through a custom module or Studio, which needs the Custom plan. ERPNext: add a custom field on Sales and Purchase Invoice.
Handle schema and date changes under change control	Track FA(3) schema versions and KSeF date changes as formal changes, test each one on a copy, and record approval before release.	Odoo: test on upgraded database copies before production. ERPNext: pin the app version, noting that v15 is supported until the end of 2027 and v16 until the end of 2029.
Confirm obligations, dates and XML rules	Record the source, version and date of each requirement the design relies on.	No KSeF control IDs are cited here. Confirm every row in the official KSeF materials before build starts.

Which self-hosted ERP platforms fit a KSeF integration

Poland's KSeF connection is built on the ERP's invoice data, so the platform choice determines how much XML, authentication and number handling your team must build or buy. The cards below compare the three self-hosted options in scope, and the last card covers platforms that need custom integration.

Odoo Community with a Polish localization

Odoo Community is published under LGPL-3.0, so the core is free to self-host in your own infrastructure. Polish invoicing depends on a localization module, and the Community edition has no vendor-supported KSeF connector that this page can confirm. Check which localization version matches your Odoo release, whether it builds FA(3) structured invoices, and who maintains it after go-live. Plan for your own patching, since the Community edition has no access to the upgrade service.

Odoo Enterprise on-premise

Odoo Enterprise adds features and support on top of the Community core, and its source code is not publicly available. On-premise use requires an Enterprise subscription, and databases are activated with a subscription code. Only the Custom plan can be hosted on-premise, so confirm the plan, the included modules and whether Polish e-invoicing features are part of your subscription. Ask the vendor in writing which Odoo version has documented KSeF support before you commit to a upgrade path.

ERPNext on Docker Compose or bench

ERPNext is licensed under GPL-3.0 and built on the Frappe Framework, which is MIT-licensed. You can run it with Docker Compose from the frappe_docker project or manually with the bench command line tool. Confirm whether a Polish KSeF app exists for your ERPNext major version and whether it is maintained. Note that Frappe's warranty coverage requires a matching Frappe Cloud support plan, and Server Scripts are disabled by default from version 15, which affects custom KSeF logic.

Custom integration for other platforms

Any ERP without a native KSeF connector needs a custom integration layer. That layer generates FA(3) XML from invoice data, manages session authentication, stores the KSeF number returned for each invoice, and reconciles received invoices. Ask the platform owner and any integrator to state, in writing, which KSeF interfaces they have implemented and tested. Budget for ongoing maintenance, because the schema and the interface can change as the national system evolves.

Which Odoo hosting option supports a self-hosted KSeF setup

Odoo Online is Odoo's hosted SaaS option, and it is not a self-hosted route. Odoo's pricing page lists the One App Free and Standard plans as available only on Odoo Online, and neither includes the multi-company, Odoo Studio, external API access or custom module capabilities that a KSeF connector typically depends on. Because the database and application sit in Odoo's cloud, you cannot place a connector service or certificate store in your own infrastructure next to the ERP.

Plan limits: Only the Custom plan includes external API access and custom modules, so Online on a standard plan leaves little room for a KSeF integration.
Hosting control: The vendor runs the environment, so the location of KSeF tokens and the connector runtime is not yours to choose.
Upgrade cadence: SaaS versions are released every two to three months and cannot use extended support, which affects how often a connector must be retested.
Major upgrades: Odoo Online requires major version upgrades every two years, so the connector needs a planned upgrade cycle.

Confirm with Odoo whether the Polish localization and any KSeF connector module are offered on Online for your plan and version before you rely on it.

Handling KSeF numbers in receivables and payables

The KSeF number is the anchor that ties an invoice in the national system to the document in your ERP, so the ERP must store it on the sales or purchase record as a dedicated field, not only in a free-text note. For issued invoices, record the number when the system returns it, then match any later status change, correction or cancellation back to that same record. For received invoices, retrieve each document from KSeF and match it against purchase records using the KSeF number first, then the seller's NIP, invoice number, issue date and gross amount as a secondary check. Without the KSeF number as the primary key, scheduled retrieval jobs will create duplicate supplier bills whenever a job is re-run or an invoice is retried after a timeout. Confirm with your integration partner how the chosen connector behaves on retries before go-live.

Map NIP tax IDs as structured master data on the customer and supplier records, validated for format and checked against the seller or buyer on each document, rather than inferred from names. Keep the seller and buyer NIP separate from any EU VAT number or foreign identifier used for cross-border trade. For corrections and cancellations, decide early whether the ERP creates a linked corrective document that references the original KSeF number or reverses the original in the ledger, and make sure the accounting treatment is agreed with your tax adviser. Store both the KSeF reference and the original XML exactly as issued. The XML is the evidence of what was sent or received, and the reference lets an auditor trace it through the system.

If you migrate historical invoices into ERPNext, the Data Import tool documentation advises importing only a few thousand records at a time, so plan the migration in batches, reconcile each batch against the source, and log the results. In ERPNext, Server Scripts are disabled by default from version 15 and must be enabled with the server_script_enabled setting, and Frappe Cloud public shared benches do not allow them. If KSeF matching or numbering logic is written as a Server Script, record that decision, the version, the hosting model and the owner in your change register, and confirm with your vendor that the chosen hosting plan permits it. The same question applies to any custom logic in Odoo, where you should confirm which edition and plan give you the custom module access you need.

What auditors and tax inspectors ask to see from a KSeF integration

This table maps each piece of evidence an auditor or tax inspector is likely to request from a KSeF integration to what it proves and to the component that produces it. Use it to check that your ERP, connector, logging stack and archive each generate the records you will need. Confirm retention periods with your tax or legal adviser and the official Polish rules, because no retention figure is supplied for this page.

Evidence item	What it proves	Component that produces it
Authenticated submission logs	Each invoice was sent to KSeF by an identified session, with timestamps and the outcome returned by the system	Connector request and response logs, shipped to the logging stack and retained outside the ERP database
KSeF numbers stored against ERP documents	Every issued or received invoice in the ledger links to its official KSeF number, so records can be matched in both directions	ERP document fields populated by the connector, checked by reconciliation reports
Stored FA(3) XML files	The exact structured content that was submitted or received can be reproduced years later	Connector archive or document store, with hashes or immutability controls where the design includes them
Change management records for ERP and connector updates	Changes to invoice logic, tax mapping and the connector were reviewed, tested and approved before go-live	Git history or ticketing system, test sign-off records and release notes from the implementation partner
Access logs for users who issue or view invoices	Only authorized people created, sent, corrected or viewed invoices, and multi-factor authentication was applied	ERP audit trail, identity provider logs and connector credential access records
Backup and restore test records	Invoices and KSeF references can be recovered after a failure, and the restore was tested rather than assumed	Backup tool job reports, restore test results on a separate environment and the date of the last successful test
Test-environment records	Integration was validated against a non-production environment before live submissions, and test data stayed separate from production	Test instance configuration, test invoice sets, defect logs and a record of the environment refresh process

How to roll out a KSeF connector without disrupting billing

This sequence moves a self-hosted ERP from confirmed mandate dates to a tested, cut-over KSeF connector, with each phase closing on a check that billing still runs. Durations depend on scope, so they must be fixed in a written plan before work starts.

Confirm the mandate date for your company category
Your finance lead and DeployOpen's engagement lead confirm which KSeF 2.0 date applies to your company category by checking the official Ministry of Finance and KSeF sources directly, not secondary summaries. The output is a dated written statement of which invoice flows fall in scope, signed off by the client's finance owner. Re-check the date at scope approval, since the timetable is the input every later phase depends on.
Scope the ERP and connector
DeployOpen and your ERP and tax owners map every invoice flow that touches KSeF, including sales, purchase, credit notes, corrections and any mixed-currency or multi-company billing. The team confirms the Odoo edition and version in use, whether the Polish e-invoicing module is available for it, and where custom code or the connector will run. The output is a fixed-scope statement of work listing flows, interfaces, exclusions and acceptance criteria.
Build a neutralized test environment
The team creates a test copy of the production database using Odoo's database duplication, which supports neutralization so that test copies cannot send live data or trigger outgoing actions. Confirm the neutralization steps with the vendor documentation for your exact version and check that the test copy is isolated from production credentials and mail servers. The output is a documented test environment that the client's security team has reviewed and accepted.
Run parallel test submissions
Using the test environment and KSeF's test facilities, the team generates structured invoices for representative cases and compares each result with what the ERP already produced for the same documents. Billing staff keep issuing invoices through the current process in parallel so that no revenue flow depends on the connector yet. The output is a log of test submissions, rejections and fixes, with each defect assigned an owner.
Validate FA(3) output and KSeF number capture
The team checks each generated FA(3) document against the schema and business rules, then confirms that the KSeF number returned on acceptance is stored on the correct receivable or payable record. Incoming invoices are tested the same way, so that the KSeF numbers used in payables matching and receivables reporting are captured and searchable. The output is a signed validation report and a test case list covering rejections, duplicates and retries.
Migrate master data in batches
Customer and supplier records, tax identifiers, company profiles and product tax mappings move from the source systems in small, reconciled batches rather than one bulk load. After each batch, finance compares record counts and sample balances with the source, and corrects mismatches before the next batch starts. The output is a reconciliation pack per batch showing that master data in the ERP matches the agreed source.
Cut over with a documented rollback plan
The team switches live invoicing to the connector during an agreed window, with named approvers, a go or no-go checklist and monitoring of first live submissions. A rollback plan states who reverts the configuration, how invoices issued during the window are reconciled, and the conditions that trigger it. The output is a cut-over record, signed by the client, showing that live invoices are being accepted and that the rollback path was tested.

What tooling alone does not cover in a KSeF project

Installing and connecting an ERP to KSeF is only part of the work. The cards below cover the decisions and controls that stay with the company and its implementation partner, whatever platform and connector are in place.

Tax treatment and master data

The ERP posts what it is told. It does not decide whether a transaction is taxable, which VAT rate applies, or whether a customer's tax ID on file is correct and current. Before go-live, assign owners for tax codes, counterparty NIP data and product classifications, and check how errors in these records flow into FA(3) invoices that are then sent to KSeF.

Connector breakage after upgrades

A KSeF connector depends on the ERP's internal data model and APIs, so a platform upgrade can break it even when the invoice module itself works. Odoo major versions on Odoo Online and Odoo.sh are mandatory every two years, and Odoo 17.0 standard support ended in September 2026. Test the connector on an upgraded copy of the database before every production upgrade.

Security patches end with standard support

Odoo provides security patches only during standard support, which lasts three years after a major release. Once a version leaves standard support, the ERP and any custom KSeF modules on it need a planned move, not a patch. Check the support end date for the running version and schedule connector regression tests alongside each security update.

ERPNext support coverage

Frappe states that warranty coverage applies only when the customer runs a listed version and holds a Frappe Cloud support plan that matches that version. A self-hosted ERPNext instance with a KSeF integration therefore needs its version and support status confirmed before the integration is built. Ask the partner who carries first-line responsibility for KSeF failures.

User identity and MFA

The KSeF integration uses credentials and tokens that must be tied to named users, and users who can issue or cancel invoices need strong authentication. Login policy, MFA enforcement and account removal belong to the identity layer, such as a central directory, not to the ERP's local user table. Confirm which accounts can reach the KSeF credentials and how access is revoked when staff leave.

Retention and archive policy

The ERP and KSeF keep invoices, but how long the company keeps them, where copies sit, and how they are restored during an audit is a company decision. Define the retention period with tax and legal advisers, set who can change archived records, and test restore procedures. Ask the implementation partner to document this policy as part of the handover.

What buyers ask before hiring help for KSeF on a self-hosted ERP

What drives the cost of a KSeF integration on a self-hosted ERP?

Cost is driven mostly by the ERP version, the number of legal entities, invoice volume, whether a built-in module can be used or a custom connector must be written, and the size of the test scope. The main cost components are the fixed-scope fee for planning, build, testing and documentation, agreed in writing before work starts; the ERP licence, which is free for self-hosted ERPNext but requires an Odoo Enterprise subscription for Odoo on-premise use; and your own staff time for master data and sign-off. Build work is one-time, while support retainers, ERP subscriptions and upgrades recur. Ask each quote to separate build, testing, documentation and retainer lines, and to state the ERP version and entity count it assumes.

How long does a KSeF integration take on a self-hosted ERP?

No duration can be stated before the scope is known, so the timeline is set by the fixed scope agreed in writing before work starts. The biggest schedule drivers are the number of entities and document types, how much master data needs cleaning, the availability of test accounts and environments, and whether an ERP upgrade must come first. Odoo's upgrade documentation says an upgraded test database should be tested before production, and on Odoo Online and Odoo.sh major upgrades are mandatory every two years, which can collide with a KSeF project. Ask for milestones tied to those dependencies, and confirm the current KSeF deadlines for your business size with official Polish sources and your tax adviser before fixing a go-live date.

Can our own developers implement KSeF without an implementation partner?

Yes, if the team includes ERP developers who know the invoice data model and a written test plan that covers both issued and received documents. The main risks sit in two places: mapping ERP fields to the required invoice structure, including how KSeF numbers are stored against receivables and payables, and upgrades that break custom code. Custom logic also needs care in ERPNext, where Server Scripts are disabled by default from version 15 and must be enabled with the server_script_enabled setting, so that setting must be planned for in every environment. Teams without a test environment that mirrors production, or without a named owner for tax mapping decisions, are the ones where outside help adds the most value.

What does our company need to provide for the engagement?

Plan to provide access to the ERP test and production environments with the administrator rights the work requires, the KSeF access and credentials your company must hold for the environments in scope (confirm the current authority process with your advisers), and sample invoices covering each document type you issue and receive. Typical inputs to confirm in the scope include:

Master data extracts for customers, suppliers, tax IDs and company entities
Named owners for mapping decisions and user acceptance sign-off
Written input from your tax adviser on VAT treatment and invoice content
Test accounts and a window in which the business can run parallel testing

Ask the partner to list each input in the scope with an owner and a due date, so a missing input does not stall the build.

Does DeployOpen certify that our KSeF setup is compliant?

No. DeployOpen prepares systems, controls and evidence for a compliance assessment, but it does not issue audit reports, attestations or certifications, and it does not decide whether your invoices meet the rules. Your tax adviser, your auditors and the Polish authorities make those determinations. In practice the engagement can cover ERP configuration, test cases with recorded results, change records, runbooks and an evidence file that your advisers can review. Ask the partner to name the evidence items in writing, to say who reviews them, and to confirm that sign-off on compliance stays with your organization and its advisers.

What happens when KSeF specifications change after go-live?

Specification changes are handled through change control. Ongoing support, upgrades and continuous testing are available as retainers, so a change to the KSeF requirements can be handled as a defined piece of work under that arrangement, with mapping updates and a repeat of the affected tests before anything reaches production. The contract should state what counts as a change, the response expectations and the regression test scope. The ERP version matters as well: Odoo standard support runs for three years after a major release, with security patches only during that period, and ERPNext customers must stay on a listed Frappe version to keep vendor warranty coverage.

How DeployOpen scopes, builds and supports a KSeF integration

DeployOpen approaches Open source e-invoicing for Poland's KSeF as a fixed-scope implementation inside your own infrastructure, covering the self-hosted ERP, the KSeF connection and the operating runbooks. We plan, implement, customize, integrate, harden, back up, document and support the open-source platforms involved, so the work stays under your control.

How we scope

Inventory which self-hosted ERP or accounting modules issue and receive invoices, and which entities are in scope.
Confirm your KSeF dates, authentication approach and whether invoices are issued, received or both.
Agree in writing the deliverables, test cases, timelines and responsibilities before any work starts.

How we build

Configure and customize the ERP's Polish e-invoicing module or integration layer against the FA(3) structure.
Map master data such as tax IDs, customer and supplier records and KSeF number handling in receivables and payables.
Test issuing and receiving flows in a non-production copy, with validation and error handling checked before go-live.

How we hand over

Document the configuration, integration points, credentials handling and the KSeF number reconciliation process.
Deliver runbooks for error triage, rejected invoices and change handling when KSeF rules or ERP versions change.
Train your finance and operations staff on daily use and on the evidence to retain for archiving and audit.

How we support

Ongoing support, upgrades and testing are available as a retainer, scoped separately from the implementation.
Plan ERP version upgrades with a tested upgraded copy before production, since the vendor's upgrade path requires it.
Confirm with your counsel or auditor which records you must keep and how DeployOpen's evidence supports that review.