E-Invoice API
Guides

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.pdf

invoice.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.

PlaceholderExample
{{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=xr and /e-invoice/xmltopdf for a reading copy.
  • Locale number formatting. 1.493,25 € needs a helper the engine does not have; CURRENCYFORMAT prints 1493.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 necessary and the render is a 422 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.

On this page