ERPNext Poland E-Invoicing (KSeF FA(2))

Key Features

FA(2) structured invoice XML generated from ERPNext Sales Invoice fields and validated against the official KSeF XSD before submission

Authenticated KSeF clearance session (token/certificate) that submits invoices to the Ministry of Finance gateway and captures the returned reference number

Custom `KSeF Submission` DocType storing request payload, KSeF reference number, processing status, error responses, and the UPO document

UPO (Urzędowe Poświadczenie Odbioru) fetch and storage, with the official confirmation attached back to the originating Sales Invoice

`hooks.py` doc events — Sales Invoice `on_submit` enqueues a non-blocking background clearance job so submission never stalls on gateway latency

Scheduler event that polls pending submissions for UPO, updates status automatically, and applies retry with exponential back-off on transient errors

KSeF Settings single DocType for environment (test/production gateway), credentials, mandate effective date, and parallel/observation-mode toggle

Threshold-based rollout handling: run in observation mode before your turnover threshold triggers, then flip to mandatory clearance on your effective date

Whitelisted server methods (submit-to-KSeF, fetch-UPO, download-official-XML) exposed as invoice buttons and callable over the Frappe REST API

Client scripts that surface clearance status, KSeF number, and UPO availability directly on the Sales Invoice form

Field mapping layer for Polish requirements — NIP, GTU/procedure codes where applicable, VAT rates, and Company/Customer address structure into FA(2)

Role profiles and DocType permissions separating who can authenticate and clear invoices from who can only view submission history

Error and rejection handling that logs the KSeF gateway response, marks the invoice, and prevents silent failure of a legally required submission

Full audit trail linking each Sales Invoice to its submission, reference number, timestamps, and UPO — queryable via report view and REST API

Compatible with Frappe/ERPNext v15 and v16, packaged as a standard installable app for your bench

Built to order, done for you

No DIY setup — a working app, built, installed and supported by ECOSIRE.

You order

Start with a one-time build price. We scope it with you at kickoff.

We build & install

ECOSIRE builds, configures and installs it on your ERPNext.

Go live + support

You go live in about 2–4 weeks, with a post-launch support window.

About this Product

Poland's Krajowy System e-Faktur (KSeF) makes structured B2B e-invoicing mandatory in 2026 — phased from February for large taxpayers and April for everyone else, driven by turnover thresholds. Every B2B invoice must be issued as FA(2) structured XML, submitted to the national KSeF gateway, and is only legally "issued" once the platform returns a UPO (Urzędowe Poświadczenie Odbioru) with an official KSeF reference number. ERPNext core gives you Sales Invoice, tax templates, and print formats, but it has no concept of the FA(2) schema, no clearance session against the Ministry of Finance API, and no place to store the KSeF number or the UPO. Once the mandate is live, a PDF or a plain ERPNext invoice is not a valid invoice in Poland — and that is exactly where native ERPNext runs out of road.

ECOSIRE builds a proper Frappe app (for example erpnext_ksef_pl) that installs cleanly onto your bench and plugs into the ERPNext document lifecycle rather than bolting a script onto the side. We map your Sales Invoice, Customer, Company, and Item tax data onto the FA(2) XML structure, validate it against the official XSD before anything leaves your server, and open an authenticated KSeF session to submit the invoice for clearance. A custom KSeF Submission DocType records the request payload, the returned reference number, the processing status, and the UPO document, so every cleared invoice has a complete, queryable audit trail linked back to its Sales Invoice.

Technically, the integration is wired through hooks.py document events — on_submit of Sales Invoice enqueues a background clearance job, so submitting an invoice is never blocked by network latency to the gateway. A scheduler event polls pending submissions for their UPO and flips status the moment Poland confirms them, with automatic retry and back-off on transient gateway errors. Whitelisted server-side methods expose "submit to KSeF", "fetch UPO", and "download official XML" as buttons on the invoice, and the same methods are reachable over the Frappe REST API for headless or upstream-system use. Threshold-based rollout is handled as configuration: a KSeF Settings single DocType holds your environment (test vs production gateway), authentication token/certificate, effective mandate date, and a toggle to run in parallel/observation mode before your obligation starts — so the same build serves you both before and after your turnover threshold triggers the requirement. Role profiles and permissions restrict who can authenticate to KSeF and who can only view submissions, and client scripts surface clearance status and the KSeF number directly on the invoice form.

Because this is build-to-order, we do not hand you a generic download — we start from a short scoping call, confirm your ERPNext version (v15 or v16), your invoice volume, and your specific FA(2) field mappings, then build and validate against your real chart of accounts and tax setup. Typical delivery is 2-4 weeks from confirmed scope. You receive the installable app source, a UAT pass on a staging bench with a rollback plan, technical documentation, a user guide plus a training session, and a post-go-live support window while your first real invoices clear through KSeF.

What you get

