ZRA Smart Invoice — Importers (Zambia)
by AminiTech Solutions https://www.aminitechsolutions.com$ 488.00
ZRA Smart Invoice Importers — reconcile what customs cleared
For importers: pull the goods declared under your TPIN at customs straight from your VSDC (selectImportItems), link each customs line to one of your products, and approve it (updateImportItems, imptItemSttsCd 3) so it becomes a registered ZRA item you can actually sell. HS code, declaration reference, origin, quantities and the foreign-currency invoice values arrive exactly as customs declared them. Builds on ZRA Smart Invoice Stock.
One-time purchase · unlimited documents · free updates on every ZRA Smart Invoice spec change. Requires the free ZRA Smart Invoice Base.
Customs declared it — now make it sellable
Zambia’s Smart Invoice will not let you sell a good the ZRA does not know, and an imported good arrives at customs as a line under your TPIN rather than as an item in your catalogue. This app closes that gap: one click pulls every imported line your VSDC knows about into a reviewable register, you link each line to the product it really is, and Approve pushes it back as imptItemSttsCd 3. The call goes to your own VSDC or OSDC — no third-party SaaS sits between your customs data and the ZRA.
Pull your customs lines
Fetch from ZRA calls /imports/selectImportItems and lands every imported line declared under your TPIN in a register you can read, filter and group — taskCd, declaration number, HS code, quantities and supplier, exactly as customs recorded them.
Link, then approve
Point each customs line at the product it really is and press Approve at ZRA: /imports/updateImportItems goes out with imptItemSttsCd 3, the item class and your product’s itemCd, turning a customs line into a registered ZRA item.
Foreign-currency detail kept
The invoice amount, currency code and exchange rate customs used (invcFcurAmt / invcFcurCd / invcFcurExcrt) are stored on every line beside the package and quantity units — the numbers you need when the ZRA asks how a landed cost was arrived at.
Every imported line, from fetch to approved
One button pulls every imported line under your TPIN
A Fetch from ZRA button sits in the header of the ZRA Imported Items list and calls /imports/selectImportItems on your VSDC with a full-history watermark, so nothing declared under your TPIN is left behind on the first run. Every line comes back with its taskCd, declaration number and date, item sequence, HS code, item name, quantities and supplier. A notification tells you exactly what happened — how many lines were new and how many were updated — rather than leaving you to guess. Run it again whenever a new consignment clears and the register catches up.
Your customs lines as a working list, not a PDF
The register shows one row per imported line: declaration date, declaration number, item sequence, HS code, item name, quantity and quantity unit, with supplier name, foreign-currency amount and currency available as optional columns you can toggle on. The state is a colour-coded badge — green once approved, red when the VSDC refused it, muted when customs cancelled the line. The list is editable in place, so you can work straight down a consignment without opening a single form. It opens filtered to Fetched, because those are the lines that need you.
The whole customs identity of the line, on the record
Open any line and the Customs Declaration block holds precisely what the ZRA holds: the task code (taskCd), the declaration number (dclNo) and date (dclDe), the item sequence, the HS code (hsCd), the customs status and both country codes — origin (orgnNatCd) and export nation (exptNatCd). Every field is read-only, because these are customs’ facts and not yours to edit. The customs status itself is the ZRA’s own imptItemSttsCd vocabulary: Unsent, Waiting, Approved or Cancelled, so you always know where a line stands before you touch it.
Packages, quantities and the foreign-currency invoice
The Quantities & Value block carries the package count and its unit (pkg / pkgUnitCd), the quantity and its unit (qty / qtyUnitCd), then the commercial detail: the invoice amount in foreign currency, the currency code and the exchange rate customs applied (invcFcurAmt, invcFcurCd, invcFcurExcrt). The supplier name and the clearing agent name (spplrNm / agntNm) sit alongside them. Nothing is re-derived or re-keyed — a K-denominated books figure and a USD customs invoice can be reconciled from the same record.
Say which of your products this customs line actually is
The Link & Approve block is where the work happens: pick the product in your catalogue that this customs line corresponds to. That link is what lets the app send your own itemCd back to the ZRA, and it is why the customs line stops being an orphan and becomes stock you can invoice. The product field is editable directly in the list too, so a twenty-line consignment can be matched in one pass down the register without opening twenty forms.
The UNSPSC class resolves itself, and you can override it
Every approval needs an item class (itemClsCd), and the app finds it for you through a three-step fallback: the class customs already put on the line, then the ZRA item class set on the linked product, then your company’s default item class — landing on 99012000 only if nothing else is set. The resolved value sits on the record as an editable field, so when customs classified a line differently from the way you registered the product, you decide which one goes back. No blank itemClsCd ever reaches the VSDC.
One click converts a customs line into a registered item
Approve at ZRA posts /imports/updateImportItems with the customs identity (taskCd, dclDe, itemSeq, hsCd), the resolved item class, your product’s ZRA item code and imptItemSttsCd 3 — the ZRA’s code for an approved imported item. If the linked product has no ZRA item code yet, one is generated to the compliant pattern before the call goes out, so you never have to prepare the product first. The record walks a Fetched → Approved status bar, and the customs status on the line is updated to 3 to match what the ZRA now holds.
Work down a consignment from the list
Every row in the register carries its own Approve action with a tick icon, and it disappears the moment the line is approved — so an already-approved line cannot be pushed twice by a stray click. Select the lines you have matched and approve them one after another straight from the list, without ever leaving it. Lines that are already approved are silently skipped when a selection includes them, so a bulk pass over a mixed consignment does the right thing.
It refuses to send a declaration that would be rejected
Two checks run before anything reaches the VSDC. Approve a line with no product linked and the app stops with a plain message naming the line, because the ZRA needs an itemCd and there is nothing honest to send without one. And if the company’s ZRA settings are incomplete, the app names exactly what is missing — TPIN, Branch ID, Smart Invoice URL or Device Serial — rather than firing a call that will fail. Fetch is guarded the same way, so a half-configured company gets an explanation instead of an error.
The response is kept, including the ones that mean success
Whatever your VSDC replies is written to the ZRA Response box on the record, which stays hidden while there is nothing to say. Two result codes are treated as success rather than failure: 921 (declared data cannot be re-received) and 994 (overlapped data) both mean the ZRA already holds this exact line, so the app converges them to Approved instead of looping on a line that is genuinely done. Anything else marks the line Failed with the VSDC’s own words, ready to fix and re-approve.
Re-running the sync updates lines instead of duplicating them
Each imported line is identified by the combination of company, task code, declaration number and item sequence — and that combination is enforced by a database constraint, not just by good intentions. So Fetch from ZRA can be run as often as you like: a line already in the register is updated in place with whatever customs now says, and only genuinely new lines are created. Your product links and approvals survive a re-sync, which matters when a declaration is amended after you have already matched half of it.
Search by HS code or declaration, group by status
The search bar takes the item name, the HS code, the declaration number or the supplier, so the one line a clearing agent is asking about is seconds away. One-click filters isolate Fetched, Approved or Failed, and Group By collapses the register by Status or by Declaration — group by declaration and each consignment becomes its own block with its own count, which is exactly how an importer thinks about the work. The register lives under Inventory as ZRA Imported Items.
Who may look, and who may approve
The app uses the three roles under the ZRA Smart Invoice (Zambia) privilege that the free Base ships. A ZRA User sees the register and can read every customs line; the Fetch from ZRA and Approve actions are reserved for a ZRA Manager, and only a Manager can edit or remove a line. So a warehouse clerk can check what customs declared for a consignment without being able to tell the ZRA that an item is approved.
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 does this need to run?
The free ZRA Smart Invoice Base (your VSDC connection, the TPIN and branch identity and the submission engine) and the ZRA Smart Invoice Stock app, which supplies the product-level ZRA item identity this app links your customs lines to.
Where do the imported lines come from?
From your own VSDC. Fetch from ZRA calls /imports/selectImportItems with your TPIN and branch, and the VSDC returns the goods declared at customs under that TPIN. Nothing is typed in by hand and no third-party service sits in between.
What does Approve actually change at the ZRA?
It posts /imports/updateImportItems with imptItemSttsCd 3, linking the customs line to your item code and its UNSPSC item class. That is what converts a customs-declared good into a registered ZRA item you can put on a Smart Invoice.
What if I fetch the same consignment twice?
Nothing breaks. Lines are keyed on company, task code, declaration number and item sequence — enforced in the database — so a re-fetch updates the existing rows and keeps your product links and approvals.
Any limits or subscription?
None. A one-time purchase, unlimited declarations and imported lines, and 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 |
•
Inventory (stock)
• Purchase (purchase) • Discuss (mail) • Invoicing (account) |
| Community Apps Dependencies | Show |
| Lines of code | 2471 |
| Technical Name |
aminitech_zra_importers |
| 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