# Modelos de PDF para os seus clientes

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

Dê aos documentos que a sua aplicação emite o seu próprio aspeto — o seu logótipo, o do seu cliente, as colunas de que os seus clientes precisam. Desenhe um modelo no editor FIZ ou escreva-o, confira-o com o motor de PDF real e instale-o em cada empresa cliente através da API.

## Como funcionam os modelos

Um modelo é um modelo [pdfme](https://pdfme.com) (o FIZ usa o **pdfme 6.2**) com campos FIZ: um texto como `{invoice.number}` é preenchido com o documento quando o PDF é gerado.

-   Um modelo é usado quando o indica: `GET /invoices/{id}/pdf?templateId=…&format=A4` — faturas, faturas-recibo, faturas simplificadas, notas de crédito e recibos. Nada é aplicado automaticamente; os emails do FIZ e a ligação pública imprimem o PDF padrão. Os PDF de guias de transporte pela API (`GET /transport-documents/{id}/pdf`) usam sempre o aspeto padrão.
-   O modelo que a sua **aplicação** instala é dela: só a sua aplicação o lista, lê, altera ou elimina, e só imprime os documentos que ela emitiu. Até 5 por aplicação e empresa, à parte dos modelos da própria empresa.
-   Os documentos de faturação que a sua aplicação emite para uma empresa que cobre podem usar modelos mesmo que a empresa não tenha plano FIZ. As guias de transporte precisam do plano da própria empresa.
-   Pela API só imprimem modelos fiscais; indicar um não fiscal é recusado com 400. Um modelo fiscal só se aplica em A4 e só aos tipos de documento do seu `documentTypes`; caso contrário o pedido tem sucesso na mesma e devolve o **PDF padrão**. Envie sempre `format=A4` (uma empresa pode ter o rolo de talão como formato predefinido). As notas de crédito e de débito só saem com o modelo se os seus tipos estiverem no `documentTypes` — os modelos de partida `invoice-pt` e `invoice-en` incluem-nos; confira a exportação do seu modelo.
-   O mesmo modelo pode ser instalado em muitas empresas — ou um diferente por cliente.

## 1. Parta de um modelo que funciona

Nunca comece de um ficheiro vazio. Descarregue um modelo de partida FIZ — um modelo completo e válido, com todas as menções fiscais:

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

…ou desenhe-o no editor FIZ (*Configurações → Faturação → Modelos de PDF*) na sua própria empresa FIZ e exporte-o pelo id:

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

A exportação traz `data` (o modelo), `starterId` e `contractVersion`. Envie os três de volta ao importar.

## 2. O que um modelo contém

A descrição completa — todos os tipos de elemento, campos e tipos de letra — está na [referência dos modelos](https://api.fiz.co/docs/templates/reference?lang=pt). Em resumo: `data` é um modelo pdfme: `basePdf` (a página: `width`, `height`, `padding` em mm) e `schemas` — uma lista de elementos por página. O FIZ aceita os tipos que o seu editor produz: `text`, `multiVariableText`, `image` (PNG ou JPG), `table`, `line` e `rectangle`. Outros tipos pdfme podem ser recusados.

**Texto com campos.** Um elemento de texto `readOnly` imprime o seu `content` com cada `{caminho}` substituído pelo valor do documento. Expressões simples funcionam dentro das chavetas, como nos modelos de partida (`{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
}
```

**Tabelas de linhas.** Uma tabela com `"rowSource": "items"` imprime uma linha por linha do documento; cada entrada de `columns` é texto literal e referências `{item.…}`, sem aritmética.

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

**Conjuntos de dados.** Um modelo de faturas vê `invoice`, `customer`, `profile` (a empresa emitente), `template` e, nas tabelas de linhas, `item`. Um modelo de guias vê `transport`, `customer`, `profile` e `item`; pode ser instalado e validado, mas por enquanto a API imprime as guias só com o aspeto padrão. O `starterId` decide qual é.

**Versão do contrato.** Um modelo tem um `contractVersion`. O que envia diz para que funcionalidades de disposição o modelo foi feito; o servidor calcula a versão de dados de que o motor precisa e devolve-a — ver a [secção 4](#4-o-que-faz-um-modelo-ser-recusado).

## 3. Referência de campos

A lista oficial é servida pela API — é a lista que a validação usa, por isso nunca está desatualizada. A validação aplica-a às tabelas de linhas de qualquer modelo e a todos os campos de um modelo não fiscal ou de guias; nos campos de texto de um modelo fiscal um caminho desconhecido não é recusado (ver a [secção 4](#4-o-que-faz-um-modelo-ser-recusado)):

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

Cada entrada é um conjunto de dados (`fiscal`, `nonFiscal`, `transport`): `fields` para textos e células, `rowFields` para tabelas de linhas, `prefixes` como `customer.customField.` + a chave de um campo personalizado do cliente, e o `contractVersion` do servidor.

## 4. O que faz um modelo ser recusado

-   Uma estrutura que o motor não consegue ler: `basePdf` sem `width`, `height` numéricos e quatro valores de `padding`, ou um elemento sem `type`, tamanho ou `position`.
-   Um caminho fora da referência de campos numa tabela de linhas (qualquer modelo) ou em qualquer campo de um modelo não fiscal ou de guias; um caminho `item.…` fora de uma tabela de linhas.
-   Mais de 5 imagens, uma imagem que não seja PNG ou JPG, um elemento menor que 3 × 3 mm ou fora das margens da página.
-   Um código QR ou outro identificador fiscal num modelo não fiscal.
-   Um `contractVersion` abaixo do que a disposição do modelo precisa: 2 para tabelas de linhas, 3 para rolos de talão (`TEMPLATES_EDITOR_OUTDATED` com `requiredVersion`).

**Não verificado:** os caminhos nos campos de texto de um modelo fiscal. Um desconhecido não é recusado e costuma imprimir o texto “undefined” — veja sempre a pré-visualização.

A validação verifica campos e disposição, não a lei. Mantenha todas as menções fiscais do modelo de partida — tipo e número do documento, ATCUD, a linha do programa certificado, o resumo do IVA, as menções de isenção e de retenção, o código QR: o PDF é o documento legal que o seu cliente emite.

**Duas versões.** O `contractVersion` que envia diz para que funcionalidades de disposição o modelo foi feito; envie o de `GET /templates/fields` ou o da exportação. O servidor calcula a versão de dados de que o motor precisa a partir dos campos que o modelo usa e devolve-a em `contractVersion` — pode ser superior à que enviou. É assim que um modelo guardado continua a funcionar quando o FIZ acrescenta campos.

## 5. Confira: validar e pré-visualizar

Validar responde exatamente o que uma importação responderia, sem guardar nada. Uma recusa vem em `problems[0]` com o `code` do erro e um `detail` técnico que indica o caminho ou o elemento:

```
# 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 @-
```

Pré-visualizar gera o modelo com o mesmo motor de PDF dos documentos reais, sobre um documento de exemplo (FT, FR ou FS). Cada página leva a marca «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
```

Repita até a pré-visualização estar certa. Para ver o modelo num documento real, instale-o e descarregue o PDF desse documento com `templateId` (passo 6). Com uma chave `fiz_test_` os mesmos pedidos correm na [sandbox](https://api.fiz.co/docs/quickstart?lang=pt).

## 6. Instale-o e imprima com ele

Importe o modelo para cada empresa cliente com o token de acesso dessa empresa (scope `invoicing.write`). Guarde o `id` devolvido por empresa:

```
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 @-
```

Depois indique-o ao descarregar o PDF de um documento que a sua aplicação emitiu, com `format=A4`:

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

Para o alterar, `PUT /templates/{id}` com o novo `data`; para o retirar, `DELETE /templates/{id}`. Uma alteração aplica-se ao PDF seguinte; os PDF que o FIZ já enviou por email ficam como estavam.

## Criar com um agente de IA

O ciclo — editar o JSON, validar, pré-visualizar — serve bem um agente de programação. Dê-lhe este prompt e uma chave API no `.env`:

```
Cria um modelo de PDF FIZ para as faturas dos meus clientes.
Lê primeiro https://api.fiz.co/docs/templates.md?lang=pt. Parte de
GET /templates/starters/invoice-pt, tira a lista de campos de
GET /templates/fields e, depois de cada alteração, corre POST /templates/validate
e POST /templates/preview; abre o URL da pré-visualização e confere o PDF.
Nunca retires uma menção fiscal do modelo de partida. Usa FIZ_API_KEY do .env.
```

Confira a última pré-visualização antes de instalar o modelo para os seus clientes.
