# PDF template reference

> Markdown edition of https://api.fiz.co/docs/templates/reference. Português: https://api.fiz.co/docs/templates/reference.md?lang=pt. Index: https://api.fiz.co/llms.txt

What a FIZ PDF template is made of: the page, the elements, where the document data comes from, every field you can print, and the fiscal mentions that must stay. Read it next to the step-by-step guide; check every change with the preview.

## 1. The skeleton

A template is a [pdfme](https://pdfme.com) template (FIZ runs pdfme 6.2): one page description and a list of elements per page. The smallest useful fiscal template:

```
{
  "basePdf": { "width": 210, "height": 297, "padding": [12, 12, 12, 12] },
  "schemas": [[
    { "name": "invoice",  "type": "multiVariableText", "content": "{}", "text": "", "variables": ["number"],
      "position": { "x": 12, "y": 12 }, "width": 4, "height": 4 },
    { "name": "customer", "type": "multiVariableText", "content": "{}", "text": "", "variables": ["name"],
      "position": { "x": 12, "y": 12 }, "width": 4, "height": 4 },
    { "name": "profile",  "type": "multiVariableText", "content": "{}", "text": "", "variables": ["name"],
      "position": { "x": 12, "y": 12 }, "width": 4, "height": 4 },

    { "name": "number", "type": "text", "readOnly": true,
      "content": "{invoice.type} {invoice.number}",
      "position": { "x": 12, "y": 60 }, "width": 186, "height": 12,
      "fontName": "Roboto Bold", "fontSize": 24 },

    { "name": "items", "type": "table", "rowSource": "items",
      "columns": ["{item.nameWithDescription}", "{item.quantity}", "{item.unitPrice}", "{item.taxRate}", "{item.lineTotal}"],
      "head": ["Descrição", "Qtd.", "Preço", "IVA", "Total"],
      "headWidthPercentages": [46, 10, 16, 10, 18],
      "showHead": true,
      "tableStyles": { "borderWidth": 0, "borderColor": "#000000" },
      "headStyles": { "fontName": "Roboto Bold", "fontSize": 10, "characterSpacing": 0, "alignment": "left",
        "verticalAlignment": "top", "lineHeight": 1, "fontColor": "#000000", "borderColor": "#000000",
        "backgroundColor": "", "borderWidth": { "top": 0, "right": 0, "bottom": 0, "left": 0 },
        "padding": { "top": 5, "right": 0, "bottom": 5, "left": 1 } },
      "bodyStyles": { "fontName": "Roboto", "fontSize": 10, "characterSpacing": 0, "alignment": "left",
        "verticalAlignment": "middle", "lineHeight": 1, "fontColor": "#000000", "borderColor": "#000000",
        "backgroundColor": "", "alternateBackgroundColor": "", "borderWidth": { "top": 0, "right": 0, "bottom": 0, "left": 0 },
        "padding": { "top": 3, "right": 0, "bottom": 2, "left": 1 } },
      "columnStyles": { "alignment": { "0": "left", "1": "left", "2": "right", "3": "right", "4": "right" } },
      "position": { "x": 12, "y": 85 }, "width": 186, "height": 40 }
  ]]
}
```

It is not complete: a real template also prints the issuer, the customer, the VAT summary, the totals and the fiscal mentions ([section 8](#8-fiscal-mentions-that-must-stay)). Start from a starter (`GET /templates/starters/invoice-pt`) and change it, rather than writing one from nothing.

## 2. The page

`basePdf` describes the paper, in millimetres:

-   `width`, `height` — 210 × 297 for A4. Fiscal templates print on A4.
-   `padding` — four margins, `[top, right, bottom, left]`. Every element must sit inside them.
-   `staticSchema` (optional) — elements repeated on every page, such as a footer; they may sit in the margins.

`schemas` is a list of pages, each a list of elements. Most templates have one page: the line table grows onto further pages by itself when a document has many lines. Then **every element above the line table repeats on every page**, and every element below it prints on the last page only.

## 3. Elements

Every element has a `name` (unique in the template), a `type`, a `position` `{ x, y }` from the top-left corner and a `width` and `height`, all in millimetres, at least 3 × 3 mm. Optional: `rotate`, `opacity`.

| Type | What it is for | Main properties |
| --- | --- | --- |
| `text` | Any printed text, fixed or with document fields. Set `"readOnly": true`. | `content`, `fontName`, `fontSize`, `fontColor`, `backgroundColor`, `alignment`, `verticalAlignment`, `lineHeight`, `characterSpacing` |
| `multiVariableText` | In the starters: the editor's sample data `invoice`, `customer`, `profile` ([section 4](#4-where-the-data-comes-from)). | `content`, `text`, `variables` |
| `image` | A logo, or a QR code FIZ generates ([section 6](#6-images-qr-codes-and-logos)). | `content` |
| `table` | The document lines ([section 5](#5-the-line-table)). | `rowSource`, `columns`, `head`, `headWidthPercentages`, and the styles `tableStyles`, `headStyles`, `bodyStyles`, `columnStyles` — required: a table without them fails to render |
| `line`, `rectangle` | Rules and boxes. | `color`, `borderWidth`, `borderColor` |

Other pdfme types may be refused. A text element with a document field:

```
{
  "name": "dueDate", "type": "text", "readOnly": true,
  "content": "{invoice.dueDate ? \"Data de vencimento: \" + invoice.dueDate : \"\"}",
  "position": { "x": 12, "y": 240 }, "width": 90, "height": 6,
  "fontName": "Roboto", "fontSize": 9, "fontColor": "#555555", "alignment": "left"
}
```

## 4. Where the data comes from

When FIZ renders a document it hands the template four roots of data: `invoice` (the document), `customer`, `profile` (the issuing company) and `template`. Text elements read them with `{…}` expressions: `{invoice.number}` prints the document number.

-   **The hidden fields in the starters are for the editor.** The starters carry three `multiVariableText` elements named `invoice`, `customer` and `profile`, 4 × 4 mm in a corner with an empty `text`: their `content` is sample data the FIZ editor shows and offers as fields. The render does not need them. Keep them if the template will be opened in the editor.
-   **Simple expressions work** inside the braces: `{invoice.dueDate ? "Vencimento " + invoice.dueDate : ""}`, `{invoice.type === "Fatura Simplificada" ? "Total pago" : "Total a pagar"}`.
-   **Values are text, already formatted** in the document's language: amounts like `1.180,00 €`, dates `DD-MM-YYYY`, the type as a word. Do not compute with them.
-   An unknown field is not refused in a fiscal template's text; it typically prints `undefined`. The preview shows it.

### invoice

| Field | Prints |
| --- | --- |
| `type`, `number` | Document type in words («Fatura», «Fatura-Recibo», «Nota de Crédito»…) and its number («FT FIZ2026/12») |
| `date`, `dueDate`, `taxPointDate` | Issue date, due date, tax point date (empty when not set) |
| `atcudLabel`, `ATCUD` | The ready ATCUD line, or the code alone. Empty on drafts and previews. |
| `certifiedSoftwareLabel` | The certified-software line with the document hash |
| `qr` | The fiscal QR code image ([section 6](#6-images-qr-codes-and-logos)) |
| `subtotal`, `taxAmount`, `total` | Total without VAT, VAT, total with VAT |
| `discount` | Global discount |
| `withholdingTaxAmount`, `totalToPay` | IRS withholding, and the total less withholding |
| `vatTypes`, `vatIncidences`, `vatValues` | The VAT summary, one line per rate: the rate, its taxable base, its VAT (three aligned columns) |
| `vatExemptionLabel`, `vatExemptionReasons` | The exemption heading and reasons, when a line is VAT-exempt |
| `withholdingMentions`, `withholdingDispensaMention` | The withholding mentions and the art. 101.º-B dispensa, when they apply |
| `duplicateOrOriginal` | «Original» or «Duplicado» |
| `notes` | The document's notes |
| `paymentDate`, `paymentMethod` | When and how a FS, FR or receipt was paid (empty otherwise) |
| `multibancoEntity`, `multibancoReference`, `multibancoAmount`, `multibancoExpiryDate` | Multibanco payment reference, when the document has one |
| `paymentUrl`, `gatewayQr`, `paymentMethodsLabel` | Online payment link, its QR image and the accepted methods |
| `reasonLabel`, `reason`, `relatedDocumentsLabel`, `parentDocumentReference`, `parentDocumentType`, `parentDocumentNumber`, `parentDocumentDate` | On credit and debit notes: the reason and the document they rectify (empty on other documents) |

### customer and profile

`customer`: `name`, `address`, `city`, `postalCode`, `country`, `taxPayerNumber`, and custom customer fields as `{customer.customField.KEY}`. `profile` (the issuer): the same address fields plus `phone`, `email`, `iban`, `site` and `issuerLine` (an extra line the company sets in FIZ).

The complete, current list is `GET /templates/fields`.

## 5. The line table

A `table` with `"rowSource": "items"` prints one row per document line. `columns` holds one cell per column: literal text and `{item.…}` references, no expressions. `head` holds the column titles and `headWidthPercentages` their widths, which add up to 100; the three lists have the same length. Only one table per template may be bound to the lines.

| item field | Prints |
| --- | --- |
| `index` | Line number |
| `name`, `description`, `nameWithDescription` | Item name, its description, or both |
| `quantity`, `unit` | Quantity and unit («un.», «h»…) |
| `unitPrice` | Unit price without VAT |
| `discount` | The line discount, «0,81 € (10%)» |
| `taxRate` | VAT rate, «23%» |
| `lineTotal` | Line total without VAT, after the line discount |
| `unitPriceWithVat` | Unit price with VAT, before the line discount |
| `lineTotalWithVat` | Line total with VAT, after the line discount, before the document's global discount and before withholding |

**Prices with VAT.** A table that prints `unitPriceWithVat` or `lineTotalWithVat` must also print `unitPrice`, `lineTotal` or `taxRate`: an invoice shows the price without VAT (CIVA art. 36.º), or — for retailers and service providers (art. 39.º) and simplified invoices (art. 40.º) — the price with VAT and the rate. Whether art. 39.º applies to the issuer is the issuer's call. In such a table every column must be at least 3 mm wide and the widths must not add up to more than 100. The sum of the lines with VAT can differ from the total: a global discount applies to the total only (a €100 line at 23% with 10% off the document shows €123,00 while the total is €110,70), and VAT is rounded per rate.

```
{
  "name": "items", "type": "table", "rowSource": "items",
  "columns": ["{item.nameWithDescription}", "{item.quantity}", "{item.unitPriceWithVat}", "{item.taxRate}", "{item.lineTotalWithVat}"],
  "head": ["Descrição", "Qtd.", "Preço c/ IVA", "IVA", "Total c/ IVA"],
  "headWidthPercentages": [44, 10, 17, 10, 19],
  "showHead": true,
  "tableStyles": { "borderWidth": 0, "borderColor": "#000000" },
  "headStyles": { "fontName": "Roboto Bold", "fontSize": 10, "characterSpacing": 0, "alignment": "left",
    "verticalAlignment": "top", "lineHeight": 1, "fontColor": "#000000", "borderColor": "#000000",
    "backgroundColor": "", "borderWidth": { "top": 0, "right": 0, "bottom": 0, "left": 0 },
    "padding": { "top": 5, "right": 0, "bottom": 5, "left": 1 } },
  "bodyStyles": { "fontName": "Roboto", "fontSize": 10, "characterSpacing": 0, "alignment": "left",
    "verticalAlignment": "middle", "lineHeight": 1, "fontColor": "#000000", "borderColor": "#000000",
    "backgroundColor": "", "alternateBackgroundColor": "", "borderWidth": { "top": 0, "right": 0, "bottom": 0, "left": 0 },
    "padding": { "top": 3, "right": 0, "bottom": 2, "left": 1 } },
  "columnStyles": { "alignment": { "0": "left", "1": "left", "2": "right", "3": "right", "4": "right" } },
  "position": { "x": 12, "y": 85 }, "width": 186, "height": 40
}
```

## 6. Images, QR codes and logos

An `image`'s `content` is either a fixed picture — a data URI, PNG or JPG only — or a field FIZ fills with an image: `{invoice.qr}` (the fiscal QR code) or `{invoice.gatewayQr}` (the online payment QR). At most 5 images per template, QR codes included.

**The fiscal QR code is at least 30 × 30 mm** — the AT's technical specification for the code (Portaria 195/2020).

```
{
  "name": "qr", "type": "image", "readOnly": true,
  "content": "{invoice.qr}",
  "position": { "x": 166, "y": 18 }, "width": 30, "height": 30
}
```

A logo is a fixed image. There is no logo field: to give each client its own logo, install a template per client company.

```
{
  "name": "logo", "type": "image", "readOnly": true,
  "content": "data:image/png;base64,iVBORw0KGgo…",
  "position": { "x": 12, "y": 12 }, "width": 40, "height": 16
}
```

## 7. Fonts

`fontName` is one of: `Roboto` (the default), `Open Sans`, `Lato`, `Montserrat`, `Inter`, `Merriweather`, `IBM Plex Mono`, `JetBrains Mono`. Each also comes as `… Bold`, `… Italic` and `… Bold Italic` (Roboto: `Roboto Bold`). Bold and italic are separate font names, not switches. A name that is not on this list makes the render fail.

## 8. Fiscal mentions that must stay

The validator checks structure and fields, not the law; the PDF is the legal document your client issues. Keep, as the starters print them:

-   document type and number — `{invoice.type} {invoice.number}`;
-   issuer and customer with their tax numbers — the `profile` and `customer` fields;
-   dates — `{invoice.date}`; `{invoice.taxPointDate}`, the date of the supply, service or advance payment, which CIVA art. 36.º n.º 5 f) requires when it differs from the issue date (empty otherwise); the due date where it applies;
-   ATCUD — `{invoice.atcudLabel}`, on every page and immediately above the QR code (Portaria 195/2020, art. 4.º n.º 3): place it above the line table, right over the QR, as the starters do;
-   the certified-software line — `{invoice.certifiedSoftwareLabel}`;
-   the fiscal QR code — an image with `{invoice.qr}`, at least 30 × 30 mm;
-   the lines with quantity, price and VAT rate ([section 5](#5-the-line-table));
-   the VAT summary per rate and the totals — `vatTypes`, `vatIncidences`, `vatValues`, `subtotal`, `taxAmount`, `total`;
-   exemption and withholding mentions — `vatExemptionLabel`, `vatExemptionReasons`, `withholdingMentions`, `withholdingDispensaMention`;
-   on credit and debit notes, the reason and the rectified document — `{invoice.reasonLabel} {invoice.reason}`, `{invoice.relatedDocumentsLabel} {invoice.parentDocumentReference}`. A template that does not print the reference prints notes in the standard layout.
