Generate and validate one UBL e-invoice

Accepts generation-input/v1 JSON with decimal strings. Both ruleset (latest or an exact immutable ID) and profile are required; document_type comes from the body. Unknown or repeated query parameters, duplicate JSON keys, unknown fields, nulls, JSON numbers and inconsistent calculated totals are refused before acceptance. UTF-8 application/json only; uncompressed body at most 5 MiB.

The operation pins the selected ruleset, generator/schema versions and engine image at acceptance. Only the exact generated XML bytes validated by that engine can succeed. Every validation layer must pass. Generated XML which fails the rules is an internal 500 generation_failed, indeterminate and uncharged; no artifact or customer-invalid verdict is returned. Dependency failures are 503/504. Validation has a 10-second deadline and result persistence a separate 5-second budget.

Authenticated requests require finance:einvoices:write and optionally Idempotency-Key. The key is scoped to the organisation and generation endpoint. Input identity is financewolf-json/1: UTF-8 JSON decoded and re-encoded with sorted object keys, compact separators and Go JSON string escaping. Whitespace, object key order and equivalent string escapes do not change identity; decimal string spelling and array order do. An existing key replays the original bytes without execution or a second usage event even after latest or the deployed generator changes; different content or selectors produce 409. Anonymous requests cannot supply Idempotency-Key or a tenant header and create no stored operation or usage event.

The successful response contains base64 of the exact XML, its SHA-256 and a nested validation verdict. One authenticated success records one einvoice.generation usage event. Source JSON is never retained. Authenticated generated XML and validation findings are retained together for 30 days, retrievable/deletable through /v1/einvoices/results/{id}; anonymous results are not retained. Deletion/expiry erases artifacts and findings but preserves the operation and usage identity, so a replay returns 410 and never runs or charges again. Responses use Cache-Control: no-store and the standard request correlation headers.