Modelos de PDF
Modelos de PDF para os seus clientes
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 (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 sempreformat=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 nodocumentTypes— os modelos de partidainvoice-pteinvoice-enincluem-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.jsonA 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. 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.
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):
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:
basePdfsemwidth,heightnuméricos e quatro valores depadding, ou um elemento semtype, tamanho ouposition. - 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
contractVersionabaixo do que a disposição do modelo precisa: 2 para tabelas de linhas, 3 para rolos de talão (TEMPLATES_EDITOR_OUTDATEDcomrequiredVersion).
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 previewRepita 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.
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.