🔧 Variáveis e Helpers

Aprenda a usar variáveis dinâmicas e helpers Handlebars para criar documentos poderosos e flexíveis.

📦 Variáveis Disponíveis

👤 Dados do Cliente

{{customer.name}}          // Nome completo
{{customer.email}}         // Email
{{customer.phone}}         // Telefone
{{customer.document}}      // CPF/CNPJ
{{customer.birth_date}}    // Data de nascimento

📍 Endereço

{{customer.address.street}}      // Rua/Avenida
{{customer.address.number}}      // Número
{{customer.address.complement}}  // Complemento
{{customer.address.neighborhood}}// Bairro
{{customer.address.city}}        // Cidade
{{customer.address.state}}       // Estado (UF)
{{customer.address.zip_code}}    // CEP
{{customer.address.country}}     // País

📅 Dados do Sistema

{{date.current_date}}      // Data atual (2026-02-24)
{{date.current_time}}      // Hora atual (14:30:00)
{{organization.name}}      // Nome da organização
{{user.name}}              // Nome do usuário que gerou

🎯 Variáveis Customizadas

Crie variáveis específicas para seu modelo:

{{custom.nome_variavel}}   // Valor personalizado

Exemplo:

Valor do Contrato: R$ {{custom.valor}}
Prazo de Entrega: {{custom.prazo}} dias
Desconto: {{custom.desconto}}%

🛠️ Helpers Handlebars

Helpers são funções que transformam dados. Use a sintaxe: {{helper valor}}

🔤 Transformação de Texto

Maiúsculas

{{uppercase customer.name}}

Resultado: JOÃO SILVA

Minúsculas

{{lowercase customer.name}}

Resultado: joão silva

Capitalizar (primeira letra)

{{capitalize customer.name}}

Resultado: João silva

Title Case (todas as palavras)

{{titleCase customer.name}}

Resultado: João Silva

🔢 Números por Extenso (Gerais)

Português

{{formatInWordsPT custom.quantidade}}

Exemplo: 250 → "duzentos e cinquenta"

Inglês

{{formatInWordsEN custom.quantidade}}

Exemplo: 250 → "two hundred and fifty"

Espanhol

{{formatInWordsES custom.cantidad}}

Exemplo: 250 → "doscientos cincuenta"

🔢 Operações Matemáticas

Aplique operações matemáticas em variáveis numéricas. Aceita variáveis ou números literais em qualquer argumento.

{{divide valor divisor}}              // valor ÷ divisor
{{multiply valor fator}}               // valor × fator
{{add valor adendo}}                  // valor + adendo
{{subtract valor subtraendo}}         // valor − subtraendo
{{sum v1 v2 v3}}                      // soma vários valores

Exemplos:

{{divide custom.valorTotal 4}}                    // Divide por 4 (ex: 1000 → 250)
{{divide custom.valorTotal custom.numParcelas}}   // Divide variável por outra variável
{{multiply custom.quantidade 2}}                 // Multiplica por 2
{{formatCurrencyBRL (divide custom.valorTotal 4)}}  // Valor ÷ 4 formatado em R$
{{sum custom.item1 custom.item2 custom.item3}}   // Soma várias variáveis

💰 Moedas (Número + Nome da Moeda)

💡 Dica

Helpers de moeda convertem o número e adicionam o nome da moeda por extenso.

Real Brasileiro (BRL)

{{formatInWordsBRL custom.valor}}

Exemplo: 1350.50 → "mil trezentos e cinquenta reais e cinquenta centavos"

Dólar Americano (USD)

{{formatInWordsUSD custom.value}}

Exemplo: 1350.50 → "one thousand three hundred fifty dollars and fifty cents"

Euro (EUR)

{{formatInWordsEUR custom.value}}

Exemplo: 1350.50 → "one thousand three hundred fifty euros and fifty cents"

Peso Argentino (ARS)

{{formatInWordsARS custom.valor}}

Exemplo: 1350.50 → "mil trescientos cincuenta pesos argentinos"

Guarani Paraguaio (PYG)

{{formatInWordsPYG custom.monto}}

Exemplo: 1350 → "mil trescientos cincuenta guaraníes"

⚠️ Atenção

Helpers monetários incluem o número E o nome da moeda. Não adicione "reais", "dólares", etc. manualmente, pois ficará duplicado.

💵 Formatação de Moeda (Símbolo)

Formata valor numérico com símbolo da moeda. Use o helper do país desejado:

{{formatCurrencyBRL custom.valor}}     // R$ 1.350,50
{{formatCurrencyUSD custom.valor}}     // $1,350.50
{{formatCurrencyEUR custom.valor}}     // 1.350,50 €
{{formatCurrencyARS custom.valor}}     // $ 1.350,50

formatCurrency (sem sufixo) retorna apenas o número formatado (1.350,50), sem símbolo.

📅 Datas

Formato completo (PT, EN, ES)

