Finance teams invoicing in Zambia face a hard constraint that ERPNext core does not know about: an invoice is not legally an invoice until the Zambia Revenue Authority's Smart Invoice service has fiscalised it and returned a fiscal reference. Out of the box, ERPNext will happily submit a Sales Invoice, post the GL entries and email a PDF that carries no fiscal number, no verification QR code and no proof of transmission. The usual workaround — keying the same invoice a second time into the ZRA-supplied client, then hand-copying the fiscal number back into a custom field — is where the damage happens: transposed figures, invoices posted in ERPNext but never fiscalised, credit notes that reference nothing, and a month-end reconciliation done in a spreadsheet because the two systems disagree.

We build a proper Frappe app — its own repository, its own module, installed on your bench alongside erpnext — rather than a pile of loose Server Scripts and Custom Fields that vanish on the next migration. A Smart Invoice Settings single DocType holds the environment (sandbox or production), endpoint, TPIN, branch ID, device serial and credentials, with secrets stored as Password fieldtypes so they never render in the UI or in an API response. Company- and item-level mapping DocTypes translate your ERPNext master data into ZRA's coded vocabulary: Item Tax Template and Item Group map to Smart Invoice tax categories and product classification codes, UOMs map to ZRA unit codes, and Customer records carry TPIN and buyer type. A Smart Invoice Log DocType holds one row per transmission — request payload, response payload, HTTP status, fiscal reference, signature and QR string — so every submission is reconstructable months later without opening a network trace.

Transmission is wired through hooks.py doc events on Sales Invoice. A before_submit validator refuses to submit a document that cannot be fiscalised (missing customer TPIN, an item with no classification code, a tax template with no ZRA category), so the failure surfaces at the point of entry rather than at the tax office. on_submit enqueues the fiscalisation job through frappe.enqueue on a dedicated queue, keeping the UI responsive and the database transaction safe when ZRA is slow. The returned fiscal reference, verification URL, QR payload and device signature are written back to read-only custom fields on the Sales Invoice and rendered into a compliant Print Format, so the human-readable document your customer receives and the machine format ZRA holds come from one posting and cannot drift. Credit Notes travel the same path as refund transactions carrying the original fiscal reference.

Rejections are first class. A rejected transmission moves its log to a Failed state with the ZRA error code decoded into plain English, raises a ToDo for the finance role, and exposes a correction-and-resend action that re-validates before re-transmitting — nobody quietly edits a submitted invoice. A scheduler event defined in hooks.py retries transient network failures with backoff and produces a daily reconciliation report of submitted ERPNext invoices against fiscalised logs, so a gap is visible the next morning rather than at audit. Whitelisted methods expose the same fiscalise and status-check operations over the Frappe REST API for POS or e-commerce front ends, a Client Script surfaces live status and the QR code on the invoice form, and permissions ship as a role profile — a Smart Invoice Manager who can edit settings and mappings, and a Smart Invoice User who can transmit and view logs but never see credentials.

This is build-to-order. It is not an existing Frappe Cloud Marketplace download you install this afternoon. We start with a scoping call to see your actual ERPNext configuration — version, tax templates, item catalogue, whether POS is in play, how many branches and devices you operate — and to confirm which ZRA Smart Invoice interface you are onboarded to. From confirmed scope, typical delivery is one working week: we build against a copy of your data, hand you a staging site for UAT, run the acceptance cases with your finance team, and only then install on production with a rollback plan in hand. You receive the source code and the git repository, so the app is yours to keep whether or not you continue with us. It is written and tested for Frappe/ERPNext v15 and v16 and delivered against your exact site version.