api/documentation/economic/invoice-template-audit.md

E-conomic Invoice Template Audit (TRU-197)

Status: Complete (no live call — credentials unavailable in this environment) Date: 2026-08-17 Scope: Audit of the e-conomic invoice layouts available in the copenhagentruckwash/api backend's e-conomic agreement, and the rationale for the two-layout strategy (one for invoices with itemized discounts, one for invoices without).

Primary files audited:

• services/nginx/app/modules/economic/endpoints/economic_layouts_endpoint.php (GET /layouts)
• services/nginx/app/modules/economic/endpoints/invoices/economic_invoices_drafts_endpoint.php (draft invoice create — uses layout.layoutNumber)
• services/nginx/app/modules/economic/invoices/draft/economic_invoice_draft_mo.php (resolveLayoutNumber())
• services/nginx/app/objects/collected_order_invoices_o.php (resolveInvoiceLayoutNumber())
• services/nginx/app/modules/economic/config/economic_invoice_layout_c.php (invoiceLayoutNumber config var, default 1)
• services/nginx/app/modules/economic/config/economic_invoice_discount_layout_c.php (invoiceDiscountLayoutNumber config var, default 1)
• services/nginx/app/routes/economicLayoutsRoute.php (superuser /economic/layouts proxy)

---

TL;DR — Recommendation

Variant	Layout (configured)	Env-var name to set	Layout intent
With discounts	invoiceDiscountLayoutNumber (currently 6 in SuperuserSystemStatusServiceTest fixtures; site default 1)	ECONOMIC_LAYOUT_WITH_DISCOUNTS	Itemized lines with the Rabat line clearly visible (negative unitNetPrice for TotDiscount product)
Without discounts	invoiceLayoutNumber (currently 1 in tests and config default)	ECONOMIC_LAYOUT_WITHOUT_DISCOUNTS	Standard invoice, no discount clutter

The two layout numbers above are placeholders to be confirmed by the account admin in e-conomic. They are written into the runtime config variables invoiceLayoutNumber and invoiceDiscountLayoutNumber (see env-var mapping section below).

---

1. Why a 2-layout strategy is needed

The copenhagentruckwash/api backend already has plumbing for two invoice layouts (see §4 below). The trigger to pick a layout is whether the invoice contains an itemized discount line (a line with product.productNumber = "TotDiscount" and a negative unitNetPrice, as produced by the Rabat aggregator in economic_invoice_draft).

When such a line is present, the system routes the invoice through invoiceDiscountLayoutNumber; otherwise it falls back to invoiceLayoutNumber. The audit goal is to find the two layouts in e-conomic that match these two intents (clean invoice vs. one that shows discounts itemized).

---

2. Available e-conomic API for layouts

2.1 Endpoint

GET https://restapi.e-conomic.com/layouts

2.2 Auth headers (same as every other e-conomic call)

X-AppSecretToken:        <ECONOMIC_API_APP_SECRET_TOKEN>
X-AgreementGrantToken:   <ECONOMIC_API_APP_ACCESS_GRANT>
Content-Type:            application/json

2.3 Response shape

The endpoint already exists in the codebase at services/nginx/app/modules/economic/endpoints/economic_layouts_endpoint.php, and is exposed to superusers via services/nginx/app/routes/economicLayoutsRoute.php (GET /economic/layouts). The PHP wrapper returns the raw JSON decoded into a stdClass:

{
  "collection": [
    {
      "layoutNumber": 1,
      "name":         "Standard",
      "deleted":      false,
      "self":         "https://restapi.e-conomic.com/layouts/1"
    },
    {
      "layoutNumber": 12,
      "name":         "Rabat variant",
      "deleted":      false,
      "self":         "https://restapi.e-conomic.com/layouts/12"
    }
  ]
}

The minimal documented fields per layout are:

Field	Type	Description
layoutNumber	integer	Unique identifier of the layout. This is the value that goes in layout.layoutNumber on /invoices/drafts.
name	string	Display name configured in e-conomic (Settings → Design and Layouts). Up to ~100 chars.
deleted	boolean	true = layout is deleted and cannot be used. Filter these out.
self	string (uri)	Link reference to the layout resource (for GET /layouts/:layoutNumber).

Note: e-conomic layouts do not have an isDefault field. The "default" concept in e-conomic is per-customer-group, not global. To find the agreement default, query /customers?filter=... and look at the layout referenced on each customer group's default. For our purposes, the admin picks the two layout numbers we want to use, so no defaulting logic is required.

2.4 Example curl (run with real creds)

curl -sS -X GET "https://restapi.e-conomic.com/layouts" \
  -H "X-AppSecretToken:      $ECONOMIC_API_APP_SECRET_TOKEN" \
  -H "X-AgreementGrantToken: $ECONOMIC_API_APP_ACCESS_GRANT" \
  -H "Content-Type:          application/json" \
  | jq '.collection[] | {layoutNumber, name, deleted}'

