Integrations Overview
Mutero provides pre-built connectors for popular accounting software and flexible REST API keys for custom POS — all wired to ZIMRA FDMS fiscalisation.
Setting this up yourself?
Automatic ZIMRA Writebacks
Cloud vs Desktop connectors
127.0.0.1:18989. Each setup guide explains where to find credentials and how to configure ZIMRA tax rates.Real-time sync vs polling
Shared FDMS preflight (all integrations)
buyerData (name + TIN). Complete Tax Mapping before go-live.How to issue credit notes
Tax Mapping — what it is and how to verify
What it does: each invoice line from Zoho, Xero, QuickBooks, Sage Business Cloud, Odoo, Pastel, or Evolution carries a tax name (e.g. OUTPUT2, Standard Rate). Tax Mapping is the lookup table that translates that name into a ZIMRA tax ID (standard / zero-rated / exempt), plus an optional default HS code for zero-rated and exempt lines.
Why set it: ZIMRA requires an explicit tax ID on every line. If Mutero cannot resolve the name, the document is blocked — it never silently becomes 15% VAT.
How to verify: after connecting, open Tax Mapping and pick your integration from the dropdown. You should see seeded defaults (cloud apps) or the rows you added. Xero also runs an automatic setup check after connect: you need a ~15% sales tax rate in Xero mapped to ZIMRA Standard, or the Hub shows Setup incomplete and blocks Sync until you fix rates / mappings and recheck. Then create a test invoice in the source app, run Sync Now (or wait for auto-fiscalize), and check Sync Logs. Success = tax resolved. Cancelled / BLOCKED with a tax message = add the exact tax name under that integration.
What to set up in each app (defaults vs ZIMRA)
Source apps ship with region-specific defaults. Those names and rates often do not match Zimbabwe VAT (15% / zero-rated / exempt). Use the table below: create or fix rates in the source app, then map the exact name in Mutero Tax Mapping.
| Integration | Where to set taxes | Typical defaults (often wrong for ZIMRA) | What you should create / use | Map in Mutero |
|---|---|---|---|---|
| Xero | Xero → Settings → Tax rates | Locked system rates are often all 0%: Tax on Sales, Tax Exempt, Tax on Purchases, Sales Tax on Imports. Do not treat “Tax on Sales” at 0% as ZIMRA 15% VAT. | + New Tax Rate for sales: e.g. VAT on Sales at 15% (apply to revenue). Optionally Zero Rated and keep Tax Exempt at 0% for exempt sales. Mutero blocks Sync until a ~15% sales rate is mapped to Standard. | Tax Mapping → Xero. Seeds include OUTPUT2, VAT on Sales, 15%, Tax on Sales, Zero Rated, Exempt, Tax Exempt (add exact custom names). Then Recheck tax in Configure. |
| Zoho Books | Zoho Books → Settings → Taxes (or Taxes & Compliance) | Org-dependent. Many orgs use Standard Rate / VAT labels; rates may not be 15% if the company is not set up for Zimbabwe VAT. | Ensure sales taxes exist at 15%, 0% zero-rated, and exempt. Prefer clear names such as Standard Rate (15%), Zero Rated, Exempt. | Tax Mapping → Zoho Books. Seeds: Standard Rate, VAT (15%), 15%, Zero Rated, Exempt, Out of Scope, etc. |
| QuickBooks Online | QBO → Taxes (or Settings → Sales tax) | US-style TAX / NON codes are common; rates may be local sales tax, not 15% VAT. | Create or rename sales tax codes so taxable sales are clearly 15%, plus zero-rated / exempt (0%) as needed. Use those codes on invoice lines. | Tax Mapping → QuickBooks Online. Seeds: TAX, TAXABLE, VAT, 15%, Standard, NON, Exempt, Zero Rated, 0%. |
| QuickBooks Desktop | QBD → Lists → Item List / Sales Tax Code List (and tax items as set up for your company) | Often Tax / Non / Taxable style codes; percentage depends on company file. | Use codes whose names you will map; ensure taxable sales behave as 15% VAT for Zimbabwe. Prefer names like Tax, VAT, 15%, Zero Rated, Exempt. | Tax Mapping → QuickBooks Desktop, then Desktop → Sync tax mappings. Seeds: Tax, Taxable, VAT, 15%, Non, Exempt, Zero Rated. |
| Odoo Cloud / Desktop | Odoo → Configuration → Taxes (Sales scope) + Settings: Fiscal Country Zimbabwe, Default Sales Tax 15% | Chart pack defaults (often US labels). Empty Sale tax picker = no active Sales taxes yet. | Create Sales taxes: 15%, Zero Rated, Exempt. Never set Exempt as the company default. See Odoo Cloud settings. | Tax Mapping → Odoo Cloud (or Desktop → Odoo + Sync tax mappings). Seeds: 15%, VAT 15%, Zero Rated, Exempt. |
| Sage Pastel Partner | Pastel tax / VAT setup for the company (codes on inventory and documents) | Often numeric or letter codes (1, 2, 0, S, Z, E) depending on how the company was set up. | Confirm which Pastel tax codes mean 15% / zero / exempt on sales documents, then use those consistently on posted invoices. | Tax Mapping → Sage Pastel, then Desktop sync. Seeds: 1, 15, 15%, VAT, S → Standard; 0, 2, Z → Zero; 3, E, Exempt → Exempt. |
| Excel / Desktop template | Column tax_code on each line in the Mutero template | Empty tax_code defaults to 15% (template contract only). | Use known labels: 15%, 0% / zero rated, exempt. Unknown non-empty values are blocked. | Usually no Tax Mapping row needed if you use known labels. Optional custom labels → Tax Mapping. |
| Custom POS / API | Your POS / backend payload | N/A — you control the fields you send. | Prefer zimra_tax_id 1 / 2 / 3 (or a known label). Zero-rated / exempt need an 8-digit HS code. | Optional Tax Mapping for your own string labels. See Custom POS docs. |
| Channel type | Checklist |
|---|---|
| Cloud (Xero / Zoho / QBO) | Fix taxes in the accounting app → Connect in Hub → open Tax Mapping → confirm seeded rows + add custom names → set HS defaults on zero-rated / exempt. Xero: Recheck tax until Sync unlocks. |
| Desktop (QBD / Odoo / Pastel) | Fix taxes in the ERP → map names in web Tax Mapping → in Mutero Desktop run Sync tax mappings (or Validate setup). |
Open Tax Mapping — use the Integration dropdown to work on one connector at a time.
Automated Sync
Invoices are automatically queued for ZIMRA signing upon creation or approval.
ZIMRA Writeback
Signed receipt numbers and QR verification links are automatically written back to source invoices.
Tax Mapping Rules
Map custom external tax codes directly to ZIMRA Tax IDs with default HS Code fallbacks.
Supported Platforms
Zoho Books API v3
Cloud Accounting Integration
Connect Zoho Books via OAuth 2.0. Supports multi-region data centers (`zoho.com`, `zoho.eu`, `zoho.in`), automated invoice fiscalization, and timeline comment writebacks with QR verification URLs.
Xero Accounting
Cloud Accounting Integration
Connect Xero via OAuth in the Mutero web dashboard. Syncs AUTHORISED ACCREC invoices and allocated credit notes, prefixes XR- / XR-CN-, auto-fiscalizes with ZIMRA, and writes FRN history notes back to Xero.
QuickBooks Online
Cloud Accounting Integration
Connect QuickBooks Online via Intuit OAuth. Sync invoices and credit memos with QBO- / QBO-CN- stubs and ZIMRA writebacks from the Integrations Hub.
Sage One (Sage Business Cloud)
Cloud Accounting Integration (Sage One / ZA)
Connect Sage One / Sage Business Cloud at accounting.sageone.co.za with username, password, and Company ID (or use auto-discovery). Syncs tax invoices and customer returns with SAZ- / SAZ-CN- stubs.
Odoo Cloud
Cloud Accounting Integration
Connect Odoo Online / Odoo.sh via JSON-RPC. Requires Zimbabwe fiscal country, Sales 15% tax, USD/ZiG, then Sync posted invoices (ODC- stubs, no webhooks).
Custom POS & Public REST API
Developer API Integration
Issue Bearer API keys to fiscalize custom POS receipts, web checkout orders, or ERP backends directly with JSON REST payloads.
Excel & Mutero Desktop
Desktop Background Hub & Integrations Agent
Electron desktop hub with Excel template, bulk CSV/XLSX upload, offline SQLite queue, and ribbon add-in on localhost:18989.
QuickBooks Desktop
Desktop + QuickBooks Web Connector
Sync QBD invoices and credit memos through Mutero Desktop's local agent. Uses QB- / QB-CN- stubs and ZIMRA-compliant credit note rules.
Odoo & Mutero Desktop
Desktop + JSON-RPC poller (LAN / self-hosted)
Connect LAN or self-hosted Odoo from Mutero Desktop Settings. Polls posted invoices and credit notes, queues with OD- stubs, and writes FRN back to Odoo chatter. Prefer Odoo Cloud for Odoo Online.
Sage Pastel Accounting (Partner & Express)
Desktop + Dual 32/64-bit ODBC poller
Mutero Desktop listens to Pastel Partner & Express via ODBC (HistoryHeader / HistoryLines) with support for standard 32-bit Pervasive / Actian Zen drivers and auto-detected DSNs, queues with SP- stubs, auto-fiscalises, and writes FRN back into Pastel.