ZRA Smart Invoice Base — the required configuration layer
The free configuration layer for the AminiTech ZRA Smart Invoice suite for Zambia. It stores your VSDC connection settings, runs the device initialization handshake, validates customer TPINs and carries the transmission on/off switch — and nothing else: on its own it does NOT invoice, sell or fiscalise anything. It talks straight to the VSDC you run yourself, so your tax data never passes through anyone else’s service. Install a paid app (Invoicing, POS, Stock…) to actually declare documents to the ZRA.
This is a configuration base, not a standalone app. Installed on its own it only adds the ZRA Smart Invoice connection settings, the device key store and the submission queue — it does not invoice, run a point of sale, move stock or declare anything to the ZRA. Those live in the paid apps below, which all require this base.
Configure once — the paid apps do the rest
The Base is where you set the ZRA Smart Invoice suite up and then leave it alone. It holds the VSDC connection (sandbox and production), your taxpayer identity (TPIN, branch, device serial), the one-click device initialization, a connection test, customer-TPIN validation against the ZRA, and the single switch that turns transmission on or off. It declares nothing by itself — add ZRA Invoicing, POS or Stock to actually send documents, and they run on the connection you configured here.
Your VSDC, your data
Point the connector at the Smart Invoice VSDC you run — typically a Java bridge on http://localhost:8080/zravsdc — or at the ZRA’s hosted OSDC. The JSON goes from your database to that endpoint and nowhere else: no intermediary SaaS, no third-party API holding your declarations.
Device init & TPIN checks
Enter your 10-digit TPIN, the 3-character branch ID (headquarters is 000) and the device serial, then click Initialize Device — selectInitInfo returns your SDC ID and MRC No and a green banner confirms activation. Any customer’s TPIN can be validated against the ZRA in one click.
One switch to send
A single Transmission Control radio decides whether declarations leave your database — Active sends in real time, Paused holds them. It is set per company, so a group can run one entity live while another is still validating on the sandbox. That is the whole of what the free Base does: connect, identify, and switch on.
Everything you configure — and nothing you don’t
Turn ZRA transmission on or off without touching a document
A single Transmission Control radio on the ZRA Smart Invoice settings page decides whether declarations leave your database: “Active — send in real time” or “Paused — accumulate in queue”. It is set per company, so a group with several Zambian entities can run one live while another is still validating on the sandbox. An “Open Queue” button sits right next to it so you can jump from the switch to the documents it governs. Nothing is ever dropped when you flip it — the setting only decides whether the queue drains.
Pause while the VSDC is down, then flush the backlog in order
Set transmission to “Paused” and a “Resume & Flush Queue” button appears. While paused, every declarable document still registers its queue entry — invoicing keeps working normally — but nothing is transmitted. One click then flips the company back to Active and immediately sweeps the whole backlog, sending entries oldest first so the VSDC receives them in a continuous, ordered sequence. That ordering is not cosmetic: the VSDC expects an unbroken series, and flushing chronologically is what keeps it unbroken.
Prove the whole flow on the ZRA sandbox before you go live
An Active Environment radio switches the connector between Sandbox and Production, and each keeps its own VSDC URL, so you never retype a thing to go live. A blue banner spells out that sandbox documents are not legally declared; an amber one warns that Production declares for real. The active URL is computed from the environment you picked, so there is no way to declare a live invoice against your test bridge by accident. Every queue entry also stores the environment it was created under, which means a sandbox declaration is still identifiable months later.
TPIN, branch and device serial in one place
The Device Identity block holds exactly what the VSDC keys every call on: your 10-digit ZRA TPIN, the 3-character branch ID (bhfId — headquarters is 000) and the device serial (dvcSrlNo) you registered on the Smart Invoice Taxpayer Portal. The TPIN falls back to the company’s Tax ID if you already captured it there, so it is never keyed twice. The device serial is restricted to system administrators and is transmitted only during initialization — business calls carry just the TPIN and branch. A pre-flight check lists anything still missing before a declaration is attempted, so a half-configured company holds its documents instead of firing rejects at the VSDC.
Initialize Device runs the VSDC init handshake for you
Press “Initialize Device” and the connector posts your TPIN, branch and device serial to /initializer/selectInitInfo. The VSDC answers with your activation values — SDC ID and MRC No — plus the communication, internal and signing keys, and a green “Device activated” banner appears showing the SDC ID and MRC No inline. The returned last-invoice and last-receipt counters are captured at the same time and used to seed your numbering, so a device that already declared under another system continues its series rather than restarting it. The keys are stored on the company and readable only by system administrators.
Confirm the VSDC is reachable before you declare anything
A “Test Connection” button fires a lightweight code lookup keyed by your TPIN and branch, and reports back in plain words. Three outcomes are distinguished rather than lumped together: the VSDC answered and accepted you, the VSDC answered but rejected the call with a result code and message, or the VSDC could not be reached at all. That distinction is the difference between a firewall problem and a credentials problem — and it saves the afternoon you would otherwise spend guessing which one you have.
Validate a buyer’s TPIN against the ZRA in one click
Every contact gains a “Check TIN (ZRA)” button that runs a selectCustomer lookup against the ZRA. The result is written straight onto the contact: a TIN Status badge (green Valid, red Invalid), the taxpayer name the ZRA holds for that TPIN, and the date it was checked — plus a chatter note recording the verdict. Confirming that the name on the ZRA register matches the customer in front of you is a thirty-second check that prevents a rejected declaration later. This is one of the things the free Base gives you outright.
No crypto to configure, because the VSDC holds the keys
The Zambian design puts the device keys inside the VSDC, so the connector does not sign or encrypt anything client-side — business calls carry your TPIN and branch in the JSON body and nothing else. That is deliberate and it matches the ZRA-official integration; there is no key material to paste, rotate or lose. For the rare deployment that expects the communication key echoed back, an “Echo Communication Key” tick box adds it to every call — off by default, and to be enabled only if your sandbox rejects calls without it.
When the spec disagrees with itself, you win the argument
The ZRA’s own materials are inconsistent about endpoint pluralization — saveItem against saveItems, savePurchase against savePurchases — and the wrong form simply returns 404. Rather than pretend one spelling is canonical, every path in the connector is overridable per company through a small JSON map, because the VSDC actually provisioned to you is the only authority that matters. Point one key at the right path and the rest keep their built-in defaults. If the JSON is malformed the connector logs it and falls back to the defaults instead of breaking, and a wrong path shows up as an ordinary failed queue entry you can read and fix.
A default UNSPSC class so lines are always coherent
The VSDC wants an item classification code (itemClsCd) on every line. The Base carries a company-level default — 99012000 out of the box — used for any product with no explicit ZRA class of its own, so an invoice-only install still declares complete, coherent lines from day one. The same block builds the rest of the item identity (code, name, barcode, packaging and quantity units) with sane fallbacks, and per-product classes override it when you add the Stock app.
Three roles, and credentials only administrators can see
The Base installs a dedicated “ZRA Smart Invoice (Zambia)” privilege with three nested roles: User (reads the queue, checks TPINs), Manager (also sends, retries, resets, cancels and deletes entries) and Administrator (the only role that sees the ZRA settings page at all). The device serial, the communication, internal and signing keys and the endpoint overrides are restricted further, to system administrators — so a clerk can clear a backlog without ever reading your VSDC credentials. A multi-company record rule keeps each company’s queue to itself.
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
What do I actually get for free?
The VSDC connection settings, the device initialization handshake, customer TPIN validation against the ZRA, and the shared engine the paid apps use — the VSDC client and the self-healing submission queue. The Base does not declare invoices, sales or stock on its own; add a paid app for that.
Is it really free, and is it configuration-only?
Yes on both. The Base is the shared engine and costs nothing, and it is configuration-only — it never declares a document by itself. You only pay for the document apps you need.
Do I need a VSDC before I install this?
Yes. ZRA Smart Invoice is reached through a VSDC — typically a Java bridge you run on your own server, for example at http://localhost:8080/zravsdc — or through the ZRA’s hosted OSDC if that is how you were provisioned. Register your device on the Smart Invoice Taxpayer Portal to get your TPIN, branch and device serial, point the connector at your VSDC and click Initialize Device.
Does it encrypt or sign anything?
No, and that is correct for Zambia: the VSDC holds the device keys and does that work. Business calls carry your TPIN and branch in the JSON body — there is no key material for you to paste, rotate or lose. An optional setting echoes the communication key back for deployments that expect it.
Where does my data go?
From your database straight to the VSDC or OSDC endpoint you configured, and nowhere else. No intermediary service sits between you and your own tax declarations.
Does it handle several companies or branches?
Yes. Every setting — transmission mode, environment, VSDC URL, TPIN, branch ID, device serial — is per company, each company keeps its own number series, and a record rule keeps each company’s queue to itself. The 3-character branch ID (000 for headquarters) travels on every call.
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)
|
| Lines of code | 1564 |
| Technical Name |
aminitech_zra_base |
| 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