# PDF templates for your clients

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

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](https://pdfme.com) 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](https://api.fiz.co/docs/templates/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](#4-what-gets-a-template-refused).

## 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](#4-what-gets-a-template-refused)):

```
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](https://api.fiz.co/docs/quickstart).

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