2.5 Example Python (run with real creds)

import os, requests
r = requests.get(
    "https://restapi.e-conomic.com/layouts",
    headers={
        "X-AppSecretToken":      os.environ["ECONOMIC_API_APP_SECRET_TOKEN"],
        "X-AgreementGrantToken": os.environ["ECONOMIC_API_APP_ACCESS_GRANT"],
        "Content-Type":          "application/json",
    },
    timeout=15,
)
r.raise_for_status()
for layout in r.json()["collection"]:
    print(layout["layoutNumber"], layout["name"], "deleted=" + str(layout["deleted"]))

---

3. Live call — was it made?

No. This audit was run in a sandbox that does not have ECONOMIC_API_APP_SECRET_TOKEN or ECONOMIC_API_APP_ACCESS_GRANT set (the only available secrets are the GitHub PAT, Linear API key, and Slack tokens). A live GET /layouts call would have returned 401 Unauthorized at best, and would have polluted the e-conomic log with a noisy failed request at worst. The two layout numbers used by the test fixtures (SuperuserSystemStatusServiceTest) — 1 and 6 — are taken as the configured values that need to be confirmed by the e-conomic account admin and, if changed, written into the e-conomic module config (see §4.3 env-var mapping).

To complete the live portion of the audit, run the curl above from a machine that has the credentials (e.g. a developer laptop or a CI runner with the secrets mounted). Paste the output into §6 of this doc and commit.

---

4. Current code state

4.1 Where layouts are read at runtime

• services/nginx/app/modules/economic/invoices/draft/economic_invoice_draft_mo.php — resolveLayoutNumber() (line 115): returns either invoice_layout or invoice_discount_layout depending on whether the draft contains a discountPercentage > 0 product line.
• services/nginx/app/objects/collected_order_invoices_o.php — resolveInvoiceLayoutNumber() (line 673): same logic for collected (batched) invoices. Trigger is hasDiscountedIncludedInvoiceItems().
• services/nginx/app/modules/economic/endpoints/invoices/economic_invoices_drafts_endpoint.php — direct /invoices/drafts create with an explicit layoutNumber arg (default = invoice_layout).

4.2 Where layouts are configured

• services/nginx/app/modules/economic/config/economic_invoice_layout_c.php registers the invoiceLayoutNumber module config variable (default 1, required). This is the "no-discount" layout.
• services/nginx/app/modules/economic/config/economic_invoice_discount_layout_c.php registers the invoiceDiscountLayoutNumber module config variable (default 1, optional, must be > 0 to enable). This is the "with-discount" layout.

Both values are admin-editable at runtime via the standard module config admin UI. The system status probe also lists them as required: services/nginx/app/classes/superuser_system_status_service.php (line 866 key invoiceDiscountLayoutNumber; line 893-894 of the test fixture uses 1 / 6).

4.3 Env-var mapping

The module config values are stored in the module_config DB table, not in environment variables. The contract is:

Runtime value	Source	Where it's set
invoiceLayoutNumber (without discounts)	Admin-set via UI	services/nginx/app/modules/economic/config/economic_invoice_layout_c.php
invoiceDiscountLayoutNumber (with discounts)	Admin-set via UI	services/nginx/app/modules/economic/config/economic_invoice_discount_layout_c.php

The ECONOMIC_API_APP_* env vars are the credentials for talking to e-conomic — they have no relationship to the layout-number config values.

That said, the task description asks for two env-var-style placeholders. We will add the following module-config aliases (constants only, no runtime logic yet) to economic_layout_selector.php (see §7) so that an operator or a deployment automation can refer to them by name:

Module-config constant	Friendly alias env-var-style name	Meaning
invoiceLayoutNumber	ECONOMIC_LAYOUT_WITHOUT_DISCOUNTS	"Clean" layout, no discount clutter
invoiceDiscountLayoutNumber	ECONOMIC_LAYOUT_WITH_DISCOUNTS	Layout that itemizes the Rabat line clearly

If the deployment process is ever updated to read these from env vars instead of the module-config DB, the constant names in economic_layout_selector.php are the right place to wire that up.

4.4 Existing PRs and related work

• PR #391 — the original sanitization fix (TRU-188 family). Adds the economic_export_sanitizer class and per-field sanitization on the draft invoice lines, recipient block, and references.
• TRU-193 — the second audit, this time on extra fields and preflight validation. See documentation/economic/export-field-audit.md for the full sanitization audit.
• TRU-197 (this audit) — picks the two specific layout numbers to use, one for with-discount and one for without-discount, and documents how to find them in e-conomic.

---

5. Visual differences (to be verified)

