Zw Compliance
A Frappe|ERPNext compliance app for Zimbabwean businesses
- Author: DonnC
- Repository: https://github.com/DonnC/zw_compliance
- GitHub stars: 4
- Forks: 1
- License: MIT
- Category: Localization
- Maintenance: Actively Maintained
- Frappe versions: develop
Install Zw Compliance
bench get-app https://github.com/DonnC/zw_compliance
Tags
- compliance
- erp
- erpnext
- fiscal
- frappe
- zimra
Add the Frappe Gems badge to your README
Maintain Zw Compliance? Paste this into your README:
[](https://frappegems.com/gems/apps/DonnC/zw_compliance)
About Zw Compliance
Zimbabwe Compliance for ERPNext
accept it?"} B -- "no: reason shown" --> A B -- yes --> C["Number · chain · sign · QR
(same DB transaction)"] C --> D["Fiscal Receipt: Queued
printable immediately"] D -- "after commit, strictly in order" --> E[("ZIMRA FDMS")] E --> F["Submitted · FDMS signature verified"] D -. "offline: waits, retries,
never skips or reorders" .-> E ``` The ZIMRA protocol itself lives in `zw_compliance/fdms`, a pure Python library with no Frappe dependency, tested against the specification's own examples. The Frappe layer (`zw_compliance/fiscalisation`) maps ERPNext documents onto it. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). Online first, offline safe: while ZIMRA is reachable a receipt is accepted within seconds of submit. When it is not, invoicing carries on. Receipts are already signed and printable, and they queue until the connection returns. Because order is enforced, the queue drains without gaps or duplicates (§4.7). ## Screenshots What ZIMRA requires on paper (§10), produced from ERPNext: | A4 fiscal tax invoice | 80 mm receipt (Receipt48) | Z report | |:---:|:---:|:---:| |
|
|
|
And what the business sees in ERPNext, starting with the workspace:

**Fiscal Receipt Register**: every receipt with its ZIMRA status |

**Fiscalisation Reconciliation**: each invoice against its receipt | |

**VAT Summary**: output against input VAT, per tax and currency |

**Fiscal Day Summary**: totals per day, tax and currency | |

**Fiscal device**: guided set-up and live status |

**Tax mapping**: ZIMRA taxes tied to ERPNext accounts and templates | All screenshots use the [demo data](#see-it-with-demo-data). ## See it with demo data No ZIMRA connection needed: the demo replays three weeks of trading through the real flow (invoices, credit notes, ZWG sales, daily Z reports, and a dropped connection today) against the built-in FDMS simulator. It lives in its own company and is removed with one command. ```bash bench --site execute zw_compliance.fiscalisation.demo.seed # ZW Demo Traders bench --site execute zw_compliance.fiscalisation.demo.wipe # removes all of it ``` Then switch to the company *ZW Demo Traders* (avatar menu → **Session Defaults**) and open the **ZIMRA Fiscalisation** workspace. ## Install Requires ERPNext v15 or later. ```bash bench get-app https://github.com/DonnC/zw_compliance bench --site install-app zw_compliance ``` Install and every `bench migrate` are idempotent. They create: - the roles *ZIMRA Manager* and *ZIMRA User*; - the custom fields (all owned by the app and removed on uninstall); - the default settings; - the ZIMRA HS code list. ## Set up a fiscal device (10 minutes) You need the device ID, serial number and activation key that ZIMRA issued for the device (from the ZIMRA self-service portal). 1. **Zimra Settings**: check the allowed currencies (default `USD,ZWG`) and map any non-obvious Mode of Payment to a ZIMRA money type. 2. **Zimra Fiscal Device → New**: company, environment (*Test* first), device ID, serial number, model. Tick *Default Device for Company*, or list the POS Profiles that use it. Save. 3. Enter the **activation key** and press **Verify Taxpayer**. ZIMRA returns the taxpayer and branch it has on record. Confirm it is you. 4. Press **Register Device**. The certificate is issued, the configuration is pulled, and taxes are provisioned. The device turns **Active**. 5. Give each item an **HS code** (or set one on the item group). Zero-rated and exempt items get the Item Tax Template the app created. That's it. Submit a Sales Invoice and the *ZIMRA Fiscalisation* section on it fills in, with Status *Submitted* a moment later. Moving from another fiscal system? Enter its last receipt global number in *Last Receipt Global No of Previous Software* before registering, so numbering continues. Full walkthrough, end of day and troubleshooting by error code: [docs/USER_GUIDE.md](docs/USER_GUIDE.md). ## Daily use | Who | What | |---|---| | Cashier, accounts | Nothing new: submit invoices as usual, print with *ZIMRA Receipt48* or *ZIMRA Invoice A4*. For returns use **Create → Return / Credit Note** and give a reason. | | ZIMRA Manager | Glance at the workspace: *Awaiting Submission*, *Rejected*, *Flagged*. Days close on schedule; use **Close Fiscal Day** to close early. Read the Z report. | | Accountant | VAT Summary for the return; Fiscalisation Reconciliation before filing. | ## Remote API Web shops, mobile apps and external tills can fiscalise through a small, uniform JSON API. Every response is either `{"ok": true, "data": …}` or `{"ok": false, "error": {"code", "message", "zimra_code"?}}`. Every write is idempotent through a `client_reference`. ```http POST /api/method/zw_compliance.api.v1.fiscalisation.fiscalise_invoice Authorization: token : {"client_reference": "WEB-10031", "customer": "Walk-in", "items": [{"item_code": "SKU-1", "qty": 2}]} ``` Endpoints: `fiscalise_invoice`, `create_credit_note`, `get_receipt
Related Localization apps for Frappe & ERPNext
- Wiki — Free and Open Source Wiki built on top of Frappe
- India Compliance — Simple, yet powerful compliance solutions for Indian businesses
- Nepal Compliance — Open source ERP for Nepal with HR, Payroll & Accounting compliance, based on ERPNext by Frappe Technologies.
- Kamra Pms — World's first open-source, agentic AI-ready PMS. Free hotel and short-term rental PMS (AGPL): front desk, folios, POS, housekeeping, booking engine, plus governed MCP so Claude can run the property. Built on Frappe v16.
- Erpnextswiss — ERPNext application for Switzerland-specific use cases
- Erpnext Germany — ERPNext customizations for German companies
- Ksa Compliance — KSA Compliance App for KSA E-invoice
- Zatca Erpgulf — Implementation of Zatca Phase-2 E-Invoicing - for FrappeCLoud