FIZ / developers

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.

TipoPara que servePropriedades principais
textQualquer texto impresso, fixo ou com campos do documento. Use "readOnly": true.content, fontName, fontSize, fontColor, backgroundColor, alignment, verticalAlignment, lineHeight, characterSpacing
multiVariableTextNos modelos de partida: os dados de exemplo do editor invoice, customer, profile (secção 4).content, text, variables
imageUm logótipo, ou um código QR gerado pelo FIZ (secção 6).content
tableAs 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, rectangleLinhas 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

CampoImprime
type, numberTipo do documento por extenso («Fatura», «Fatura-Recibo», «Nota de Crédito»…) e o número («FT FIZ2026/12»)
date, dueDate, taxPointDateData de emissão, data de vencimento, data da operação (vazia quando não definida)
atcudLabel, ATCUDA linha ATCUD pronta, ou só o código. Vazios em rascunhos e pré-visualizações.
certifiedSoftwareLabelA linha do programa certificado, com o hash do documento
qrA imagem do código QR fiscal (secção 6)
subtotal, taxAmount, totalTotal sem IVA, IVA, total com IVA
discountDesconto global
withholdingTaxAmount, totalToPayRetenção na fonte, e o total depois da retenção
vatTypes, vatIncidences, vatValuesO resumo do IVA, uma linha por taxa: a taxa, a incidência, o IVA (três colunas alinhadas)
vatExemptionLabel, vatExemptionReasonsO título e os motivos de isenção, quando há linhas isentas
withholdingMentions, withholdingDispensaMentionAs menções de retenção e a dispensa do art. 101.º-B, quando se aplicam
duplicateOrOriginal«Original» ou «Duplicado»
notesAs observações do documento
paymentDate, paymentMethodQuando e como foi paga uma FS, FR ou recibo (vazios nos outros)
multibancoEntity, multibancoReference, multibancoAmount, multibancoExpiryDateReferência Multibanco, quando o documento tem uma
paymentUrl, gatewayQr, paymentMethodsLabelLigação de pagamento online, a imagem QR dela e os meios aceites
reasonLabel, reason, relatedDocumentsLabel, parentDocumentReference, parentDocumentType, parentDocumentNumber, parentDocumentDateNas 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 itemImprime
indexNúmero da linha
name, description, nameWithDescriptionNome do artigo, a descrição, ou os dois
quantity, unitQuantidade e unidade («un.», «h»…)
unitPricePreço unitário sem IVA
discountO desconto da linha, «0,81 € (10%)»
taxRateTaxa de IVA, «23%»
lineTotalTotal da linha sem IVA, depois do desconto da linha
unitPriceWithVatPreço unitário com IVA, antes do desconto da linha
lineTotalWithVatTotal 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);
  • 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.