{{formatDatePT date.current_date}}     // 24 de fevereiro de 2026
{{formatDateEN date.current_date}}     // February 24, 2026
{{formatDateES date.current_date}}     // 24 de febrero de 2026

Formato curto

{{formatDateShortPT date.current_date}}  // 24/02/2026
{{formatDateShortEN date.current_date}}  // 02/24/2026
{{formatDateShortES date.current_date}}  // 24/02/2026

Dia, mês e ano (separados, aceita GMT)

{{formatDay date.current_date}}        // 24
{{formatMonthPT date.current_date}}    // fevereiro
{{formatMonthEN date.current_date}}    // February
{{formatMonthES date.current_date}}    // febrero
{{formatYear date.current_date}}       // 2026

Data e hora (aceita GMT, use "now" para agora)

{{formatDateTimePT date.current_date}}           // 24/02/2026 às 14:30
{{formatDateTimePT "now" -3}}                    // Data/hora atual em GMT-3
{{formatDateTimeEN custom.data_hora}}            // Feb 24, 2026 at 14:30
{{formatDateTimeES custom.data_hora -4}}         // Com offset GMT-4

Apenas hora (aceita GMT)

{{formatTime custom.horario}}          // 14:30
{{formatTimeWithSeconds custom.horario}}  // 14:30:00
{{formatTime "now" -3}}                // Hora atual em GMT-3

Usando com campos customizados

Data de Vencimento: {{formatDatePT custom.data_vencimento}}

💡 Data e hora atuais

Use "today" para data atual e "now" para data/hora atual:

{{formatDatePT "today"}}
{{formatDateTimePT "now" -3}}

🔗 Combinar Helpers

Você pode combinar múltiplos helpers usando parênteses:

Texto em Maiúsculas + Por Extenso

{{uppercase (formatInWordsBRL custom.valor)}}

Resultado: "MIL TREZENTOS E CINQUENTA REAIS E CINQUENTA CENTAVOS"

Data em Maiúsculas

{{uppercase (formatDatePT date.current_date)}}

Resultado: "24 DE FEVEREIRO DE 2026"

Title Case + Moeda

{{titleCase (formatInWordsUSD custom.value)}}

Resultado: "One Thousand Three Hundred Fifty Dollars And Fifty Cents"

Operação Matemática + Formatação

{{formatCurrencyBRL (divide custom.valorTotal 4)}}

Resultado: valor total ÷ 4 formatado em R$ (ex: R$ 250,00)

💡 Exemplos Práticos

Contrato de Prestação de Serviços

<h1>CONTRATO DE PRESTAÇÃO DE SERVIÇOS</h1>

<p><strong>CONTRATANTE:</strong> {{uppercase customer.name}}</p>
<p><strong>CPF:</strong> {{customer.document}}</p>
<p><strong>Endereço:</strong> {{customer.address.street}}, {{customer.address.number}} - {{customer.address.city}}/{{customer.address.state}}</p>

<h2>VALOR DO CONTRATO</h2>
<p>O valor total deste contrato é de <strong>{{formatCurrencyBRL custom.valor}}</strong> ({{formatInWordsBRL custom.valor}}).</p>

<p>Firmado em {{formatDatePT "today"}}.</p>

Ficha de Cadastro Multilíngue

<h2>Customer Information</h2>
<p><strong>Name:</strong> {{titleCase customer.name}}</p>
<p><strong>Email:</strong> {{lowercase customer.email}}</p>
<p><strong>Registration Date:</strong> {{formatDateEN date.current_date}}</p>

Relatório com Cálculos

<h2>Relatório Financeiro</h2>

<table>
  <tr>
    <td>Valor Principal:</td>
    <td>{{formatInWordsBRL custom.valor_principal}}</td>
  </tr>
  <tr>
    <td>Valor da Parcela (÷ {{custom.num_parcelas}}):</td>
    <td>{{formatCurrencyBRL (divide custom.valor_principal custom.num_parcelas)}}</td>
  </tr>
  <tr>
    <td>Data de Emissão:</td>
    <td>{{formatDateShortPT "today"}}</td>
  </tr>
</table>

🎯 Dicas Avançadas

1. Formatação Consistente

Use sempre o mesmo helper para tipos similares de dados:

{{titleCase customer.name}}     // ✅ Consistente
{{uppercase customer.name}}     // ❌ Diferente do padrão

2. Contexto Visual

Adicione contexto ao redor das variáveis:

CPF: {{customer.document}}                    // ✅ Com contexto
{{customer.document}}                          // ❌ Sem contexto

3. Valores Padrão

Para variáveis opcionais, considere usar condicionais (veja Condicionais):

{{#if custom.observacoes}}
  <p><strong>Observações:</strong> {{custom.observacoes}}</p>
{{/if}}

🎬 Próximo Passo

Aprenda a usar Condicionais para criar documentos ainda mais inteligentes e dinâmicos!