🔧 Variables y Helpers

Aprenda a usar variables dinámicas y helpers Handlebars para crear documentos potentes y flexibles.

📦 Variables Disponibles

👤 Datos del Cliente

{{customer.name}}          // Nombre completo
{{customer.email}}         // Email
{{customer.phone}}         // Teléfono
{{customer.document}}      // DNI/CUIT
{{customer.birth_date}}    // Fecha de nacimiento

📍 Dirección

{{customer.address.street}}      // Calle/Avenida
{{customer.address.number}}      // Número
{{customer.address.complement}}  // Complemento
{{customer.address.neighborhood}}// Barrio
{{customer.address.city}}        // Ciudad
{{customer.address.state}}       // Estado/Provincia
{{customer.address.zip_code}}    // Código Postal
{{customer.address.country}}     // País

📅 Datos del Sistema

{{date.current_date}}      // Fecha actual (2026-02-24)
{{date.current_time}}      // Hora actual (14:30:00)
{{organization.name}}      // Nombre de la organización
{{user.name}}              // Nombre del usuario que generó

🎯 Variables Personalizadas

Cree variables específicas para su plantilla:

{{custom.nombre_variable}}   // Valor personalizado

Ejemplo:

Valor del Contrato: $ {{custom.valor}}
Plazo de Entrega: {{custom.plazo}} días
Descuento: {{custom.descuento}}%

🛠️ Helpers Handlebars

Los helpers son funciones que transforman datos. Use la sintaxis: {{helper valor}}

🔤 Transformación de Texto

Mayúsculas

{{uppercase customer.name}}

Resultado: JUAN SILVA

Minúsculas

{{lowercase customer.name}}

Resultado: juan silva

Capitalizar (primera letra)

{{capitalize customer.name}}

Resultado: Juan silva

Title Case (todas las palabras)

{{titleCase customer.name}}

Resultado: Juan Silva

🔢 Números en Letras (Generales)

Portugués

{{formatInWordsPT custom.quantidade}}

Ejemplo: 250 → "duzentos e cinquenta"

Inglés

{{formatInWordsEN custom.quantity}}

Ejemplo: 250 → "two hundred and fifty"

Español

{{formatInWordsES custom.cantidad}}

Ejemplo: 250 → "doscientos cincuenta"

🔢 Operaciones Matemáticas

Aplique operaciones matemáticas a variables numéricas. Acepta variables o números literales en cualquier argumento.

{{divide valor divisor}}              // valor ÷ divisor
{{multiply valor factor}}             // valor × factor
{{add valor sumando}}                 // valor + sumando
{{subtract valor sustraendo}}         // valor − sustraendo
{{sum v1 v2 v3}}                      // suma varios valores

Ejemplos:

{{divide custom.valorTotal 4}}                    // Divide por 4 (ej: 1000 → 250)
{{divide custom.valorTotal custom.numCuotas}}    // Divide variable por otra variable
{{multiply custom.cantidad 2}}                   // Multiplica por 2
{{formatCurrencyBRL (divide custom.valorTotal 4)}}  // Valor ÷ 4 formateado en R$
{{sum custom.item1 custom.item2 custom.item3}}   // Suma varias variables

💰 Monedas (Número + Nombre de la Moneda)

💡 Consejo

Los helpers de moneda convierten el número y agregan el nombre de la moneda en letras.

Real Brasileño (BRL)

{{formatInWordsBRL custom.valor}}

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

Dólar Estadounidense (USD)

{{formatInWordsUSD custom.value}}

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

Euro (EUR)

{{formatInWordsEUR custom.value}}

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

Peso Argentino (ARS)

{{formatInWordsARS custom.valor}}

Ejemplo: 1350.50 → "mil trescientos cincuenta pesos argentinos"

Guaraní Paraguayo (PYG)

{{formatInWordsPYG custom.monto}}

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

⚠️ Atención

Los helpers monetarios incluyen el número Y el nombre de la moneda. No agregue "reais", "dólares", etc. manualmente, ya que quedará duplicado.

💵 Formato de Moneda (Símbolo)

