EN 16931 Global Semantic Invoice Model

The shared, normalised EN 16931 invoice data model every e-invoicing format generator builds on

EN 16931 is the European Norm that defines the semantic data model of an electronic invoice — the ordered set of Business Terms (BT-1 … BT-150) grouped into Business Groups (BG-1 … BG-25). Every modern e-invoicing regime (Peppol BIS Billing 3.0, France Factur-X, Germany XRechnung, Italy, Spain, the Nordics and more) is a syntax binding of this one semantic model.

This module is the foundation layer: it normalises any Odoo customer or vendor invoice into the EN 16931 semantic model once, computes the VAT breakdown and totals exactly as the standard prescribes, and validates the result against the published EN 16931 business rules. Downstream format-generator apps (UBL 2.1, UN/CEFACT CII / Factur-X, national JSON regimes) then consume one normalised representation instead of each re-reading account.move and re-deriving the maths.

What it does

Semantic normalisation (BT / BG)

Maps the seller and buyer parties (BG-4 / BG-7), postal addresses (BG-5 / BG-8), invoice lines (BG-25) with their item and price blocks, document-level allowances and charges (BG-20 / BG-21), payment instructions (BG-16) and the preceding invoice reference (BG-3) into a single, framework-free model.

VAT breakdown & totals

Aggregates the lines into the EN 16931 VAT breakdown (BG-23) per category and rate, and derives the document totals (BG-22) — line total (BT-106), allowance/charge totals, tax-exclusive (BT-109), total VAT (BT-110), tax-inclusive (BT-112) and amount due (BT-115).

Currency-correct rounding

Commercial (half-up) rounding to each currency's ISO 4217 minor units — 2 decimals for EUR/USD, 3 for KWD/BHD/OMR, 0 for JPY/KRW — so the computed amounts match what the standard expects rather than Python's banker's rounding.

EN 16931 business rules

A real, published rule engine: content rules (BR-1 … BR-67), calculation rules (BR-CO-10 … BR-CO-17) and the per-category VAT rules (BR-S, BR-Z, BR-E, BR-AE, BR-G, BR-IC, BR-O) plus the code-list rules (BR-CL-*). Every violation reports its real rule code, the Business Term, a message and a severity.

Code lists

Ships the EN 16931-restricted code lists: UNTDID 5305 VAT categories, UNTDID 1001 document types, UNTDID 4461 payment means, UN/ECE Rec 20 units of measure, ISO 4217 currencies and ISO 3166 countries — with smart resolution of the VAT category from the rate, tax name and country pair.

Inspect & export

Each invoice gets a persisted EN 16931 document with its VAT breakdown, totals and validation issues, plus a one-click export of the canonical semantic model as JSON — the exact payload a downstream format generator consumes.

EN 16931 coverage

How it fits

Install this once and point your country/format-generator apps at it. The model exposes a clean Python hook (move._en16931_build_semantic()) returning the normalised SemanticInvoice, and the persisted document carries the snapshot, the VAT breakdown, the totals and the validation report. No country logic lives here — it is the jurisdiction-agnostic semantic core of every binding.

Scope & boundary: this module produces and validates the EN 16931 semantic model. It does not transmit invoices or claim any accreditation; format serialisation and BYOK transmission belong to the downstream generator/transport apps.

Highlights

• Framework-free, unit-tested core services (model, rounding, calculation, rules, mapper).
• Deterministic, idempotent VAT breakdown and totals computation.
• Real published code lists — nothing invented.
• Works on Odoo 18 and Odoo 19, Community base (account only).
• Multi-currency aware, multi-rate, allowance/charge aware, credit-note aware.

Screenshots

Semantic Documents