A geração de documentos por mala direta consiste em ler valores de uma fonte de dados e colocar cada um no espaço reservado correspondente de um modelo. Você mantém duas coisas: um modelo que contém os campos de mesclagem (as variáveis à espera de preenchimento) e uma fonte de dados que fornece os valores mais tudo o que permanece igual em cada cópia. O motor de relatórios do PDF4me pega esses dois arquivos e devolve um documento pronto.
O PDF4me aceita modelos de Word, HTML e PDF, e o mais rico dos três é o Word. Com uma sintaxe curta e legível, você cria um único modelo do Word que cobre faturas, recibos, contratos, orçamentos ou qualquer documento personalizado, e gera milhares a partir de dados. Este guia percorre toda a sintaxe — campos de mesclagem, condições, formatação, tabelas, imagens e HTML embutido — com exemplos prontos para copiar e um modelo de exemplo que você pode baixar e executar. Cada link de sintaxe aponta para a página exata da documentação da sintaxe de modelos do Word.
Escreva espaços reservados como <<[FieldName]>> em um documento do Word. Adicione condições, formatação, laços, imagens e HTML com alguns tokens a mais. Envie esse modelo junto com um arquivo de dados JSON (ou XML) para a ação Generate Document do PDF4me e você recebe de volta um documento personalizado e pronto — uma vez ou aos milhares.
Como você cria um modelo do Word?
Tudo começa com um espaço reservado. Em qualquer lugar em que queira inserir um valor, digite o nome do campo envolto em colchetes angulares duplos e colchetes:
<<[FieldName]>>
O nome entre colchetes precisa corresponder a uma propriedade da sua fonte de dados. Mantenha nomes descritivos, use uma única convenção (camelCase ou PascalCase) e evite caracteres especiais. Aqui está um modelo mínimo e os dados que o preenchem:
Dear <<[CustomerName]>>,
Thank you for your order #<<[OrderNumber]>>.
{
"CustomerName": "John Smith",
"OrderNumber": "12345"
}
O motor retorna:
Dear John Smith,
Thank you for your order #12345.
Essa é a ideia toda. Tudo abaixo é uma variação do mesmo princípio — condições, laços e formatação sempre envolvem campos de mesclagem comuns. Os detalhes completos estão na Visão geral da sintaxe.
Como adicionar condições a um modelo?
A ação Generate Document pode se ramificar conforme os seus dados. Dependendo de a condição ser verdadeira, ela insere um bloco de conteúdo ou outro. A estrutura básica if / elseif / else se lê assim:
<<if [condition1]>> Add the first block
<<elseif [condition2]>> Add the second block
<<else>> Add the fallback block
<</if>>
As condições podem testar um valor diretamente ou apoiar-se nos métodos de enumeração (mais sobre isso abaixo), por exemplo <<if [employees.Any(p => p.Age > 50)]>>. Você encontra o conjunto completo de operadores de comparação e lógicos em Lógica condicional.
Como formatar valores em um modelo?
Muitas vezes um valor bruto precisa ser preparado antes de ser colocado — uma data em um estilo específico, um número arredondado, texto em maiúsculas. Adicione uma especificação de formato após o nome do campo, separada por dois-pontos e entre aspas:
<<[token]:"format">>
As datas usam um padrão no estilo .NET:
Invoice Date: <<[invoiceDate]:"dd.MM.yyyy">>
Due Date: <<[dueDate]:"MMMM dd, yyyy">>
Maiúsculas e minúsculas têm seus próprios modificadores curtos — :upper, :caps (capitalizar cada palavra) e :firstCap:
Customer: <<[customerName]:upper>>
Product: <<[productName]:caps>>
Números usam formatos numéricos padrão, de modo que <<[price]:"F2">> fixa um valor em duas casas decimais. A lista completa de padrões de data, texto e número está em Formatação em modelos.
Como construir tabelas a partir de uma lista?
É nas tabelas que a geração de documentos mostra seu valor — uma linha do modelo se expande em quantas linhas seus dados tiverem. Crie uma tabela normal do Word, abra um laço <<foreach>> na primeira célula, adicione um campo de mesclagem em cada célula seguinte e feche o laço na última célula:
Column 1: <<foreach [product in products]>><<[product.productName]>>
Column 2: <<[product.manufactured]:"yyyy.MM.dd">>
Column 3: <<[product.price]>><</foreach>>
Cada objeto do array products vira uma linha, e você pode formatar células embutidas como em qualquer outro lugar. Mais padrões de tabela, incluindo linhas filtradas e agregadas, são tratados em Tabelas em modelos.
Como repetir parágrafos e seções?
O mesmo laço <<foreach>> funciona também fora das tabelas. Envolva qualquer bloco de conteúdo — um parágrafo, um título com seu corpo, uma seção inteira — e ele se repete uma vez por item da coleção:
<<foreach [item in collection]>>
Content with <<[item.property]>>
<</foreach>>
Os laços podem ser aninhados (uma seção por departamento, uma linha por funcionário dentro dela) e podem filtrar ou ordenar a coleção no caminho. Veja Repetir parágrafos e seções para exemplos aninhados e condicionais.
Como adicionar imagens a um modelo?
O PDF4me pode inserir imagens em um documento gerado a partir de uma URL pública ou de uma string Base64. Uma regra importa: o campo de imagem precisa ficar dentro de uma Caixa de texto do Word. Crie a caixa de texto onde quiser a imagem e depois adicione o campo.
A partir de uma URL pública:
<<image [imageUrl]>>
A partir de uma string codificada em Base64:
<<image [imageBase64]>>
Você controla o tamanho com modificadores como -keepRatio, -fitHeight, -fitWidth e -fitSize, por ex. <<image [companyLogo] -keepRatio>>. A referência completa de tamanhos e exemplos de imagens por linha estão em Inserir imagens.
Como inserir HTML em um modelo?
Se seus dados já contêm HTML formatado, renderize-o no lugar com o modificador -html em vez de escapá-lo como texto simples:
<<[token] -html>>
O motor analisa o valor do campo como HTML e aplica a formatação — negrito, itálico, listas, títulos, spans coloridos e mais — dentro do documento gerado. As tags e estilos suportados estão listados em Inserir HTML.
Trabalhe com seus dados usando métodos de enumeração
Além dos campos simples, o motor expõe métodos no estilo IEnumerable que você pode chamar diretamente dentro de um token — filtrar, ordenar, contar, calcular média e mais. Alguns exemplos:
Total products: <<[products.Count()]>>
Average price: $<<[products.Average(p => p.price)]:"F2">>
Top items: <<foreach [p in products.OrderByDescending(x => x.price).Take(5)]>><<[p.name]>><</foreach>>
Eles se combinam naturalmente com condições e laços. A lista completa de métodos — Where, OrderBy, GroupBy, Sum, Any, First e o restante — está em Enumeração em modelos.
Os dados de exemplo têm esta aparência — um fornecedor, um cliente e uma lista de produtos sobre a qual o modelo itera:
{
"VendorName": "PDF4me",
"VendorCity": "Zurich",
"VendorCountry": "Switzerland",
"VendorZip": "8630",
"VendorContact": "123456",
"InvoiceDate": "22-08-2022",
"CustomerName": "John Doe",
"CustomerCity": "Start City",
"CustomerCountry": "US",
"CustomerZip": "3214",
"products": [
{ "productName": "PDF Converter", "value": 2000, "expires": "01/08/2025" },
{ "productName": "PDF API", "value": 1250, "expires": "18/02/2029" },
{ "productName": "PDF Editor", "value": 1999, "expires": "12/12/2027" }
],
"comments": "This document is <b>computer generated</b> and does not require a signature."
}
Observe que comments traz HTML — combine-o com o modificador <<[comments] -html>> e a tag <b> será renderizada em negrito na saída.
Links rápidos para criar seu modelo
Perguntas frequentes
Como criar campos de mesclagem em um modelo do Word?
Digite o nome do campo entre colchetes angulares duplos e colchetes, como <<[CustomerName]>>, onde quiser inserir um valor. O nome precisa corresponder a uma propriedade da sua fonte de dados JSON ou XML. Você pode adicionar campos manualmente em qualquer lugar — títulos, parágrafos, células de tabela ou caixas de texto.
Quais formatos de modelo o PDF4me suporta?
Word (.docx, .doc), HTML e PDF. Os três usam a mesma sintaxe de campos de mesclagem, então o que você aprende para um modelo do Word se transfere. O Word oferece o controle mais completo sobre layout, condições, tabelas e imagens.
Posso adicionar condições if/else a um modelo do Word?
Sim. Envolva o conteúdo com <<if [condition]>> ... <<elseif [condition]>> ... <<else>> ... <</if>>. Uma condição pode comparar um campo diretamente ou chamar um método de enumeração como Any() ou Count(). Assim um único modelo lida com cada variação dos seus dados em vez de manter um arquivo por caso.
Como formatar datas e números em um modelo?
Coloque o formato após o nome do campo, entre aspas: <<[invoiceDate]:"dd.MM.yyyy">> para uma data, <<[price]:"F2">> para um número com duas casas decimais. Maiúsculas e minúsculas têm modificadores curtos — :upper, :caps e :firstCap.
Como gerar uma tabela que cresce com meus dados?
Crie uma tabela do Word, abra <<foreach [item in collection]>> na primeira célula, coloque um campo de mesclagem em cada célula restante e feche com <</foreach>> na última célula. Cada item da coleção vira automaticamente uma linha.
Solução de problemas
Próximos passos
Crie o modelo uma vez, conecte-o aos seus dados, e o PDF4me produz faturas, contratos e relatórios personalizados sob demanda — a partir de uma única chamada de API ou de uma automação que processa milhares de uma vez.