Formatea el valor numérico con símbolo de moneda. Use el helper del país:

{{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 (sin sufijo) retorna solo el número formateado (1.350,50), sin símbolo.

📅 Fechas

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 corto

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

Día, mes y año (separados, acepta 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

Fecha y hora (acepta GMT, use "now" para ahora)

{{formatDateTimePT date.current_date}}           // 24/02/2026 às 14:30
{{formatDateTimePT "now" -3}}                    // Fecha/hora actual en GMT-3
{{formatDateTimeEN custom.fecha_hora}}           // Feb 24, 2026 at 14:30
{{formatDateTimeES custom.fecha_hora -4}}        // Con offset GMT-4

Solo hora (acepta GMT)

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

Usando con campos personalizados

Fecha de Vencimiento: {{formatDateES custom.fecha_vencimiento}}

💡 Fecha y hora actuales

Use "today" para la fecha actual y "now" para fecha/hora actual:

{{formatDateES "today"}}
{{formatDateTimeES "now" -3}}

🔗 Combinar Helpers

Puede combinar múltiples helpers usando paréntesis:

Texto en Mayúsculas + En Letras

{{uppercase (formatInWordsARS custom.valor)}}

Resultado: "MIL TRESCIENTOS CINCUENTA PESOS ARGENTINOS"

Fecha en Mayúsculas

{{uppercase (formatDateES date.current_date)}}

Resultado: "24 DE FEBRERO DE 2026"

Title Case + Moneda

{{titleCase (formatInWordsUSD custom.value)}}

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

Operación Matemática + Formato

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

Resultado: valor total ÷ 4 formateado en $ (ej: $ 250,00)

💡 Ejemplos Prácticos

Contrato de Prestación de Servicios

<h1>CONTRATO DE PRESTACIÓN DE SERVICIOS</h1>

<p><strong>CONTRATANTE:</strong> {{uppercase customer.name}}</p>
<p><strong>DNI:</strong> {{customer.document}}</p>
<p><strong>Dirección:</strong> {{customer.address.street}}, {{customer.address.number}} - {{customer.address.city}}/{{customer.address.state}}</p>

<h2>VALOR DEL CONTRATO</h2>
<p>El valor total de este contrato es de <strong>{{formatCurrencyARS custom.valor}}</strong> ({{formatInWordsARS custom.valor}}).</p>

<p>Firmado el {{formatDateES "today"}}.</p>

Ficha de Registro Multilingüe

<h2>Información del Cliente</h2>
<p><strong>Nombre:</strong> {{titleCase customer.name}}</p>
<p><strong>Email:</strong> {{lowercase customer.email}}</p>
<p><strong>Fecha de Registro:</strong> {{formatDateES date.current_date}}</p>

Informe Financiero

<h2>Informe Financiero</h2>

<table>
  <tr>
    <td>Valor Principal:</td>
    <td>{{formatInWordsARS custom.valor_principal}}</td>
  </tr>
  <tr>
    <td>Valor de la Cuota (÷ {{custom.num_cuotas}}):</td>
    <td>{{formatCurrencyARS (divide custom.valor_principal custom.num_cuotas)}}</td>
  </tr>
  <tr>
    <td>Fecha de Emisión:</td>
    <td>{{formatDateShortES "today"}}</td>
  </tr>
</table>

🎯 Consejos Avanzados

1. Formato Consistente

Use siempre el mismo helper para tipos de datos similares:

{{titleCase customer.name}}     // ✅ Consistente
{{uppercase customer.name}}     // ❌ Diferente del estándar

2. Contexto Visual

Agregue contexto alrededor de las variables:

DNI: {{customer.document}}                    // ✅ Con contexto
{{customer.document}}                          // ❌ Sin contexto

3. Valores Predeterminados

Para variables opcionales, considere usar condicionales (vea Condicionales):

{{#if custom.observaciones}}
  <p><strong>Observaciones:</strong> {{custom.observaciones}}</p>
{{/if}}

🎬 Próximo Paso

Aprenda a usar Condicionales para crear documentos aún más inteligentes y dinámicos!