[Docs D-19] Reference — Procurement routing codes (ip_invoice_meta)

[nielsdrost7]

Wiki section: Reference — v1.8.0 data fields
Tier: 3 — Reference
Publish when: InvoicePlane v1.8.0 is released
Related issue: #15 — Add procurement routing code fields to invoice record

---

What these fields are

Government e-invoicing in multiple countries requires 1–3 routing codes on the invoice to direct it to the correct department within the receiving entity. These codes come from the purchase order or contract — they belong on the invoice, not on the client record.

In InvoicePlane v1.8.0 they are stored in ip_invoice_meta as key→value pairs.

---

Canonical meta key names

All generators must use exactly these key names. Using consistent names ensures one invoice record exports correctly to all formats.

Meta key	Description
invoice_routing_code_1	Primary procurement routing code
invoice_routing_code_2	Secondary routing code
invoice_routing_code_3	Tertiary routing code (e.g. accounting / payment unit)

---

Per-standard mapping

Standard	routing_code_1	routing_code_2	routing_code_3	XML element
Germany XRechnung	Leitweg-ID (mandatory)	—	—	ram:BuyerReference / cbc:BuyerReference
Peppol BIS Billing 3.0	Buyer reference	—	—	cbc:BuyerReference
Italy FatturaPA B2G	CIG (tender/contract ID)	CUP (project ID)	—	Procurement section
Spain Facturae B2G	Managing body code (DIR3)	Processing unit code (DIR3)	Accounting office code (DIR3)	Administrative centre
France Chorus Pro	Engagement number	Service code	—	Service node

---

Reading from generators

// Read from ip_invoice_meta — no ip_invoices column involved
$code1 = $invoice_meta['invoice_routing_code_1'] ?? null;
$code2 = $invoice_meta['invoice_routing_code_2'] ?? null;
$code3 = $invoice_meta['invoice_routing_code_3'] ?? null;

When all three keys are absent or null, no routing elements are emitted in the XML output.

---

XRechnung mandatory enforcement

For the XRechnung generator specifically, invoice_routing_code_1 (Leitweg-ID) is mandatory. If it is null or absent from ip_invoice_meta, the generator returns a validation error and produces no XML file.

---

UI location

In InvoicePlane v1.8.0: Invoice create/edit → E-Invoicing section (collapsible)

Fields:

• Routing code 1
• Routing code 2
• Routing code 3

Labels are intentionally generic. Tooltip / help text explains the mapping per standard (Leitweg-ID for XRechnung, CIG/CUP for FatturaPA, etc.).

The E-Invoicing section is shown automatically when the selected client has e-invoicing active.

---

Validation rules

Rule	Detail
Required at save	No — all three are optional when saving the invoice
Required at generation	invoice_routing_code_1 is mandatory for XRechnung; generation fails if absent
Format	Freetext — no format enforced at save time
Max length	100 characters each

This separation allows saving an incomplete draft before the procurement routing code is known (e.g. before receiving the purchase order). The XRechnung generator rejects generation — not the save action — when invoice_routing_code_1 is missing.

---

Persistence

All three codes are meta keys in ip_invoice_meta — they are not columns on ip_invoices. The standard invoice save() does not persist them automatically.

The e-invoicing controller must perform an explicit upsert after the main invoice save:

foreach (['invoice_routing_code_1', 'invoice_routing_code_2', 'invoice_routing_code_3'] as $key) {
    $value = $input[$key] ?? null;
    if ($value !== null && $value !== '') {
        $this->db->query(
            'INSERT INTO ip_invoice_meta (invoice_id, meta_key, meta_value) VALUES (?, ?, ?)
             ON DUPLICATE KEY UPDATE meta_value = VALUES(meta_value)',
            [$id, $key, $value]
        );
    }
}

When loading an invoice for editing, the controller must read these keys back from ip_invoice_meta and pass them to the view separately from the main invoice object.

---

Null behaviour

When all three meta keys are absent or null:

• No routing elements are emitted in UBL or CII output
• Generation succeeds without error (except XRechnung — see above)

---

Migrated from InvoicePlane/InvoicePlane-e-invoices#43.