Introduction

The ThatFiscal API lets you send invoices and credit notes to the ZIMRA revenue authority for fiscal processing from your own application or any accounting system. One POST in, a fiscalised receipt out.

Authentication

Every request carries your tenant API key in the X-Api-Key header. Find it in Portal → Settings & Branding. Keys start with tf_.

X-Api-Key: tf_Kx9……your_key……

The key is issued the moment your account goes Live. Before that, the /portal/* endpoints — including device registration — also accept a signed-in portal session in the X-Portal-Session header, which is how you register your first device and unlock the key.

Errors & Status Codes

ZIMRA validation errors are surfaced as error_code (RCPT047, RCPT015, RCPT043, …) with a plain-language error_detail. Platform-side holds use their own codes: PAYMENT_REQUIRED, PLAN_LIMIT, FISCAL_DAY, MAPPING. The Knowledge Base Error Table explains each fix.

Webhooks (Inbound Connectors)

Pre-built receivers translate each system's native payload into the canonical invoice — no mapping work on your side. All of them take the same X-Api-Key header and return the same receipt summary as /api/invoices.

Submit Invoice

Submit a canonical invoice for fiscalisation. Synchronous: the response tells you whether ZIMRA accepted it.

{
  "invoice_no": "INV-2026-0042",
  "receipt_type": "FiscalInvoice",
  "currency": "USD",
  "lines_tax_inclusive": true,
  "buyer": {"name": "Company ABC Ltd", "tin": "1987012311"},
  "lines": [{
    "name": "Consulting", "hs_code": "9983",
    "qty": 1, "price": 115.50, "total": 115.50,
    "tax_percent": 15.5, "tax_id": 3
  }],
  "payments": [{"money_type": "BankTransfer", "amount": 115.50}]
}

Validation

The body is validated before anything is written or sent. A failure returns 422 with a detail string listing every problem at once:

Response

{
  "id": "9f2c…", "status": "fiscalised",
  "invoice_no": "INV-2026-0042", "type": "FiscalInvoice",
  "source": "api", "currency": "USD", "total": 115.00,
  "receipt_global_no": 482, "receipt_counter": 17,
  "verification_code": "C0DE-4F92-A1B7-22E8",
  "qr_url": "https://invoice.zimra.co.zw/…",
  "error_code": null, "attempts": 1,
  "fiscalised_at": "2026-08-16T09:14:02", "created_at": "2026-08-16T09:14:01"
}

status is fiscalised or fiscalised_yellow when ZIMRA accepted it (Yellow means accepted with a non-blocking warning), and error when it did not — in which case error_code is populated and the receipt can be re-submitted with Resend. qr_url and verification_code are null until the receipt is fiscalised.

Submit Credit Note

Same endpoint, with receipt_type: "CreditNote" plus a credited_invoice object referencing the original document:

{
  "invoice_no": "CN-2026-0007",
  "receipt_type": "CreditNote",
  "credited_invoice": {"invoiceNo": "INV-2026-0042"},
  "currency": "USD",
  "notes": "Goods returned — damaged in transit",
  "lines": [ …the lines being credited, as positive amounts… ],
  "payments": [{"money_type": "BankTransfer", "amount": 115.00}]
}

Identifying the Original

credited_invoice accepts any one of these shapes. We resolve whichever you send into the reference FDMS requires (§4.7) — a receiptID, or deviceID + receiptGlobalNo + fiscalDayNo together:

ThatFiscal links it to the original receipt and nets it off in all reports. Debit notes: receipt_type: "DebitNote", with the same credited_invoice requirement.

Check Status

Full detail for one receipt: everything in the submit response plus payload (the canonical invoice as we stored it), server_signature, device_hash and error_detail.

List receipts newest first. status filters on one receipt status; q searches the invoice number.

Resend Receipt

Re-fiscalise after fixing an error. A receipt that is already fiscalised or fiscalised_yellow returns 409 rather than being sent twice. The receipt keeps its originally reserved global number and counter on retry, so no gap appears in the device's sequence.

Download QR

The ZIMRA QR as a PNG, ready to embed in your own invoice template. Returns 404 until the receipt is fiscalised and has a QR URL.

Period Summary

Total fiscalised invoices, credit notes, errors and net value by currency for any month range — e.g. January and February together. Credit notes are subtracted from the value totals. Omit dfrom / dto for everything on record:

{
  "from": "2026-01", "to": "2026-02",
  "total_fiscalised": 214, "total_errors": 3,
  "net_value_by_currency": {"USD": 48210.55, "ZWG": 812400.00},
  "by_source": {"odoo": 180, "api": 31, "excel": 3},
  "by_month": {
    "2026-01": {"invoices": 98, "credit_notes": 4, "errors": 1, "value": {"USD": 22110.20}},
    "2026-02": {"invoices": 109, "credit_notes": 3, "errors": 2, "value": {"USD": 26100.35}}
  }
}

VAT Report

Output VAT by rate and currency — taxable, VAT and gross — with credit notes netted. These are the figures for the VAT7 return.

Audit Export

One CSV row per receipt: date, invoice number, type, status, currency, total, global number, verification code, source, error code.

Register Device

{ "zimra_device_id": 12345, "activation_key": "XXXX-XXXX",
  "serial_no": "TFVFD-2026-00001", "environment": "prod" }   // serial_no is optional — defaults to your assigned TFVFD serial

Runs the full ZIMRA §2.1 flow: verify taxpayer → keygen (ECC P-256) → CSR → registerDevice → getConfig. The certificate and private key are held server-side and are never returned by the API. environment is test or prod; a missing zimra_device_id or activation_key returns 422.

Close Fiscal Day

Closes the open fiscal day with the fiscal-day device signature (§13.3.1) and produces the Z-report. Returns 409 when receipts inside the day are still blocking the close — clear or resend those first, or pass ?force=true when support tells you to. A day left open past the device's maximum day length (taxPayerDayMaxHrs from getConfig, usually 24 hours) is closed automatically by the platform.

Live FDMS device and fiscal-day status: operating mode, certificate expiry, the open day's number, when it must close by, hours remaining, and the receipts currently blocking a close.

The Z-report for a closed day, or the X-report for the day still open. fmt=json for the structured model, fmt=text for the 48-column printed layout.

Branding Settings

Read or update the tenant's invoice branding: logo_data_url, bank_name, bank_branch, account_name, account_number_usd, account_number_zwg, swift_code, invoice_notes, invoice_footer, address, phone. POST only the fields you are changing. A logo over 300 KB returns 413; setting a logo requires the branding feature (Standard and Enterprise, or as an add-on) and returns 402 otherwise.

Billing (Paynow)

{ "plan": "standard", "period": "monthly",
  "method": "ecocash", "phone": "0771234567" }

Card payments (method: "web") return a redirect_url to Paynow checkout. Ecocash/OneMoney push a prompt to the phone; poll GET /billing/paynow/poll/{payment_id} until status: "paid". The plan activates the moment Paynow confirms.

Current plan, price, invoice usage this month, and last payment.

Canonical Invoice Schema

Version Notes

• 16 August 2026 — Connector Overhaul
  • Strict validation on /api/invoices: a malformed payload now returns 422 naming every problem, instead of a 500. credited_invoice is enforced on credit and debit notes.
  • Credit notes work on every connector. credited_invoice accepts invoiceNo, receiptID or sourceRef and is resolved to the FDMS §4.7 reference; previously the invoice number was dropped and every credit note failed RCPT015.
  • Odoo: only out_invoice and out_refund in state posted are fiscalised. Vendor bills, vendor credit notes, journal entries and receipts return 200 with skipped: true instead of becoming error receipts that block the Z report. Lines are read tax-exclusive from price_subtotal.
  • Zoho Books: buyer TIN/VAT and line HS codes are read from custom fields via custom_field_hash, custom_fields and item_custom_fields. The date is no longer used to stamp the receipt (it caused RCPT014 / RCPT030 on every invoice after the first of the day). Percentage discounts and shipping charges are carried correctly.
  • QuickBooks Online: tax rates are read from TxnTaxDetail.TaxLine[].TaxLineDetail.TaxPercent; zero-rated and NON lines stay at 0%. Credit memos are detected even when posted unwrapped, and link through LinkedTxn.
  • Excel / CSV: a blank tax_inclusive column now means tax-inclusive. An unknown receipt_type is rejected before submission, and one bad row no longer abandons the rest of the upload.
• 10 August 2026
  • Added /portal/reports/summary, /portal/reports/vat, /portal/reports/export.csv — period reporting by month range.
  • Added Paynow billing endpoints (/billing/paynow/*) with Ecocash, OneMoney and card.
  • Added branding settings (/portal/settings): logo, banking details, invoice notes.
  • Added reseller application API (/api/resellers/apply).
• April 2026
  • Receipt signature & hash chaining verified against every worked example in ZIMRA spec v7.2.
  • Credit-note linkage to original global number.
• Initial release
  • Device registration flow, submitReceipt, fiscal counters, openDay/closeDay, QR & verification codes, Odoo/Zoho/QuickBooks/Excel connectors.