FIZ / developers

PDF templates

PDF template reference

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

TypeWhat it is forMain properties
textAny printed text, fixed or with document fields. Set "readOnly": true.content, fontName, fontSize, fontColor, backgroundColor, alignment, verticalAlignment, lineHeight, characterSpacing
multiVariableTextIn the starters: the editor's sample data invoice, customer, profile (section 4).content, text, variables
imageA logo, or a QR code FIZ generates (section 6).content
tableThe document lines (section 5).rowSource, columns, head, headWidthPercentages, and the styles tableStyles, headStyles, bodyStyles, columnStyles — required: a table without them fails to render
line, rectangleRules 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

FieldPrints
type, numberDocument type in words («Fatura», «Fatura-Recibo», «Nota de Crédito»…) and its number («FT FIZ2026/12»)
date, dueDate, taxPointDateIssue date, due date, tax point date (empty when not set)
atcudLabel, ATCUDThe ready ATCUD line, or the code alone. Empty on drafts and previews.
certifiedSoftwareLabelThe certified-software line with the document hash
qrThe fiscal QR code image (section 6)
subtotal, taxAmount, totalTotal without VAT, VAT, total with VAT
discountGlobal discount
withholdingTaxAmount, totalToPayIRS withholding, and the total less withholding
vatTypes, vatIncidences, vatValuesThe VAT summary, one line per rate: the rate, its taxable base, its VAT (three aligned columns)
vatExemptionLabel, vatExemptionReasonsThe exemption heading and reasons, when a line is VAT-exempt
withholdingMentions, withholdingDispensaMentionThe withholding mentions and the art. 101.º-B dispensa, when they apply
duplicateOrOriginal«Original» or «Duplicado»
notesThe document's notes
paymentDate, paymentMethodWhen and how a FS, FR or receipt was paid (empty otherwise)
multibancoEntity, multibancoReference, multibancoAmount, multibancoExpiryDateMultibanco payment reference, when the document has one
paymentUrl, gatewayQr, paymentMethodsLabelOnline payment link, its QR image and the accepted methods
reasonLabel, reason, relatedDocumentsLabel, parentDocumentReference, parentDocumentType, parentDocumentNumber, parentDocumentDateOn 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 fieldPrints
indexLine number
name, description, nameWithDescriptionItem name, its description, or both
quantity, unitQuantity and unit («un.», «h»…)
unitPriceUnit price without VAT
discountThe line discount, «0,81 € (10%)»
taxRateVAT rate, «23%»
lineTotalLine total without VAT, after the line discount
unitPriceWithVatUnit price with VAT, before the line discount
lineTotalWithVatLine 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);
  • 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.