Developers

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.

OpenAPI 3.1llms.txt (for AI assistants)CSV template

Quickstart

  1. 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.
  2. 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.
  3. 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

Invoice fields
FieldWhat it is
typeinvoice (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.
customername, tin (10 digits), vatNumber (9), email, phone, address. Required for a sale on account; a TIN and VAT number print on a tax invoice.
memoUp 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

Print

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);
}

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.

Error codes
StatuscodeMeans
400invalid_requestA field is missing or malformed; param says which.
400unmappable_documentA connector could not map the source document without guessing.
400account_requiredA partner key needs Thuma-Account.
401invalid_api_keyMissing, wrong or revoked key.
403account_not_grantedThat business has not granted this partner, or removed it.
404invoice_not_foundNo such document — or a note's invoice was not sent first.
409idempotency_conflictAn Idempotency-Key reused with a different body.
422invoice_settledA credit note against a paid invoice, sent without saying how the money went back.
422invoice_refusedThe books or a ZIMRA rule refused it; the message says which and why.
429rate_limitedOver 120 requests a minute on this key.
503unavailableRetry 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.