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: every content rule of the official CEN validation artefact (BR-01 … BR-65), 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

Area	Business Terms / Rules
Document header	BT-1, BT-2, BT-3, BT-5, BT-9, BT-10, BT-13, BT-22, BT-24
Seller / Buyer (BG-4 / BG-7)	BT-27, BT-31, BT-40, BT-44, BT-48, BT-55
Invoice line (BG-25)	BT-126, BT-129, BT-130, BT-131, BT-146, BT-151, BT-152, BT-153
VAT breakdown (BG-23)	BT-116, BT-117, BT-118, BT-119, BT-120, BT-121
Document totals (BG-22)	BT-106 … BT-115
Content rules	BR-01 … BR-65 (all content rules of the official CEN EN 16931 validation artefact)
Calculation rules	BR-CO-10 … BR-CO-17
VAT category rules	BR-S, BR-Z, BR-E, BR-AE, BR-G, BR-IC, BR-O
Code-list rules	BR-CL-01, BR-CL-04, BR-CL-16, BR-CL-17, BR-CL-23

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.

Which Pokutsoft apps build on it (checked 2026-09-26): our EN 16931 XML generators einvoice_outbound_dispatcher, peppol_invoice_pdf_embed, peppol_outbound_queue_pro and peppol_pint_base currently build their XML from their own mapping and do not call this model yet. Any generator, including your own, can use it through the hook above.

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, Odoo 19 and Odoo 20, Community base (account only).
• Multi-currency aware, multi-rate, allowance/charge aware, credit-note aware.

Screenshots

Semantic Documents