Installable Frappe app source code for your ERPNext version (v15 or v16), built and configured for your instance

Installation and configuration on your environment, including KSeF Settings, credentials wiring, and test-gateway connection

Technical documentation covering DocTypes, hooks, scheduler jobs, whitelisted methods, and the FA(2) field mapping

User guide plus a live training session for your finance/AP team on issuing and confirming KSeF invoices

Post-go-live support window while your first production invoices clear through KSeF

UAT sign-off on a staging bench with a documented rollback plan before touching production

Git repository handover with full commit history and README

Field-mapping and configuration reference tailored to your chart of accounts and tax setup

Who this is for

Finance & Compliance Lead

Owns VAT and statutory reporting for a Polish entity and must have every B2B invoice cleared through KSeF with a valid UPO before the 2026 mandate hits their turnover threshold. Needs a defensible audit trail, not a manual upload workaround.

ERPNext System Administrator

Runs the company's ERPNext v15/v16 bench and wants a clean, installable Frappe app with proper hooks, scheduler jobs, and permissions — not ad-hoc server scripts they'll have to maintain and re-apply after every update.

CFO / Group Controller (multi-entity)

Oversees a Polish subsidiary inside a larger group and needs KSeF compliance handled predictably, with observation mode to validate output before the mandate is enforced and a clear go-live plan across entities.

ERP Implementation Partner

An integrator delivering ERPNext to Polish clients who needs a maintainable KSeF module with source handover and documentation they can support and extend rather than reverse-engineer.

How ERPNext Poland E-Invoicing (KSeF FA(2)) Compares

Criterion	ECOSIRE	Custom Build	Competitor
FA(2) XML generation	Built and validated against the official XSD before submission	Possible, but you own the schema mapping and every future change	Often generic e-invoice XML, not Poland FA(2) specific
KSeF clearance API	Authenticated session with the Ministry of Finance gateway, test and production	You build and maintain the session and auth handling yourself	Varies; may cover only submission, not full lifecycle
UPO confirmation	Polled, stored on the invoice, with reference number and audit trail	Must be designed and built from scratch	Sometimes partial or manual
Threshold-based rollout	Observation mode plus effective-date toggle in KSeF Settings	Whatever you choose to engineer	Rarely configurable per taxpayer
Fit to your ERPNext	Built for your v15/v16 bench and real tax setup	Fully bespoke but slow and costly to reach parity	Generic; may need workarounds to fit your data
Source and ownership	Full app source and git repository handed over	You own it, but you also built all of it	Often closed or license-locked
Delivery time	2-4 weeks from confirmed scope	Months of in-house build and testing	Fast to install, slow to fit your specifics
Support and updates	Post-go-live window plus scoped update work as KSeF evolves	Entirely on your team	Depends on vendor roadmap and pricing

Frequently Asked Questions about ERPNext Poland E-Invoicing (KSeF FA(2))

How long does delivery take?

This is a build-to-order product, not an instant download. After a short scoping call to confirm your ERPNext version, invoice volume, and FA(2) field mappings, typical delivery is 2-4 weeks from confirmed scope. That includes build, validation against your real tax setup, UAT on a staging bench, and go-live.

What happens after go-live — do you provide support and updates?

Yes. Every build includes a post-go-live support window while your first real invoices clear through KSeF. You also receive the full app source and git repository, so nothing is locked to us. As KSeF schema versions or gateway rules evolve, we can scope update work; because you own the code, you or your own team can maintain it too.

Does this work with our ERPNext version?

The app is built as a standard installable Frappe app supporting ERPNext v15 and v16. We confirm your exact version and bench setup during scoping and build/validate against it, so it installs cleanly rather than fighting a version mismatch.

How does it handle Poland's threshold-based phased rollout?

The KSeF Settings DocType carries your mandate effective date and a parallel/observation-mode toggle. Before your turnover threshold triggers the requirement, you can generate and validate FA(2) XML without mandatory clearance; on your effective date you switch to full clearance. The same build serves you both before and after the obligation starts.

Is an invoice really "issued" only after KSeF responds?

Yes — under KSeF an invoice is legally issued when the platform accepts it and returns a UPO with an official reference number. The app enforces this: submission runs on Sales Invoice submit, a scheduler polls for the UPO, and the confirmation plus reference number are stored back on the invoice so you always know an invoice's true clearance status.

Can other systems trigger or read KSeF clearance?

Yes. The submit-to-KSeF, fetch-UPO, and download-official-XML actions are exposed as whitelisted methods reachable over the Frappe REST API, and submission records are queryable. That lets upstream billing systems or headless workflows drive and read clearance without using the ERPNext desk UI.

Will this bypass ERPNext's permission model?

No. The app ships with role profiles and DocType permissions that separate who can authenticate to KSeF and clear invoices from who can only view submission history, so KSeF actions respect your existing ERPNext access controls.