Layouts in e-conomic are visually configured in the Settings → Design and Layouts UI; the REST API only exposes their names and numbers, not their visual representation. From the existing example invoice (services/nginx/app/routes/orderInvoicesRoute.php line 199 sample payload), a booked invoice with discounts has this structure:

lines: [
  { lineNumber: 1, sortKey: 1, description: "[ 01/12/2025 00:00 PLENO #38679 ]" },
  { lineNumber: 2, sortKey: 2, description: "Reference:" },
  { lineNumber: 3, sortKey: 3, description: "# Vaskeabonnementer" },
  { lineNumber: 4, sortKey: 4, description: "Trækker", quantity: 2, unitNetPrice: 579, vatRate: 25, totalNetAmount: 1158, product: {productNumber: 1} },
  { lineNumber: 5, sortKey: 5, description: "Reference:" },
  { lineNumber: 6, sortKey: 6, description: "# EH89254" },
  { lineNumber: 7, sortKey: 7, description: "Spot Free- Lastbil", quantity: 2, unitNetPrice: 39, vatRate: 25, totalNetAmount: 78, product: {productNumber: 33} },
  { lineNumber: 8, sortKey: 8, description: "Reference:" },
  { lineNumber: 9, sortKey: 9, description: "# EH89254" },
  { lineNumber: 10, sortKey: 10, description: "Rabat", quantity: 1, unitNetPrice: -542, vatRate: 25, totalNetAmount: -542, product: {productNumber: "TotDiscount"} },
  { lineNumber: 11, sortKey: 11 }
]

This invoice was booked with layoutNumber = 12 (per the sample in orderInvoicesRoute.php). Layout #12 is therefore a known historical choice; it predates the audit and is not necessarily the final answer.

The visual difference between layouts 1 (default) and 12 (discount) is to be verified by exporting a sample invoice in each layout. The relevant template knobs in e-conomic are:

• Whether the discount column is rendered.
• Whether the Rabat line is broken out vs. folded into the per-product discountPercentage.
• The number of text/separator lines (the two layouts may differ in how much spacing they show between products).

These are UI choices in the e-conomic admin; the backend has no insight into which lines the layout chooses to render.

---

6. Live-call results — TO BE FILLED IN

Paste the output of the curl in §2.4 below, then commit.

# layoutNumber  name                          deleted
# ------------  ----------------------------  -------
# 1             Standard                      false
# 12            Rabat variant                 false
# ...

Once filled in, mark the audit as Verified — live call and add a row per layout to the table in §3.1 if the layout count is larger than expected.

---

7. Files added in this PR

File	Purpose
documentation/economic/invoice-template-audit.md	This document.
services/nginx/app/classes/economic_layout_selector.php	Skeleton class exposing the two layout-number constants (LAYOUT_WITHOUT_DISCOUNTS, LAYOUT_WITH_DISCOUNTS) and a name() helper. No runtime logic yet — the two existing resolveLayoutNumber() / resolveInvoiceLayoutNumber() call sites continue to read the module-config values directly. The skeleton is in place so that a follow-up PR can switch those call sites to EconomicLayoutSelector::LAYOUT_* without renaming the constants.

The economic_layout_selector.php skeleton is intentionally empty of logic per the task description ("skeleton — just the constants, no logic yet"). Wiring it up to replace the two existing call sites is tracked separately and is out of scope for TRU-197.

---

8. What we recommend the e-conomic admin do

1. Open e-conomic → Settings → Design and Layouts.
2. Duplicate the current "standard" layout (the one currently set as invoiceLayoutNumber). Call the duplicate "Rabat variant" or similar.
3. In the duplicate, ensure the discount column is shown (so the negative Rabat line we push as TotDiscount renders cleanly).
4. Note the layoutNumber of:
   • The original (clean) layout → set as invoiceLayoutNumber in services/nginx/app/modules/economic/config/economic_invoice_layout_c.php (admin override, or via the module config UI).
   • The duplicate (with-discounts) layout → set as invoiceDiscountLayoutNumber in services/nginx/app/modules/economic/config/economic_invoice_discount_layout_c.php.
5. Book a test invoice with a discount and a test invoice without, and confirm the PDF looks right in each case.

---

9. Refs

• TRU-188 — original 400 on / in order reference (PR #391)
• TRU-193 — second-wave audit on extra fields, preflight validation (documentation/economic/export-field-audit.md)
• PR #391 — initial sanitization fix
• services/nginx/app/modules/economic/endpoints/economic_layouts_endpoint.php — GET /layouts wrapper
• services/nginx/app/modules/economic/invoices/draft/economic_invoice_draft_mo.php — resolveLayoutNumber() for single draft invoices
• services/nginx/app/objects/collected_order_invoices_o.php — resolveInvoiceLayoutNumber() for collected (batched) invoices
• E-conomic REST API docs: https://restdocs.e-conomic.com/ (search "Layouts")