# Referência dos modelos de PDF

> Edição Markdown de https://api.fiz.co/docs/templates/reference?lang=pt. English: https://api.fiz.co/docs/templates/reference.md. Índice: https://api.fiz.co/llms.txt

De que é feito um modelo de PDF FIZ: a página, os elementos, de onde vêm os dados do documento, todos os campos que pode imprimir e as menções fiscais que têm de ficar. Leia-a junto com o guia passo a passo; confira cada alteração com a pré-visualização.

## 1. O esqueleto

Um modelo é um modelo [pdfme](https://pdfme.com) (o FIZ usa o pdfme 6.2): uma descrição da página e uma lista de elementos por página. O menor modelo fiscal útil:

```
{
  "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 }
  ]]
}
```

Não está completo: um modelo real imprime também o emitente, o cliente, o resumo do IVA, os totais e as menções fiscais ([secção 8](#8-menções-fiscais-que-têm-de-ficar)). Parta de um modelo de partida (`GET /templates/starters/invoice-pt`) e altere-o, em vez de escrever um do zero.

## 2. A página

`basePdf` descreve o papel, em milímetros:

-   `width`, `height` — 210 × 297 para A4. Os modelos fiscais imprimem em A4.
-   `padding` — quatro margens, `[cima, direita, baixo, esquerda]`. Todos os elementos têm de ficar dentro delas.
-   `staticSchema` (opcional) — elementos repetidos em todas as páginas, como um rodapé; podem ficar nas margens.

`schemas` é uma lista de páginas, cada uma com uma lista de elementos. A maioria dos modelos tem uma página: a tabela de linhas continua sozinha nas páginas seguintes quando o documento tem muitas linhas. Nesse caso **todos os elementos acima da tabela de linhas repetem-se em todas as páginas**, e os que estão abaixo dela só saem na última.

## 3. Elementos

Cada elemento tem um `name` (único no modelo), um `type`, uma `position` `{ x, y }` a partir do canto superior esquerdo e uma `width` e `height`, tudo em milímetros, no mínimo 3 × 3 mm. Opcionais: `rotate`, `opacity`.

| Tipo | Para que serve | Propriedades principais |
| --- | --- | --- |
| `text` | Qualquer texto impresso, fixo ou com campos do documento. Use `"readOnly": true`. | `content`, `fontName`, `fontSize`, `fontColor`, `backgroundColor`, `alignment`, `verticalAlignment`, `lineHeight`, `characterSpacing` |
| `multiVariableText` | Nos modelos de partida: os dados de exemplo do editor `invoice`, `customer`, `profile` ([secção 4](#4-de-onde-vêm-os-dados)). | `content`, `text`, `variables` |
| `image` | Um logótipo, ou um código QR gerado pelo FIZ ([secção 6](#6-imagens-códigos-qr-e-logótipos)). | `content` |
| `table` | As linhas do documento ([secção 5](#5-a-tabela-de-linhas)). | `rowSource`, `columns`, `head`, `headWidthPercentages`, e os estilos `tableStyles`, `headStyles`, `bodyStyles`, `columnStyles` — obrigatórios: uma tabela sem eles falha na geração |
| `line`, `rectangle` | Linhas e caixas. | `color`, `borderWidth`, `borderColor` |

Outros tipos pdfme podem ser recusados. Um elemento de texto com um campo do documento:

```
{
  "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. De onde vêm os dados

Ao gerar um documento, o FIZ entrega ao modelo quatro raízes de dados: `invoice` (o documento), `customer`, `profile` (a empresa emitente) e `template`. Os elementos de texto leem-nas com expressões `{…}`: `{invoice.number}` imprime o número do documento.

-   **Os campos escondidos dos modelos de partida são para o editor.** Os modelos de partida têm três elementos `multiVariableText` com os nomes `invoice`, `customer` e `profile`, de 4 × 4 mm num canto e com `text` vazio: o `content` é um exemplo que o editor FIZ mostra e oferece como campos. A geração não precisa deles. Mantenha-os se o modelo for aberto no editor.
-   **Funcionam expressões simples** dentro das chavetas: `{invoice.dueDate ? "Vencimento " + invoice.dueDate : ""}`, `{invoice.type === "Fatura Simplificada" ? "Total pago" : "Total a pagar"}`.
-   **Os valores são texto já formatado** na língua do documento: valores como `1.180,00 €`, datas `DD-MM-AAAA`, o tipo por extenso. Não faça contas com eles.
-   Um campo desconhecido não é recusado no texto de um modelo fiscal; costuma imprimir `undefined`. A pré-visualização mostra-o.

### invoice

| Campo | Imprime |
| --- | --- |
| `type`, `number` | Tipo do documento por extenso («Fatura», «Fatura-Recibo», «Nota de Crédito»…) e o número («FT FIZ2026/12») |
| `date`, `dueDate`, `taxPointDate` | Data de emissão, data de vencimento, data da operação (vazia quando não definida) |
| `atcudLabel`, `ATCUD` | A linha ATCUD pronta, ou só o código. Vazios em rascunhos e pré-visualizações. |
| `certifiedSoftwareLabel` | A linha do programa certificado, com o hash do documento |
| `qr` | A imagem do código QR fiscal ([secção 6](#6-imagens-códigos-qr-e-logótipos)) |
| `subtotal`, `taxAmount`, `total` | Total sem IVA, IVA, total com IVA |
| `discount` | Desconto global |
| `withholdingTaxAmount`, `totalToPay` | Retenção na fonte, e o total depois da retenção |
| `vatTypes`, `vatIncidences`, `vatValues` | O resumo do IVA, uma linha por taxa: a taxa, a incidência, o IVA (três colunas alinhadas) |
| `vatExemptionLabel`, `vatExemptionReasons` | O título e os motivos de isenção, quando há linhas isentas |
| `withholdingMentions`, `withholdingDispensaMention` | As menções de retenção e a dispensa do art. 101.º-B, quando se aplicam |
| `duplicateOrOriginal` | «Original» ou «Duplicado» |
| `notes` | As observações do documento |
| `paymentDate`, `paymentMethod` | Quando e como foi paga uma FS, FR ou recibo (vazios nos outros) |
| `multibancoEntity`, `multibancoReference`, `multibancoAmount`, `multibancoExpiryDate` | Referência Multibanco, quando o documento tem uma |
| `paymentUrl`, `gatewayQr`, `paymentMethodsLabel` | Ligação de pagamento online, a imagem QR dela e os meios aceites |
| `reasonLabel`, `reason`, `relatedDocumentsLabel`, `parentDocumentReference`, `parentDocumentType`, `parentDocumentNumber`, `parentDocumentDate` | Nas notas de crédito e de débito: o motivo e o documento retificado (vazios nos outros documentos) |

### customer e profile

`customer`: `name`, `address`, `city`, `postalCode`, `country`, `taxPayerNumber`, e os campos personalizados do cliente como `{customer.customField.CHAVE}`. `profile` (o emitente): os mesmos campos de morada e ainda `phone`, `email`, `iban`, `site` e `issuerLine` (uma linha extra que a empresa define no FIZ).

A lista completa e atual é `GET /templates/fields`.

## 5. A tabela de linhas

Uma `table` com `"rowSource": "items"` imprime uma linha por linha do documento. `columns` tem uma célula por coluna: texto literal e referências `{item.…}`, sem expressões. `head` tem os títulos das colunas e `headWidthPercentages` as larguras, que somam 100; as três listas têm o mesmo tamanho. Só uma tabela por modelo pode estar ligada às linhas.

| Campo item | Imprime |
| --- | --- |
| `index` | Número da linha |
| `name`, `description`, `nameWithDescription` | Nome do artigo, a descrição, ou os dois |
| `quantity`, `unit` | Quantidade e unidade («un.», «h»…) |
| `unitPrice` | Preço unitário sem IVA |
| `discount` | O desconto da linha, «0,81 € (10%)» |
| `taxRate` | Taxa de IVA, «23%» |
| `lineTotal` | Total da linha sem IVA, depois do desconto da linha |
| `unitPriceWithVat` | Preço unitário com IVA, antes do desconto da linha |
| `lineTotalWithVat` | Total da linha com IVA, depois do desconto da linha, antes do desconto global do documento e da retenção |

**Preços com IVA.** Uma tabela que imprime `unitPriceWithVat` ou `lineTotalWithVat` tem de imprimir também `unitPrice`, `lineTotal` ou `taxRate`: a fatura mostra o preço sem IVA (art. 36.º do CIVA) ou — para retalhistas e prestadores de serviços (art. 39.º) e faturas simplificadas (art. 40.º) — o preço com IVA e a taxa. Se o art. 39.º se aplica ao emitente é decisão do emitente. Numa tabela assim, cada coluna tem pelo menos 3 mm e as larguras não somam mais de 100. A soma das linhas com IVA pode diferir do total: o desconto global aplica-se só ao total (uma linha de 100 € a 23% com 10% de desconto no documento mostra 123,00 € e o total é 110,70 €), e o IVA é arredondado por taxa.

```
{
  "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. Imagens, códigos QR e logótipos

O `content` de uma `image` é uma imagem fixa — um data URI, só PNG ou JPG — ou um campo que o FIZ preenche com uma imagem: `{invoice.qr}` (o código QR fiscal) ou `{invoice.gatewayQr}` (o QR do pagamento online). No máximo 5 imagens por modelo, códigos QR incluídos.

**O código QR fiscal tem no mínimo 30 × 30 mm** — a especificação técnica da AT para o código (Portaria 195/2020).

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

Um logótipo é uma imagem fixa. Não há campo de logótipo: para dar a cada cliente o seu logótipo, instale um modelo por empresa cliente.

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

## 7. Tipos de letra

`fontName` é um de: `Roboto` (o predefinido), `Open Sans`, `Lato`, `Montserrat`, `Inter`, `Merriweather`, `IBM Plex Mono`, `JetBrains Mono`. Cada um existe também como `… Bold`, `… Italic` e `… Bold Italic` (Roboto: `Roboto Bold`). Negrito e itálico são nomes de letra separados, não opções. Um nome fora desta lista faz falhar a geração.

## 8. Menções fiscais que têm de ficar

A validação verifica estrutura e campos, não a lei; o PDF é o documento legal que o seu cliente emite. Mantenha, como nos modelos de partida:

-   tipo e número do documento — `{invoice.type} {invoice.number}`;
-   emitente e cliente com os números de contribuinte — os campos `profile` e `customer`;
-   datas — `{invoice.date}`; `{invoice.taxPointDate}`, a data do fornecimento, da prestação de serviços ou do pagamento antecipado, que o art. 36.º n.º 5 f) do CIVA exige quando difere da data de emissão (vazia nos outros casos); a data de vencimento quando se aplica;
-   ATCUD — `{invoice.atcudLabel}`, em todas as páginas e imediatamente acima do código QR (Portaria 195/2020, art. 4.º n.º 3): coloque-o acima da tabela de linhas, logo por cima do QR, como nos modelos de partida;
-   a linha do programa certificado — `{invoice.certifiedSoftwareLabel}`;
-   o código QR fiscal — uma imagem com `{invoice.qr}`, no mínimo 30 × 30 mm;
-   as linhas com quantidade, preço e taxa de IVA ([secção 5](#5-a-tabela-de-linhas));
-   o resumo do IVA por taxa e os totais — `vatTypes`, `vatIncidences`, `vatValues`, `subtotal`, `taxAmount`, `total`;
-   as menções de isenção e de retenção — `vatExemptionLabel`, `vatExemptionReasons`, `withholdingMentions`, `withholdingDispensaMention`;
-   nas notas de crédito e de débito, o motivo e o documento retificado — `{invoice.reasonLabel} {invoice.reason}`, `{invoice.relatedDocumentsLabel} {invoice.parentDocumentReference}`. Um modelo que não imprime a referência imprime as notas com o aspeto padrão.
