Modelos de PDF
Referência dos modelos de PDF
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 (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). 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). | content, text, variables |
image | Um logótipo, ou um código QR gerado pelo FIZ (secção 6). | content |
table | As linhas do documento (secção 5). | 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
multiVariableTextcom os nomesinvoice,customereprofile, de 4 × 4 mm num canto e comtextvazio: ocontenté 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 €, datasDD-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) |
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
profileecustomer; - 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);
- 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.