| Availability |
Odoo Online
Odoo.sh
On Premise
|
| Odoo Apps Dependencies |
•
Invoicing (account)
• Sales (sale_management) • Purchase (purchase) • Discuss (mail) |
| Community Apps Dependencies | Show |
| Lines of code | 10421 |
| Technical Name |
eh_log_l10n_ae_customs |
| License | LGPL-3 |
| Website | https://www.erpheritage.com.au/ |
| Versions | 16.0 17.0 18.0 19.0 |
Logistics UAE Customs (Mirsal 2)
Plugs a working Mirsal 2 declaration adapter, UAE declaration types, and HS duty overlays into the logistics customs engine, so a fresh install can write and submit a UAE declaration on day one.
Why this module
Logistics UAE Customs (Mirsal 2)
A concrete Mirsal 2 adapter that actually serialises and parses
The module ships a real subclass of the suite BaseAdapter. It builds the documented Mirsal 2 declaration XML (parties, totals, lines with HS code, duty and VAT rates), dispatches over HTTPS through the engine transport, and parses the regulator response into a structured result with the regulator reference, status, and any field-level errors. Declaration submit, status query, and health check are all implemented.
UAE declaration types and HS overlays seeded on install
Seven UAE-scoped declaration types are appended to the universal seed: import to local from ROW, import to free zone, free zone to free zone, free zone to local, re-export consumed, temporary admission, and export to ROW. A starter UAE HS overlay carries duty and VAT defaults including excise-bearing goods. Enough to write a working declaration without hand-keying master data first.
Mock environment on install, so nothing calls the live regulator
The seeded Mirsal 2 profile defaults to the mock environment. A fresh deployment replays bundled fixtures deterministically and never accidentally hits the live Dubai Trade endpoint. Operators flip the environment to sandbox or production only after configuring the credential through the documented precedence chain (environment variable first, then encrypted config parameter), resolved per company.
Day in the life
From a typed declaration to a regulator reference, in one click
A broker fills a UAE import declaration in the customs engine: declaration type, parties with their tax registration numbers, lines with HS codes, customs value, duty and VAT. They submit. The Mirsal 2 adapter serialises the record into the documented XML, dispatches it, and parses the response. On acceptance the regulator-issued reference lands back on the declaration; on rejection the field-level error (for example an HS code not registered in the national tariff) is surfaced verbatim. Every request and response is logged as an append-only adapter message for audit. With the profile in mock mode, the whole loop runs offline against bundled fixtures, so the team can rehearse the flow before live credentials exist.
Edge cases
The cases most modules quietly ignore.
In the shipped code today, each one a place where a cheaper module silently does the wrong thing.
When Mirsal 2 rejects a declaration, the parser extracts each error code, message, and offending field (for example HS_CODE_NOT_FOUND pointing at Lines/Line[1]/HsCode) into a structured list rather than swallowing it, so the operator sees exactly which line failed.
A submit response that is not well-formed XML raises a typed AdapterValidationError with a clear message and the raw payload preserved in the message log, instead of a bare stack trace. The status query and health check parsers degrade gracefully to an unknown or OK status.
UAE free zone reality is modelled as distinct declaration types: import to free zone, free zone to free zone, and free zone to local. The free-zone-to-local and import-to-local types carry the deferment-required flag that triggers the engine guarantee-balance guard before submission.
The HS overlay seeds duty rates that reflect UAE excise reality (50 percent on carbonated and malt beverages, 100 percent on cigarettes) alongside zero-rated medicines, so the seeded tariff is a realistic starting point rather than a flat placeholder.
Building request headers without a configured API key does not crash in mock mode; the live call path fails fast with a clean credentials-missing message only when a real dispatch is attempted.
Credential lookup is company-scoped, so one Odoo install can dispatch to two companies Dubai Trade accounts from the same Mirsal 2 profile shape without cross-wiring keys.
What is inside
Built to do the job, end to end.
- Mirsal 2 adapter (adapters/mirsal2.py). Concrete BaseAdapter subclass, provider code mirsal2, API version pinned to 2.4. Implements serialize and parse for declaration_submit, declaration_status, and health_check, with per-message endpoint paths, HTTP method selection, and Bearer-token headers from the credentials helper. Registered in the suite adapter registry at import time.
- UAE declaration types (data). Seven country-scoped eh.log.customs.declaration.type records appended to the universal seed: import to local, import to free zone, free zone to free zone, free zone to local, re-export consumed, temporary admission, export to ROW. Two carry the requires_deferment flag that drives the engine pre-submission guard.
- UAE HS overlay (data). Eight UAE-scoped eh.log.customs.hs.code records with duty and VAT defaults, including smartphones, portable computers, vehicles, excise-bearing beverages and tobacco, medicines, and plastics. A starter set; production deployments append the full national tariff through a separate data load.
- Default Mirsal 2 profile (data). One eh.log.adapter.profile record seeded with environment set to mock, sandbox endpoint, API key auth, request timeout, retry attempts, and circuit-breaker threshold and cooldown, so the engine resilience controls are pre-tuned for this regulator.
- Fixture-backed tests (tests). A TransactionCase suite asserts registry registration, profile seeding, well-formed submit XML serialisation including every line, structured parse of the success and rejection fixtures, typed errors on unknown message types and malformed XML, and a full mock-mode round trip that writes an adapter message.
- Auto-install wiring (manifest). Depends on eh_log_base, eh_log_customs, and eh_log_l10n_ae, with auto_install true, so buyers who already run the customs engine and the UAE localisation pack get the Mirsal 2 wiring without an extra install step.
Honest about the edges
What this does not do, so nothing surprises you.
- This is an add-on, not a standalone app. The customs declaration model, its state machine, the deferment account and ledger, and the submit action all live in the parent customs engine (eh_log_customs); this pack supplies the UAE adapter and master data that those features run against.
- The Mirsal 2 adapter is implemented to the published documentation and verified offline with fixtures. Live sandbox and production verification are deferred until the operator configures real Dubai Trade credentials; the profile ships in mock mode for this reason.
- Implemented message types are declaration submit, status query, and health check. There is no amendment or cancellation message type, no pre-arrival notification, and no scheduled status-polling cron in this module.
- The HS overlay is a starter set of eight subheadings with default duty and VAT rates. It is not the full UAE national tariff; operators load the complete tariff and override per-line rates where the actual rate differs.
- The module ships no views, wizards, or new security-controlled models of its own. It is a data and adapter pack that surfaces through the parent engine screens.
- Default duty and VAT rates in the seed reflect common UAE values at time of authoring and are not a substitute for a current ruling from the customs broker or the regulator.
UAE customs Odoo, Mirsal 2 adapter, Dubai Trade integration, Dubai Customs declaration, Odoo 19 freight forwarding, customs declaration Odoo, UAE HS code tariff, FTA VAT customs, free zone declaration UAE, GCC customs Odoo, Federal Customs Authority, logistics customs engine, Odoo Community customs, deferment account customs, Mirsal declaration submission
Languages
Available in 19 languages
The interface ships translated out of the box. Switch language in Odoo and the fields, menus, and messages follow.
Please log in to comment on this module