FIZ / developers

PDF templates

PDF templates for your clients

Give the documents your app issues your own layout — your logo, your client’s logo, the columns your clients need. Design a template in the FIZ editor or write it yourself, check it with the real PDF engine, and install it in each client company through the API.

How templates work

A template is a pdfme template (FIZ runs pdfme 6.2) with FIZ fields: text such as {invoice.number} is filled from the document when the PDF is rendered.

  • A template is used when you name it: GET /invoices/{id}/pdf?templateId=…&format=A4 — invoices, invoice-receipts, simplified invoices, credit notes and receipts. Nothing is applied automatically; FIZ emails and the public link print the standard PDF. Transport document PDFs through the API (GET /transport-documents/{id}/pdf) always use the standard layout.
  • A template your app installs belongs to the app: only your app lists, reads, changes or deletes it, and it prints only the documents your app issued. Up to 5 per app and company, apart from the company’s own templates.
  • Invoice-family documents your app issues for a company it covers may use templates even when the company has no FIZ plan. Transport documents need the company’s own plan.
  • Through the API only fiscal templates print; naming a non-fiscal one is refused with 400. A fiscal template applies only on A4 and only to the document types in its documentTypes; otherwise the request still succeeds and returns the standard PDF. Always send format=A4 (a company may default to a receipt roll). Credit and debit notes print with a template only if their types are in its documentTypes — the invoice-pt and invoice-en starters include them; check the export of your template.
  • The same template can be installed in many companies — or a different one per client.

1. Start from a working template

Never start from an empty file. Either download a FIZ starter — a complete, valid template with every fiscal mention in place:

curl https://api.fiz.co/templates/starters/invoice-pt \
  --header "x-api-key: $FIZ_API_KEY" > starter.json

…or design one visually in the FIZ editor (Settings → Invoicing → PDF templates) in your own FIZ company, then export it with its id:

curl https://api.fiz.co/templates/TEMPLATE_ID \
  --header "x-api-key: $FIZ_API_KEY" > my-template.json

The export carries data (the template), starterId and contractVersion. Send all three back when you import it.

2. What a template contains

The full description — every element type, field and font — is the template reference. In short: data is a pdfme template: basePdf (the page: width, height, padding in mm) and schemas — one array of elements per page. FIZ supports the element types its editor produces: text, multiVariableText, image (PNG or JPG), table, line and rectangle. Other pdfme types may be refused.

Text with fields. A readOnly text element prints its content with every {path} replaced by the document’s value. Simple expressions work inside the braces, as in the starters ({invoice.dueDate ? "Vencimento " + invoice.dueDate : ""}).

{
  "type": "text",
  "name": "number",
  "readOnly": true,
  "content": "{invoice.type} {invoice.number}",
  "position": { "x": 12, "y": 40 }, "width": 120, "height": 8, "fontSize": 14
}

Line tables. A table with "rowSource": "items" prints one row per document line; each entry of columns is literal text and {item.…} references, no arithmetic.

{
  "type": "table",
  "name": "items",
  "rowSource": "items",
  "columns": ["{item.name}", "{item.quantity}", "{item.unitPrice}", "{item.taxRate}", "{item.lineTotal}"],
  "head": ["Descrição", "Qtd.", "Preço", "IVA", "Total"],
  "headWidthPercentages": [40, 10, 18, 12, 20],
  "position": { "x": 12, "y": 110 }, "width": 186, "height": 40
}

Data sets. An invoice template sees invoice, customer, profile (the issuing company), template and, in line tables, item. A transport template sees transport, customer, profile and item; it can be installed and validated, but the API prints transport documents only in the standard layout for now. The starterId decides which one a template is.

Contract version. A template carries a contractVersion. The one you send says which layout features the template was made for; the server computes the data version the render needs and returns it — see section 4.

3. Field reference

The authoritative list is served by the API — it is the list the validator uses, so it is never out of date. The validator applies it to line tables in every template and to every field of a non-fiscal or transport template; in the text fields of a fiscal template an unknown path is not refused (see section 4):

