MuteroDocs

Odoo & Mutero Desktop

Connect LAN or self-hosted Odoo Accounting to Mutero Desktop — find credentials, configure ZIMRA tax rates, validate the installation, and fiscalise posted invoices and credit notes with OD- numbering and chatter writeback. For Odoo Online / Odoo.sh, prefer the Odoo Cloud Hub connector.

Prefer Odoo Cloud for Odoo Online
If your database is on Odoo Online or Odoo.sh and reachable over the public internet, use the Odoo Cloud guide (Integrations Hub, ODC- stubs). Use this Desktop guide when Odoo is only reachable on a private LAN / VPN from the Windows PC.
Local agent — credentials stay on this PC
Mutero Desktop runs a local HTTP agent at http://127.0.0.1:18989. Odoo URL, database, username, and API key are stored encrypted on the Windows PC only. Mutero Cloud never receives your Odoo password or API key. Keep Mutero running (window or system tray) whenever you use Odoo with Mutero.

1Environments: Odoo Online (cloud) vs self-hosted (local)

Mutero talks to Odoo over JSON-RPC (/jsonrpc). The same Desktop connector works for both deployment types — only the URL and how you find the database name differ.

Odoo Online / Odoo.sh (cloud)

  • URL looks like https://mycompany.odoo.com (or your custom domain on Odoo.sh).
  • Database name is usually the subdomain (e.g. mycompany) — confirm on the database selector / login page.
  • Requires HTTPS reachable from the PC running Mutero Desktop.

Self-hosted / on-premise

  • URL is your server base, e.g. https://odoo.internal.local or http://192.168.1.50:8069.
  • Database name is the PostgreSQL database you select at login (often shown in the Manage Databases screen).
  • Mutero Desktop must reach that host from the same network (no cloud tunnel required).
Not the same as Mutero Cloud vs Desktop
Odoo itself may be cloud or local. Mutero's Desktop connector always runs on the PC (local agent) for LAN-only / on-premise Odoo. Prefer Odoo Cloud in the web Integrations Hub when your database is reachable over HTTPS (Odoo Online / Odoo.sh).

2Choose your starting path

Path A — Mutero Desktop is already installed

  1. Skip the download section below.
  2. Sign in (if needed) → select your VFD → open a fiscal day.
  3. Jump to Where to find Odoo credentials, then Connect Odoo, Tax rates, and Validate setup.

Path B — First-time Mutero Desktop install

  1. Download and install Mutero Desktop (next section).
  2. Sign in with browser and select one VFD device.
  3. Continue with credentials → connect → taxes → Validate setup.

3Download & install Mutero Desktop

Mutero Desktop for Windows

Automated Windows setup file (`Mutero-Setup.exe`). No terminal commands required.

  1. Download and launch Mutero-Setup.exe on a Windows PC that can reach your Odoo URL.
  2. Choose Theme Mode (Dark, Light, or System) during setup.
  3. Launch Mutero Desktop → Sign in with browser.
  4. Select one active VFD and open a fiscal day before fiscalising.

4Where to find each Odoo credential

Mutero Desktop → Settings → Odoo — Field Guide

FieldWhere to find it
Odoo URLBrowser address bar while logged into Odoo — scheme + host only, no path. Examples: https://mycompany.odoo.com, https://odoo.example.com, http://192.168.1.50:8069. Do not include /web or /odoo.
DatabaseOn Odoo Online: usually the subdomain (e.g. mycompany). On self-hosted: the DB name on the login / Manage Databases screen. Multi-DB servers show a database dropdown at login — copy that exact name.
UsernameThe Odoo login email or login used for Accounting (e.g. admin@company.com). Must have rights to read posted customer invoices and post chatter notes.
API keyPreferred over passwords (Odoo 14+). In Odoo: open your avatar → Preferences (or My Profile) → Account Security → New API Key. Copy the key once — Odoo will not show it again. Paste into Mutero Desktop; it is stored with Electron safeStorage.
Password fallback
If your Odoo build has no API keys, you can use the account password instead. API keys are safer and survive password changes. Prefer a dedicated integration user with Accounting / Invoicing access rather than a personal admin password.

5Connect Odoo in Mutero Desktop

  1. Open Mutero Desktop → Settings → Odoo.
  2. Enter URL, Database, Username, and API key from the field guide above.
  3. Click Save, then Test connection (auth + posted invoice count).
  4. Enable the listener and leave Auto-fiscalise on (recommended).
  5. Click Validate setup (see below) before go-live.
Credentials stay on this PC
Odoo URL, database, username, and API key never leave this machine. Only fiscalised receipt payloads sync to Mutero Cloud after browser sign-in.

6Set up tax rates in Odoo (ZIMRA FDMS)

