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.document}} // CPF/CNPJ (formatado)
{{customer.email}} // Email
{{customer.phone}} // Telefone
{{customer.whatsapp}} // WhatsApp
{{customer.created_at}} // Data de cadastro
{{customer.stage_name}} // Estágio no funil
{{customer.tags}} // Tags (separadas por vírgula)

Endereço (endereço padrão do cliente)

{{customer.address}} // Endereço completo (texto)
{{customer.formatted_address}} // Endereço formatado (Maps, se houver)
{{customer.address_line_1}} // Logradouro
{{customer.address_line_2}} // Complemento
{{customer.city}} // Cidade
{{customer.state}} // Estado (UF)
{{customer.postal_code}} // CEP
{{customer.country}} // País

Endereço usado

O sistema usa o endereço marcado como padrão (is_default). Se não houver padrão, usa o endereço mais recente.

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)

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!