ZRA Smart Invoice Pro — the control tower for your VSDC
One screen to supervise everything your business declares to the Zambia Revenue Authority: the ZRA Bot with live counts and one-click Flush Queue, Retry Failed, Run Sweepers and Test VSDC, a unified Declarations report over invoices and POS orders with pivot and graph, a stock-movements analysis over every saveStockItems call, and a persistent health log that records every time the integration repaired itself. Built on the free ZRA Smart Invoice Base.
One-time purchase · unlimited documents · free updates on every ZRA Smart Invoice spec change. Requires the free ZRA Smart Invoice Base.
See everything, fix it in one click
Pro turns your Smart Invoice integration from a black box into a cockpit. The ZRA Bot counts what is pending, sending, failed and declared today, warns you when transmission is paused or a critical health alert is open, and gives you four buttons that solve almost every real problem: flush the queue, retry the failures, re-run the sweepers, test the VSDC. Around it sit a unified Declarations report with pivot and graph, a stock-movements analysis, and a health-event log that proves what the system did on your behalf — all reading your own VSDC or OSDC directly, with no third-party SaaS in the middle of your tax data.
The ZRA Bot
Live tiles for Pending, Failed, Declared Today and Sending, each drilling into the queue behind it — plus Flush Queue, Retry Failed, Run Sweepers and Test VSDC, so a manager runs the whole integration from one screen.
Declarations, analysed
Every invoice and POS order declared to the ZRA in one searchable list, pivot and graph — ZRA invoice number, receipt number, customer, untaxed, VAT and total, drillable straight to the source document.
It tells you when it heals itself
A health log records every intervention with a severity: a scheduled job switched back on, entries recovered from Sending, a VSDC that stopped answering, a backlog of repeat failures, a hole in your number series.
Supervise the whole integration, end to end
One screen over every declaration you make
Pro adds the ZRA Bot: a single dashboard that reads the live submission queue and answers the only question that matters at five o’clock — is everything at the ZRA? It opens from ZRA Smart Invoice › Bot as a single record that is created on first use and reused thereafter, so there is one cockpit rather than a pile of dashboards. Every figure on it is computed from the queue at the moment you look, so nothing is cached and nothing is stale.
Pending, Failed, Declared Today and Sending — counted for you
Four stat tiles run across the top of the Bot: Pending (waiting to go), Failed (the VSDC refused, or could not be reached), Declared Today (accepted since midnight) and Sending (in flight right now). Each is a live count straight off the queue, and each is a button — click any tile and you land in the submission queue itself rather than being left to search for the rows behind the number. A Sending count that never moves is the clearest early warning you can get, and it is on the tile.
Send everything that is due, right now, in order
Flush Queue stops you waiting for the next scheduled sweep: it processes the whole backlog immediately, oldest first. Chronological order is not cosmetic here — the ZRA requires continuous, ordered sequences, and a sale’s stock-out must not arrive before the sale itself, so flushing in create order keeps the VSDC receiving your documents the way it expects them. It honours the transmission setting too, so nothing leaks out of a company you deliberately paused. Reserved for a ZRA Manager.
Re-queue every rejection in a single click
Retry Failed picks up every failed entry for you, gives each one back an attempt from its budget and re-sends it there and then — instead of you opening rejections one at a time. It is the button for the minute after you fixed the cause: the VSDC was down, a product had no item class, the branch was wrong. Fix it once, press once, and the backlog clears. Also reserved for a ZRA Manager.
Catch the documents that never made it into the queue
The three sweepers normally run hourly on their own: they hunt for posted invoices, paid POS orders and validated transfers that have no live queue entry — the ones raised while the settings were incomplete, or while a declaration could not be built — and enqueue them. Run Sweepers fires all three on demand. It is deliberately soft-guarded: only the sweepers whose apps you actually have installed are called, so the button is safe on any combination of the suite.
Prove the connection before you blame the data
Test VSDC runs a lightweight probe — a code lookup keyed by your TPIN and branch — against every company whose transmission is Active and which has a TPIN and a VSDC URL set. The answer comes back as a sticky notification naming each company and what its VSDC said, so a multi-company group sees at a glance which entity is talking to the ZRA and which is not. It is the first thing to press when declarations start failing, and unlike the other three actions it is open to any ZRA user.
The Bot says what is wrong, in words
Three banners appear on the Bot only when they are true. An amber one warns that transmission is paused on one or more companies and that declarations are piling up in the queue — the failure mode that otherwise stays invisible until month end. A red one counts unresolved critical health alerts and points you to the Health log. And a blue one explains any ambiguous-delivery entries: attempts that may have reached the VSDC without a readable answer, which the queue re-sends safely because the VSDC rejects a duplicate with 921 or 994. A clean day shows none of them.
The numbers behind the tiles, spelled out
Under the tiles the Bot groups the same truth into two blocks. Queue lists Pending, Sending, Failed and Ambiguous; Activity lists Declared Today, Critical Alerts and whether transmission is paused. Ambiguous deserves its own line because it is the one count that is not a problem — it is the queue being careful with a call whose outcome could not be read. Everything is scoped to what you are allowed to see, and a multi-company rule keeps each company’s queue to itself.
Every document you declared, whatever app raised it
The Declarations report unions every document your database has declared to the ZRA — customer invoices, credit notes and POS orders — into one analysable list. Each line carries the date, the ZRA invoice number (invcNo), the source, the receipt type (Sale or Refund), the customer, the untaxed, VAT and total amounts with column sums, the ZRA receipt number and a colour-coded status badge: green for Declared, red for Failed, amber for Queued or Not Configured. It is the one artefact to hand an auditor when they ask what you declared.
The report adapts to the apps you actually bought
Pro depends only on the free Base, and the Declarations report is built to match: it inspects your database and unions only the sources that exist. Invoice-only shop? The report is your invoices. POS as well? Both, in one list. Neither yet? The view still builds and simply shows nothing, rather than failing to install. That is why Pro can be bought first, or last, or alongside any subset of the suite, and always shows exactly what your setup declares — nothing more, nothing less.
From a ZRA number to the actual document, in one click
Open any declaration line and an Open Source Document button takes you straight to the record behind it — the customer invoice, the credit note or the POS order. You go from a ZRA invoice number or a receipt number to the document itself with no searching by reference and no guessing which sale a given number belongs to. The read-only form shows the whole declaration first: source, invoice number, type, status, receipt number, date, customer and the untaxed, VAT and total amounts.
Answer “did this reach the ZRA?” in seconds
Type a ZRA invoice number, a customer or a receipt number into the Declarations search bar and land on the exact submission. One-click filters isolate Declared or Failed, or split the report to Invoices only or POS Orders only, and a date filter scopes it to a period. Group By collapses everything by Type, Status, Source, Customer or Month — and the report opens grouped by status by default, so the first thing you see is how many went through and how many did not.
Cross-tab your declarations by month and receipt type
The same data opens as a pivot: months down the rows, receipt type (Sale against Refund) across the columns, with total amount and VAT as the measures. Refunds as a share of sales, month by month, reads straight off the grid — no spreadsheet export, no formula. Drag in the customer, the source or the status to build whatever cross-tab the question needs, then export it like any pivot when the accountant wants it in a file.
See the day it stopped
Switch to the graph and your declared value becomes a bar per day. That is how you spot the afternoon transmission stalled, the week a branch came online, or a run of rejections after a tax change — as a shape, not as a row buried in a list. It uses standard grouping, so any filter or group-by you set carries straight through from the list to the chart, and it can go on a dashboard for a manager who should glance rather than audit.
What you declared, by month, ready for the return
Tax Summary is the same declaration data opened as a pivot, pre-filtered to what the ZRA actually accepted and pre-grouped by month — so the untaxed, VAT and total you declared per month are on screen the moment you click the menu, with no set-up. It is the view to open when you are reconciling a VAT return against what the VSDC really holds, rather than against what your books hope it holds. Every measure is the amount that was declared, not merely posted.
Every stock call to the ZRA, analysed
A second analysis covers the stock side: every item registration, stock movement and stock-master sync that passed through the queue, shown with its reference, its endpoint, its ZRA reason code and its direction. The reason codes are the ZRA’s own sarTyCd vocabulary — 01 Import, 02 Purchase, 03 Return in, 04 Movement in, 05 Processing in, 06 Adjustment in, 11 Sale, 12 Return out, 13 Movement out, 14 Processing out, 15 Discarding, 16 Adjustment out — and In or Out is derived from the code, so you never have to remember which is which.
Reason against status, and volume over time
The stock report opens as a pivot of reason code against status, counting movements — so “every purchase went through but four discards are failing” is one glance rather than an investigation. Its graph plots movements per day split by direction, In against Out. Filters isolate entries in, exits out or failures, and Group By collapses by Reason, Endpoint, Status or Month; it opens grouped by reason, because that is how the ZRA thinks about stock.
A written record of everything that went wrong or fixed itself
The Health log is a persistent, read-only record of the integration’s own life, colour-coded by severity: red for Critical, amber for Warning. Each event has a type — Cron Reactivated, Stuck Entries Recovered, VSDC Unreachable, Queue Backlog, Repeated Failures, Series Integrity or Info — a plain-language name, the company it concerns and a Details box that says what to do about it. Filter to Critical or Warnings, group by Type or Severity. A problem that fixed itself still leaves a trail.
The monitor repairs the integration — and writes it down
Every thirty minutes a health check sweeps the integration and Pro records what it found. If someone switched off the queue, the alerts or the health job itself, it is switched back on and logged as a warning. Entries stuck in Sending for more than fifteen minutes — a killed worker, a dropped connection — are recovered and logged. Anything that has failed five times or more raises a Critical event whose details tell you to review the errors and retry after fixing the cause. And each active company’s VSDC is probed; one that does not answer is a Critical event naming the company and the reason.
A hole in your ZRA numbering is not allowed to stay quiet
The ZRA expects your invoice numbers to form a continuous series. An hourly check reads every ZRA invoice number your invoices and POS orders carry, per company, and looks for duplicates and gaps. If it finds either, it raises a Critical health event naming the offending numbers — because a hole or a duplicate means something interfered with the numbering, and that is a conversation you want to have with yourself rather than with the ZRA. It is the check nobody thinks to build until the audit.
The right screens for the right people
Pro plugs into the three roles under the ZRA Smart Invoice (Zambia) privilege. A ZRA User sees the Bot, the Declarations, the Tax Summary, the Stock Movements report and the Submission Queue, and can test the VSDC; the Flush, Retry and Run Sweepers actions and the Health log are for a ZRA Manager; and the Configuration menu with the VSDC settings is locked to a ZRA Administrator. Every report is read-only for everyone, and each company sees only its own queue.
We connect you to ZRA Smart Invoice
Buying the app includes the setup: we help you register your device on the ZRA Smart Invoice Taxpayer Portal, point the connector at your VSDC (or ZRA’s hosted OSDC), run the device initialisation, validate the full flow on the ZRA sandbox, then switch you to production.
Device on the ZRA Smart Invoice portal
TPIN, branch, device serial, tax bands
Full flow on the ZRA sandbox
Switch to production, declare for real
One suite, sold your way
Buy only what you need on the free Base, or take the all-in-one Suite.
Frequently asked
Does it need anything else?
Only the free ZRA Smart Invoice Base, which holds your VSDC connection, your TPIN and branch identity and the submission queue Pro supervises. It is deliberately independent of the document apps.
Does it work if I only have some of the apps?
Yes. The Declarations report inspects your database and unions only the sources that exist, and Run Sweepers only calls the sweepers whose apps are installed. Pro shows exactly what your setup declares.
What is an “ambiguous” entry on the Bot?
An attempt that may have reached the VSDC without a readable answer — a read timeout, a connection lost mid-flight, an HTTP 5xx. It is safe: the VSDC rejects a duplicate of the same stored transaction with result code 921 or 994, which the queue converges without registering it twice.
Does Test VSDC declare anything?
No. It runs a read-only code lookup keyed by your TPIN and branch against each active company’s VSDC, purely to prove the connection. Nothing is declared and nothing is changed.
Any limits or subscription?
None. One-time purchase, unlimited declarations, free updates as the ZRA Smart Invoice specification moves.
Ready for ZRA Smart Invoice compliance?
Install now, or write to us — we set up your Smart Invoice connection with you.
reach@aminitechsolutions.comZRA, Smart Invoice and the Zambia Revenue Authority name are the property of the Zambia Revenue Authority and are used here only to identify the system this connector integrates with. AminiTech Solutions is an independent software vendor and is not affiliated with, or endorsed by, the ZRA.
| Availability |
Odoo Online
Odoo.sh
On Premise
|
| Odoo Apps Dependencies |
Discuss (mail)
|
| Community Apps Dependencies | Show |
| Lines of code | 2210 |
| Technical Name |
aminitech_zra_pro |
| License | OPL-1 |
| Website | https://www.aminitechsolutions.com |
Odoo Proprietary License v1.0 This software and associated files (the "Software") may only be used (executed, modified, executed after modifications) if you have purchased a valid license from the authors, typically via Odoo Apps, or if you have received a written agreement from the authors of the Software (see the COPYRIGHT file). You may develop Odoo modules that use the Software as a library (typically by depending on it, importing it and using its resources), but without copying any source code or material from the Software. You may distribute those modules under the license of your choice, provided that this license is compatible with the terms of the Odoo Proprietary License (For example: LGPL, MIT, or proprietary licenses similar to this one). It is forbidden to publish, distribute, sublicense, or sell copies of the Software or modified copies of the Software. The above copyright notice and this permission notice must be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Please log in to comment on this module