What no one tells you about integrating with African tax authority APIs
After delivering production-live integrations with ZRA (Zambia) and TRA (Tanzania), we documented the real challenges that the official specifications do not prepare you for.
The specification problem
Most tax authority API specifications are written by compliance professionals, not software engineers. The ZRA Smart Invoice API documentation runs to several hundred pages, but the sections most critical to integration — error code semantics, retry behaviour, and edge case handling — are either absent or ambiguous. You will not discover this until you are deep in the integration work.
Sandbox vs. production divergence
The sandbox environments provided by tax authorities frequently behave differently from production. We encountered cases where error codes returned in sandbox did not map to the same conditions in production — meaning that testing against the sandbox gave a false sense of completeness. The only way to catch these divergences is methodical boundary testing and being prepared to adjust after the production go-live.
Certification is not the end
Both ZRA and TRA require formal certification before you can go live. The certification process involves submitting a defined set of test transactions and receiving sign-off from the authority's technical team. What the specifications do not mention is that this process can take weeks, requires direct human communication with the authority, and can surface requirements that were not in any documentation. Build this timeline into your project plan — not as a footnote, but as a critical path item.
Retry logic is not optional
Tax authority APIs are not SLA-backed like commercial APIs. Downtime, slow responses, and intermittent failures are real. Every e-invoicing integration must include robust retry logic with exponential backoff, a queue for failed submissions, and clear alerting when invoices have been outstanding beyond a threshold. A business cannot function if a transaction failure means an invoice is simply lost.
Dual-jurisdiction is a different problem
Our most complex delivery was a client requiring simultaneous integration with both ZRA and TRA — two different API specifications, two certification processes, two sets of error codes. The architectural solution was a unified compliance middleware layer that normalised both specifications behind a single internal interface. This approach added upfront complexity but made the ongoing maintenance of each jurisdiction's integration independently manageable.
What to budget for
If you are planning an e-invoicing integration and have not built one before, here is our honest budgeting advice: double your initial engineering estimate, and add at least six weeks to your timeline to account for certification delays and post-launch adjustments. Include an ongoing maintenance line — because tax authority API specifications change, and you will need to track and respond to those changes. The integration does not end at go-live.
We have delivered this in production. If you are starting an e-invoicing integration project and want to understand the scope honestly before you commit to a timeline, reach out. We would rather give you an accurate picture upfront than let you discover the complexities partway through.