The Fiscal API
Fiscalise invoices, credit notes and debit notes from any system through a business's own ThumaBooks fiscal device. JSON over HTTPS, money in cents, errors in sentences. Version 2026-10-01, returned on every answer as Thuma-Api-Version.
Quickstart
- In the Books Desk, open Month-end → Developers & integrations and press New test key. Copy it: it is shown once, and only its fingerprint is kept.
- Send an invoice with it. A test key checks it against every ZIMRA rule and answers with exactly what ZIMRA would receive — taxes, payments, refusals — without filing anything.
- When your integration is right, make a live key. The same request now creates the document in the business's books and fiscalises it with its device.
curl https://api.thumaexpress.com/api/v1/fiscal/account \
-H "Authorization: Bearer tbk_test_…"
Base URL: https://api.thumaexpress.com/api/v1/fiscal.
Keys and modes
Send the key as a bearer token. tbk_live_… files real documents; tbk_test_… previews. A key acts with the authority of the person who made it — an owner or accountant of those books — and a revoked key stops working at once. Every bad key gets the same 401 invalid_api_key, whatever is wrong with it.
Create an invoice
POST /invoices
| Field | What it is |
|---|---|
type | invoice (default), credit_note or debit_note |
source * | The system it came from: 2–40 of a–z, 0–9, . _ - (xero, my-pos) |
externalId * | That system's own id for this document. One document per source and id, ever. |
currency * | USD or ZWG |
lines[] * | 1 to 50: description, quantity (up to 3 decimals), unitAmount (VAT-inclusive, in cents), optional amount (line total in cents, within a cent of quantity × unitAmount), taxClass (standard, zero, exempt), optional hsCode (4 or 8 digits) |
payments[] | One payment for the full total — method: cash, card, mobile_money, bank_transfer, other; amount in cents. None: a sale on account. |
customer | name, tin (10 digits), vatNumber (9), email, phone, address. Required for a sale on account; a TIN and VAT number print on a tax invoice. |
memo | Up to 300 characters, kept with the document. |
The standard rate is the one ZIMRA has configured for the device (15.5 % since 1 January 2026); you send the class, not the rate, so a rate change never breaks your integration.
Credit and debit notes
The same request with type set, a reason (printed on the note, as ZIMRA requires), and the invoice it corrects: correctsExternalId (same source) or correctsInvoiceId. Send the invoice first.
Money back. A credit note against an invoice that is still owed reduces what is owed, and carries no payment. Against an invoice paid in full it gives money back: send it with payments: [{ "method", "amount" }] saying how the money went back, and ZIMRA receives it as a CreditNote with negative payments. Sent without one, it is refused with 422 invoice_settled. Notes together never take back more than the invoice was for.
{ "type": "credit_note", "source": "xero", "externalId": "CN-0003",
"correctsExternalId": "INV-0042", "reason": "Two bags returned damaged",
"currency": "USD",
"lines": [{ "description": "Cement 50kg", "quantity": 2, "unitAmount": 1155,
"taxClass": "standard" }] }
The answer
201 the first time, 200 for the same document again.
{
"object": "invoice", "id": "9b2f…", "livemode": true, "number": "INV-118",
"type": "invoice", "source": "my-pos", "externalId": "INV-0042",
"currency": "USD", "total": 2310, "vat": 310, "status": "fiscalised",
"fiscal": {
"deviceId": 21045, "fiscalDayNo": 84, "receiptGlobalNo": 5521,
"verificationCode": "4C8B-1F0A-93DE-7E21",
"qrPayload": "https://fdms.zimra.co.zw/0000021045021020260000005521…",
"zimraSignature": "verified"
},
"links": { "pdf": "/api/v1/fiscal/invoices/9b2f…/pdf",
"receipt48": "/api/v1/fiscal/invoices/9b2f…/receipt48" }
}
status: fiscalised (ZIMRA has it), signed (signed, in the queue), pending (being signed), refused (with refusal, a sentence), or not_fiscalised (no device registered). A test key answers "object": "invoice_preview" with the receipt as ZIMRA would get it.
Retrieve and list
GET /invoices/{id} or /invoices/{source}:{externalId}
GET /invoices?limit=20&source=xero&startingAfter={id}
GET /account — the business, whether its device is fiscalising, and its alerts
GET /invoices/{ref}/pdf — the A4 invoice ZIMRA prescribes, as base64 in JSON
GET /invoices/{ref}/receipt48?cols=48 — the slip, line by line: 48 columns for 80 mm, 32 for 58 mm, 42 or 64 for others
Sending twice
Two protections, so a retry after a timeout is always safe. The same source and externalId is the same document, forever. And an Idempotency-Key header replays the first answer for 24 hours; the same key with a different body is refused with 409 idempotency_conflict.
Webhooks
Add an https endpoint in the Desk. Events: invoice.fiscalised and invoice.refused, each delivered once, retried from a minute to six hours apart for up to 12 attempts. Each delivery carries Thuma-Event, Thuma-Event-Id and Thuma-Signature: t=<unix>,v1=<hex> — an HMAC-SHA256 of t + "." + body with your endpoint's secret.
const crypto = require('crypto');
// rawBody: the bytes as received, before any JSON parsing
function verify(rawBody, header, secret, toleranceSec = 300) {
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
const expected = crypto.createHmac('sha256', secret)
.update(`${parts.t}.${rawBody}`).digest('hex');
const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) <= toleranceSec;
const a = Buffer.from(expected), b = Buffer.from(parts.v1 || '');
return fresh && a.length === b.length && crypto.timingSafeEqual(a, b);
}
import hmac, hashlib, time
def verify(raw_body: bytes, header: str, secret: str, tolerance=300) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body,
hashlib.sha256).hexdigest()
fresh = abs(time.time() - int(parts["t"])) <= tolerance
return fresh and hmac.compare_digest(expected, parts.get("v1", ""))
function verify(string $rawBody, string $header, string $secret, int $tolerance = 300): bool {
parse_str(str_replace(',', '&', $header), $p);
$expected = hash_hmac('sha256', $p['t'] . '.' . $rawBody, $secret);
return abs(time() - (int) $p['t']) <= $tolerance
&& hash_equals($expected, $p['v1'] ?? '');
}
Connectors
POST /invoices/from/{xero|quickbooks|zoho|sage|odoo}
Send { "document": …, "options": … } — the invoice exactly as that system's API returns it. Options: paidBy, refundedBy (a credit note that gave money back), taxMap (source tax code → standard, zero or exempt), correctsExternalId, kind (CreditMemo for QuickBooks, sales_credit_note for Sage), and for Odoo lines (the move's account.move.line records). The answer adds warnings. A document we will not guess about is refused with 400 unmappable_document and a sentence saying what to add. Details per system on integrations.
Spreadsheet import
POST /imports — { "csv": "…" }, up to 200 documents
GET /imports/template — the CSV template (no key needed)
Columns: document_id, type, currency, customer_name, customer_tin, customer_vat_number, customer_email, description, quantity, unit_price, tax, hs_code, paid_by, corrects_document_id, reason. Prices are VAT-inclusive decimals, as a till shows them. The answer lists each document: ok, created, the invoice, or the error with its row.
Partner keys
For resellers and software vendors. Register as a partner (signed in, POST /fiscal-partners), make a partner key, and give your clients your partner code. A client enters it in the Desk to grant you access — and removes it to take access away. Call the API for a client with your key and their account id:
curl https://api.thumaexpress.com/api/v1/fiscal/invoices \
-H "Authorization: Bearer tbk_live_…partner…" \
-H "Thuma-Account: 3f6e…" # the client's books
curl https://api.thumaexpress.com/api/v1/fiscal/partner/accounts \
-H "Authorization: Bearer tbk_live_…partner…" # who has granted you
A partner key acts with the authority of whoever granted it, and never more than the API allows. Without a grant: 403 account_not_granted.
Errors
Every refusal has one shape: { "error": { "type", "code", "message", "param"? } }. message is a sentence a person can act on; param names the field.
| Status | code | Means |
|---|---|---|
| 400 | invalid_request | A field is missing or malformed; param says which. |
| 400 | unmappable_document | A connector could not map the source document without guessing. |
| 400 | account_required | A partner key needs Thuma-Account. |
| 401 | invalid_api_key | Missing, wrong or revoked key. |
| 403 | account_not_granted | That business has not granted this partner, or removed it. |
| 404 | invoice_not_found | No such document — or a note's invoice was not sent first. |
| 409 | idempotency_conflict | An Idempotency-Key reused with a different body. |
| 422 | invoice_settled | A credit note against a paid invoice, sent without saying how the money went back. |
| 422 | invoice_refused | The books or a ZIMRA rule refused it; the message says which and why. |
| 429 | rate_limited | Over 120 requests a minute on this key. |
| 503 | unavailable | Retry with the same Idempotency-Key. |
Limits
- 120 requests a minute per key.
- 50 lines per document; 200 documents and 2 MB per import.
- Money in cents (integers); quantities to 3 decimals.
Changelog
2026-10-02 — A credit note against an invoice paid in full gives money back, with its payments (invoice_settled when they are missing). Connectors take refundedBy; a Xero credit note refunded in Xero is read as money back; a spreadsheet credit note's paid_by is how money went back.
2026-10-01 — First version: invoices, credit and debit notes, test mode, idempotency, webhooks, PDF and slips, connectors for Xero, QuickBooks Online, Zoho Books, Sage Business Cloud and Odoo, spreadsheet import, partner keys.