Invoice templates
Render invoices as Factur-X PDFs in an Office Freund layout — how a template works, and every placeholder.
/e-invoice/xmltopdf renders the fixed XRechnung visualisation. The
template endpoints render a designed layout: an XHTML
document with Mustache
placeholders, rendered from the same invoice JSON you send to
/e-invoice/invoice2XML. The result is a PDF/A-3 with the EN 16931 XML
embedded (factur-x.xml) — a legal Factur-X invoice.
The templates are maintained by Office Freund and shared by every API key. Custom layouts per account are planned as a paid feature; until then, pick one from the list.
Quick start
# 1. Pick a template
curl "$BASE/e-invoice/templates" -H "Authorization: Bearer $API_KEY"
# → { "templates": [{ "id": "3f9b…", "name": "Office Freund Standard (DE)", ... }] }
# 2. Render an invoice with it
curl "$BASE/e-invoice/templates/3f9b…/render" -H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" --data @invoice.json -o invoice.pdfinvoice.json is the CalculatedInvoice shape from the Documents API —
number, currency, issueDate, sender, recipient, zfitems[] and so
on. The engine computes every total from the line items; totals in the body
are ignored. Amounts are passed on digit for digit, so send them the way your
system writes them.
GET /e-invoice/templates/{id} returns what the engine receives: mustache, the XHTML
source, and base64, the map of fonts and images it references as
base64:<name>. It is the reference for what a layout shows.
Placeholders
Names are case-sensitive and come from the engine, not from the JSON keys —
line items are {{#ZFItems}} (not zfitems), the VAT total is {{VATtotal}},
a line's rate is {{product.VATPercent}}. Two helpers format values:
{{#DATEFORMAT}}{{issueDate}}{{/DATEFORMAT}} → 25.09.2026, and
{{#CURRENCYFORMAT}}{{grandTotal}}{{/CURRENCYFORMAT}} → 1493.25. Both
fail the whole render on an empty value, so optional fields are guarded:
{{#dueDate}}{{#DATEFORMAT}}{{dueDate}}{{/DATEFORMAT}}{{/dueDate}}.
CURRENCYFORMAT also fails on a value with more than two decimals and always
prints a dot and no thousands separator, in every language. A third helper,
{{#UNIT}}{{product.unit}}{{/UNIT}}, spells a unit code out in the render
language (HUR → Stunden / Hours); it works for DE and EN and fails
the render for FR.
| Placeholder | Example |
|---|---|
{{number}} {{documentName}} {{documentCode}} {{currency}} | RE-2026-0042 Rechnung 380 EUR |
{{issueDate}} {{dueDate}} {{deliveryDate}} {{detailedDeliveryPeriodFrom}} {{detailedDeliveryPeriodTo}} | dates — wrapped in DATEFORMAT |
{{referenceNumber}} {{buyerOrderReferencedDocumentID}} {{invoiceReferencedDocumentID}} | 04011000-12345-67 (Leitweg-ID) |
{{paymentReference}} {{paymentTermDescription}} | RE-2026-0042 |
{{#notes}}{{.}}{{/notes}} | each note |
{{#cashDiscounts}}{{percent}} {{days}} {{basisAmount}}{{/cashDiscounts}} | 2 7 1493.25 |
{{sender.name}} {{sender.street}} {{sender.zip}} {{sender.location}} {{sender.country}} {{sender.vatID}} {{sender.taxID}} {{sender.email}} | seller; same fields under recipient. |
{{sender.contact.name}} {{sender.contact.phone}} {{sender.contact.email}} | guarded with {{#sender.contact}} |
{{sender.legalOrganisation.tradingBusinessName}} | |
{{#sender.bankDetails}}{{IBAN}} {{BIC}} {{accountName}}{{/sender.bankDetails}} | DE02… BYLADEM1001 Muster GmbH |
{{#tradeSettlement}}{{ownIBAN}} {{ownBIC}} {{accountName}}{{/tradeSettlement}} | the tradeSettlementPayment entries |
{{taxBasis}} {{VATtotal}} {{grandTotal}} {{duePayable}} {{lineTotalAmount}} {{totalPrepaidAmount}} | totals — wrapped in CURRENCYFORMAT; totalPrepaidAmount only if sent |
{{#calculation.taxDetails}}{{applicablePercent}} {{basis}} {{calculated}} {{categoryCode}} {{vatExemptionReasonText}}{{/calculation.taxDetails}} | one entry per VAT rate |
{{#ZFItems}}…{{/ZFItems}} inside: {{id}} {{product.name}} {{product.description}} {{quantity}} {{product.unit}} (or {{#UNIT}}{{product.unit}}{{/UNIT}}) {{price}} {{product.VATPercent}} {{product.sellerAssignedID}} {{accountingReference}} {{detailedDeliveryPeriodFrom}} {{detailedDeliveryPeriodTo}} | one line item |
… {{calculation.itemTotalNetAmount}} {{calculation.itemTotalVATAmount}} {{calculation.itemTotalGrossAmount}} {{calculation.price}} | computed per line |
What is not possible
- XRechnung. Rendering is Factur-X only. B2G callers keep using
/e-invoice/invoice2XML?format=xrand/e-invoice/xmltopdffor a reading copy. - Locale number formatting.
1.493,25 €needs a helper the engine does not have;CURRENCYFORMATprints1493.25. - Your own totals. The engine recomputes them from the lines.
- A line whose VAT needs more than two decimals (2.5 × 30.50 at 19 %) —
the engine answers
Rounding necessaryand the render is a422 RENDER_REJECTED.
The language query parameter is passed to the engine, where it only affects
UNIT; dates and amounts print the same way in DE, EN and FR — the template's
own labels decide the language of the document, which is why the catalogue has
one template per language.