Create the three standard ZIMRA tax entries in Odoo under Accounting → Configuration → Taxes (or Invoicing → Configuration → Taxes). Use Sales tax scope. Do not use compound / multi-group taxes for ZIMRA VAT.

Recommended Odoo tax rates

Tax NameAmountTax ScopeZIMRA mapping
VAT 15% or Tax 15%15%SalesStandard Rate (Tax ID 1)
Zero Rated or Zero-Rated0%SalesZero Rated (Tax ID 2)
Exempt or Tax Exempt0%SalesExempt (Tax ID 3)

Mutero resolves known labels and clear rates (0 / ~15) automatically. Custom names must be mapped under Tax Mapping. Unknown taxes never silently become 15%.

Mutero Tax Mapping (cloud) + Desktop sync

  1. Open Dashboard → VFD → Settings → Tax Mapping.
  2. Platform = odoo. Map each Odoo tax name (exact spelling) to ZIMRA tax ID 1 / 2 / 3.
  3. For Zero Rated and Exempt rows, set an 8-digit HS code default (RCPT047 / RCPT048).
  4. In Mutero Desktop → Settings → Odoo, click Sync tax mappings (or run Validate setup, which refreshes mappings automatically).
Unknown Odoo tax names never default to 15%
Unmapped taxes leave the queue row BLOCKED. Fix the Odoo tax name or add a Tax Mapping row, then Sync tax mappings and Sync now.
Invoice preferences tip

Apply the correct sales tax on every invoice line in Odoo. Prefer tax-exclusive pricing unless your catalog is tax-inclusive. Partners with a VAT/TIN populate ZIMRA buyerData (RCPT043). Currency must be USD or ZiG.

7Validate installation

After connecting, click Validate setup in Mutero Desktop → Settings → Odoo. This goes beyond Test connection and checks:

  • Credentials configured + JSON-RPC authentication
  • Mutero Desktop signed in and a VFD device selected
  • Listener enabled (warning if off)
  • Active Odoo sales taxes discovered on account.tax
  • Each tax resolves to ZIMRA (known label or Tax Mapping)
  • Coverage for Standard 15%, Zero Rated, and Exempt
  • 8-digit HS defaults on zero-rated / exempt mappings
  • Tax mappings refreshed from Mutero Cloud

Results show as ready, needs attention, or not ready, with per-check OK / WARN / FAIL lines and any unmapped tax names listed for Tax Mapping.

When to re-validate
Re-run Validate setup after creating new Odoo taxes, changing Tax Mapping, or moving to a new Odoo database / URL.

8. How the listener works

While the listener is enabled, the agent polls Odoo about every 45 seconds for posted account.move records:

  • out_invoice → fiscal invoice
  • out_refund → ZIMRA credit note against the original

Use Sync now for an immediate pull. Drafts are ignored — only posted customer invoices and refunds are fiscalised.

9. Invoice numbering (OD-)

Mutero prefixes Odoo document names so the source is visible in Invoices and the Queue:

Odoo documentMutero number
INV/2026/0001OD-INV/2026/0001
RINV/2026/0001OD-CN-RINV/2026/0001

10. How to issue a credit note

Easiest option: Mutero web app
If Odoo feels confusing, open the fiscalised invoice in the Mutero web app, then click Issue Credit Note. That handles the ZIMRA credit note for you. Use the Odoo steps below only when you also want the credit note recorded in Odoo.

Create the credit note in Odoo from the fiscalised customer invoice. Mutero Desktop will pick it up after you post it.

Steps in Odoo

  1. Open the original posted customer invoice (already fiscalised in Mutero).
  2. Use Add Credit Note / reverse it so Odoo links the refund to that invoice.
  3. Add a short reason in the narration / reference.
  4. Post the credit note (drafts are ignored).
If it is skipped
The refund must point at the original invoice, and that original must already be fiscalised in Mutero.

11. ZIMRA writeback

After a successful fiscal sync, Mutero posts a chatter note on the Odoo move with the Mutero invoice number, fiscal receipt number (when available), and verification URL.

Troubleshooting

  • Auth failed — confirm URL (no trailing path), exact database name, username, and API key. Prefer API keys on Odoo 14+.
  • Wrong database — multi-DB servers often fail auth with a cryptic RPC error; re-check the Manage Databases name.
  • Validate setup FAIL on taxes — create VAT 15% / Zero Rated / Exempt in Odoo, map custom names in Tax Mapping, Sync tax mappings, then Validate again.
  • Nothing queued — only posted customer invoices/refunds are pulled. Check listener enabled + fiscal day open.
  • BLOCKED (tax / HS) — map the Odoo tax or add an 8-digit HS for zero-rated / exempt lines.
  • Offline — items stay in the Desktop Queue as PENDING and drain when Mutero Cloud is reachable again.
  • Credit note skipped — the refund must reference the original (reversed_entry_id), and that original must already be fiscalised as OD-….