{
  "openapi": "3.1.0",
  "info": {
    "title": "ThumaBooks Fiscal API",
    "version": "2026-10-01",
    "description": "Fiscalise invoices, credit notes and debit notes from any system through a business's own ThumaBooks fiscal device (ZIMRA FDMS v7.2). Money in minor units (cents). Test keys (tbk_test_) preview and file nothing; live keys (tbk_live_) file.",
    "contact": {
      "email": "hello@thumabooks.com",
      "url": "https://fiscalisation.thumabooks.com/developers.html"
    }
  },
  "servers": [
    {
      "url": "https://api.thumaexpress.com/api/v1/fiscal"
    }
  ],
  "security": [
    {
      "bearer": []
    }
  ],
  "paths": {
    "/account": {
      "get": {
        "summary": "The key's business, and whether its device is fiscalising",
        "parameters": [
          {
            "name": "Thuma-Account",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "With a partner key: the business to act for (it must have granted the partner)."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "503": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/invoices": {
      "post": {
        "summary": "Create and fiscalise an invoice, credit note or debit note",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 255
            },
            "description": "Replays the first answer for 24 hours; a different body under the same key is refused (409)."
          },
          {
            "name": "Thuma-Account",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "With a partner key: the business to act for (it must have granted the partner)."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InvoiceCreate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Invoice"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "503": {
            "$ref": "#/components/responses/Error"
          },
          "200": {
            "description": "The same document, sent again (same source and externalId), or a test-mode preview",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Invoice"
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "List invoices, newest first",
        "parameters": [
          {
            "name": "Thuma-Account",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "With a partner key: the business to act for (it must have granted the partner)."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "source",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "startingAfter",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "hasMore": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Invoice"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "503": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/invoices/{ref}": {
      "get": {
        "summary": "Retrieve an invoice",
        "parameters": [
          {
            "name": "ref",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The invoice id, or source:externalId."
          },
          {
            "name": "Thuma-Account",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "With a partner key: the business to act for (it must have granted the partner)."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Invoice"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "503": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/invoices/{ref}/pdf": {
      "get": {
        "summary": "The A4 invoice as ZIMRA prescribes, base64 in JSON",
        "parameters": [
          {
            "name": "ref",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The invoice id, or source:externalId."
          },
          {
            "name": "Thuma-Account",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "With a partner key: the business to act for (it must have granted the partner)."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "filename": {
                      "type": "string"
                    },
                    "base64": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "503": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/invoices/{ref}/receipt48": {
      "get": {
        "summary": "The receipt slip, line by line",
        "parameters": [
          {
            "name": "ref",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The invoice id, or source:externalId."
          },
          {
            "name": "Thuma-Account",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "With a partner key: the business to act for (it must have granted the partner)."
          },
          {
            "name": "cols",
            "in": "query",
            "schema": {
              "type": "integer",
              "enum": [
                32,
                42,
                48,
                64
              ],
              "default": 48
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "lines": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "qr": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "503": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/invoices/from/{source}": {
      "post": {
        "summary": "Map another system's own invoice and create it",
        "description": "The body carries the document exactly as Xero, QuickBooks Online, Zoho Books, Sage Business Cloud or Odoo returns it. The answer adds warnings: each judgement the mapping made.",
        "parameters": [
          {
            "name": "source",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "xero",
                "quickbooks",
                "zoho",
                "sage",
                "odoo"
              ]
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 255
            },
            "description": "Replays the first answer for 24 hours; a different body under the same key is refused (409)."
          },
          {
            "name": "Thuma-Account",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "With a partner key: the business to act for (it must have granted the partner)."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "document"
                ],
                "properties": {
                  "document": {
                    "type": "object"
                  },
                  "options": {
                    "type": "object",
                    "properties": {
                      "paidBy": {
                        "type": "string",
                        "enum": [
                          "cash",
                          "card",
                          "mobile_money",
                          "bank_transfer",
                          "other"
                        ]
                      },
                      "taxMap": {
                        "type": "object",
                        "additionalProperties": {
                          "type": "string",
                          "enum": [
                            "standard",
                            "zero",
                            "exempt"
                          ]
                        }
                      },
                      "correctsExternalId": {
                        "type": "string"
                      },
                      "kind": {
                        "type": "string",
                        "enum": [
                          "CreditMemo",
                          "sales_credit_note"
                        ]
                      },
                      "lines": {
                        "type": "array",
                        "items": {
                          "type": "object"
                        },
                        "description": "Odoo: the move's account.move.line records"
                      },
                      "refundedBy": {
                        "type": "string",
                        "enum": [
                          "cash",
                          "card",
                          "mobile_money",
                          "bank_transfer",
                          "other"
                        ],
                        "description": "A credit note that gave money back: how"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Invoice"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "warnings": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "503": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/imports": {
      "post": {
        "summary": "Import a spreadsheet (CSV) of documents, each created once",
        "parameters": [
          {
            "name": "Thuma-Account",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "With a partner key: the business to act for (it must have granted the partner)."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "csv"
                ],
                "properties": {
                  "csv": {
                    "type": "string",
                    "maxLength": 2000000
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "const": "import"
                    },
                    "livemode": {
                      "type": "boolean"
                    },
                    "documents": {
                      "type": "integer"
                    },
                    "succeeded": {
                      "type": "integer"
                    },
                    "failed": {
                      "type": "integer"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "503": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/imports/template": {
      "get": {
        "summary": "The CSV template",
        "security": [],
        "responses": {
          "200": {
            "description": "CSV",
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/partner/accounts": {
      "get": {
        "summary": "A partner key's businesses: those that granted it",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "409": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "503": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "tbk_live_… or tbk_test_…"
      }
    },
    "responses": {
      "Error": {
        "description": "A refusal, in one shape",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "type",
              "code",
              "message"
            ],
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "invalid_request_error",
                  "authentication_error",
                  "rate_limit_error",
                  "api_error"
                ]
              },
              "code": {
                "type": "string",
                "examples": [
                  "invalid_request",
                  "unmappable_document",
                  "account_required",
                  "invalid_api_key",
                  "account_not_granted",
                  "invoice_not_found",
                  "idempotency_conflict",
                  "invoice_refused",
                  "invoice_settled",
                  "rate_limited",
                  "unavailable"
                ]
              },
              "message": {
                "type": "string"
              },
              "param": {
                "type": "string"
              }
            }
          }
        }
      },
      "Line": {
        "type": "object",
        "required": [
          "description",
          "unitAmount"
        ],
        "properties": {
          "description": {
            "type": "string",
            "maxLength": 200
          },
          "quantity": {
            "type": "number",
            "exclusiveMinimum": 0,
            "default": 1
          },
          "unitAmount": {
            "type": "integer",
            "minimum": 0,
            "description": "VAT-inclusive unit price in cents"
          },
          "amount": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "description": "VAT-inclusive line total in cents; within a cent of quantity × unitAmount"
          },
          "taxClass": {
            "type": "string",
            "enum": [
              "standard",
              "zero",
              "exempt"
            ],
            "default": "standard"
          },
          "hsCode": {
            "type": "string",
            "pattern": "^\\d{4}(\\d{4})?$"
          }
        }
      },
      "InvoiceCreate": {
        "type": "object",
        "required": [
          "source",
          "externalId",
          "currency",
          "lines"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "invoice",
              "credit_note",
              "debit_note"
            ],
            "default": "invoice"
          },
          "source": {
            "type": "string",
            "pattern": "^[a-z0-9_.-]{2,40}$"
          },
          "externalId": {
            "type": "string",
            "maxLength": 120
          },
          "currency": {
            "type": "string",
            "enum": [
              "USD",
              "ZWG"
            ]
          },
          "lines": {
            "type": "array",
            "minItems": 1,
            "maxItems": 50,
            "items": {
              "$ref": "#/components/schemas/Line"
            }
          },
          "payments": {
            "type": "array",
            "maxItems": 1,
            "items": {
              "type": "object",
              "required": [
                "method",
                "amount"
              ],
              "properties": {
                "method": {
                  "type": "string",
                  "enum": [
                    "cash",
                    "card",
                    "mobile_money",
                    "bank_transfer",
                    "other"
                  ]
                },
                "amount": {
                  "type": "integer"
                }
              }
            },
            "description": "On an invoice: how it was paid in full (none: on account). On a credit note against a paid invoice: how the money went back. Not on a debit note."
          },
          "customer": {
            "type": "object",
            "required": [
              "name"
            ],
            "properties": {
              "name": {
                "type": "string"
              },
              "tin": {
                "type": "string",
                "pattern": "^\\d{10}$"
              },
              "vatNumber": {
                "type": "string",
                "pattern": "^\\d{9}$"
              },
              "email": {
                "type": "string"
              },
              "phone": {
                "type": "string"
              },
              "address": {
                "type": "string"
              }
            }
          },
          "reason": {
            "type": "string",
            "minLength": 3,
            "description": "Required on a note"
          },
          "correctsExternalId": {
            "type": "string"
          },
          "correctsInvoiceId": {
            "type": "string",
            "format": "uuid"
          },
          "memo": {
            "type": "string",
            "maxLength": 300
          }
        }
      },
      "Invoice": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "invoice",
              "invoice_preview"
            ]
          },
          "id": {
            "type": "string"
          },
          "livemode": {
            "type": "boolean"
          },
          "number": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "source": {
            "type": [
              "string",
              "null"
            ]
          },
          "externalId": {
            "type": [
              "string",
              "null"
            ]
          },
          "currency": {
            "type": "string"
          },
          "total": {
            "type": "integer"
          },
          "vat": {
            "type": "integer"
          },
          "status": {
            "type": "string",
            "enum": [
              "fiscalised",
              "signed",
              "pending",
              "refused",
              "not_fiscalised"
            ]
          },
          "fiscal": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "deviceId": {
                "type": "integer"
              },
              "fiscalDayNo": {
                "type": "integer"
              },
              "receiptGlobalNo": {
                "type": "integer"
              },
              "receiptCounter": {
                "type": "integer"
              },
              "receiptDate": {
                "type": "string"
              },
              "verificationCode": {
                "type": "string"
              },
              "qrPayload": {
                "type": "string"
              },
              "verifyUrl": {
                "type": "string"
              },
              "zimraReceiptId": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "zimraSignature": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "refusal": {
            "type": [
              "string",
              "null"
            ]
          },
          "links": {
            "type": "object"
          }
        }
      }
    }
  },
  "webhooks": {
    "invoice.fiscalised": {
      "post": {
        "summary": "ZIMRA has the receipt",
        "description": "Signed: Thuma-Signature: t=<unix>,v1=<hex HMAC-SHA256 of t + '.' + body>.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "object": {
                    "const": "event"
                  },
                  "type": {
                    "type": "string"
                  },
                  "created": {
                    "type": "string"
                  },
                  "data": {
                    "$ref": "#/components/schemas/Invoice"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Received"
          }
        }
      }
    },
    "invoice.refused": {
      "post": {
        "summary": "The device could not fiscalise it, with the reason",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Received"
          }
        }
      }
    }
  }
}