curl https://api.fiz.co/templates/fields \
  --header "x-api-key: $FIZ_API_KEY"

Each entry is one data set (fiscal, nonFiscal, transport): fields for text and cells, rowFields for line tables, prefixes such as customer.customField. + the key of a custom customer field, and the server’s contractVersion.

4. What gets a template refused

  • A structure the renderer cannot read: basePdf without numeric width, height and four padding values, or an element without a type, size or position.
  • A path outside the field reference in a line table (any template), or in any field of a non-fiscal or transport template; an item.… path outside a line table.
  • More than 5 images, an image that is not PNG or JPG, an element smaller than 3 × 3 mm or outside the page margins.
  • A QR code or other fiscal identifier on a non-fiscal template.
  • A contractVersion below what the template’s layout needs: 2 for line tables, 3 for receipt rolls (TEMPLATES_EDITOR_OUTDATED with requiredVersion).

Not checked: the paths in the text fields of a fiscal template. An unknown one is not refused and typically prints the text “undefined” — always look at the preview.

The validator checks fields and layout, not the law. Keep every fiscal mention of the starter — document type and number, ATCUD, the certified-software line, the VAT summary, exemption and withholding mentions, the QR code: the PDF is the legal document your client issues.

Two versions. The contractVersion you send says which layout features your template was made for; send the one from GET /templates/fields or from the export. The server works out the data version the render needs from the fields the template uses and returns it as contractVersion — it can be higher than what you sent. Templates are versioned this way, so a stored template keeps rendering when FIZ adds fields.

5. Check it: validate and preview

Validate answers exactly what an import would, without storing anything. A refusal comes back as problems[0] with the error code and a technical detail naming the path or element:

# template.json holds the template itself (the "data" of an export)
jq -n --slurpfile t template.json \
  '{data: $t[0], starterId: "invoice-pt", contractVersion: 7}' \
| curl --request POST https://api.fiz.co/templates/validate \
  --header "x-api-key: $FIZ_API_KEY" \
  --header 'Content-Type: application/json' --data @-

Preview renders the template with the same PDF engine as real documents, on a sample document (FT, FR or FS). Every page carries «DOCUMENTO DE TESTE — SEM VALIDADE FISCAL»:

jq -n --slurpfile t template.json \
  '{data: $t[0], starterId: "invoice-pt", contractVersion: 7, documentType: "INVOICE_RECEIPT"}' \
| curl --request POST https://api.fiz.co/templates/preview \
  --header "x-api-key: $FIZ_API_KEY" \
  --header 'Content-Type: application/json' --data @- \
| jq -r .url   # open the URL: a PDF marked as a preview

Repeat until the preview looks right. To see the template on a real document, install it and download that document’s PDF with templateId (step 6). With a fiz_test_ key the same requests run in the sandbox.

6. Install it and print with it

Import the template into each client company with that company’s access token (scope invoicing.write). Keep the returned id per company:

jq -n --slurpfile t template.json \
  '{name: "Gym A4", data: $t[0], starterId: "invoice-pt", contractVersion: 7}' \
| curl --request POST https://api.fiz.co/templates \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: install-gym-a4-1' --data @-

Then name it when you download a PDF of a document your app issued, with format=A4:

curl "https://api.fiz.co/invoices/INVOICE_ID/pdf?templateId=TEMPLATE_ID&format=A4" \
  --header "Authorization: Bearer $ACCESS_TOKEN"

To change it, PUT /templates/{id} with the new data; to remove it, DELETE /templates/{id}. A change applies to the next render; PDFs FIZ already emailed keep their copy.

Build it with a coding agent

The loop — edit JSON, validate, preview — suits an AI coding agent. Give it this prompt and an API key in .env:

Build a FIZ PDF template for my clients' invoices.
Read https://api.fiz.co/docs/templates.md first. Start from
GET /templates/starters/invoice-pt, take the field list from
GET /templates/fields, and after every change run POST /templates/validate
and POST /templates/preview; open the preview URL and check the PDF.
Never drop a fiscal mention from the starter. Use FIZ_API_KEY from .env.

Review the last preview yourself before installing the template for your clients.