Plantillas de Documentos (DOCX)

Índice

• Introducción
• Cómo subir tu plantilla
• Cómo se escriben las variables
• Variables de Cotizaciones, Facturas y Notas de Débito
  • Cliente
  • Dirección de envío
  • Datos del documento
  • Productos
  • Totales e impuestos
  • Formas de pago
  • Notas del documento
  • Totales en dólares y otras monedas
  • Otras variables del documento
  • Bloques XML armados
  • Campos personalizados
  • Diferencias entre cotización, factura y nota de débito
• Variables de Notas de Crédito
• Variables de la plantilla de Notas de Entrega
  • Datos del documento
  • Origen de la mercancía
  • Destino de la mercancía
  • Productos
  • Condiciones que cambian los datos
• Variables de Guías de Despacho
• Ejemplos completos
• Errores frecuentes

---

Introducción

Cachicamo genera cada documento rellenando una plantilla de Word (formato .docx) con los datos de la operación. La plantilla la puedes personalizar: descarga la actual como base, edítala en Word agregando o quitando variables, y súbela de vuelta.

Se pueden personalizar seis plantillas:

• Cotizaciones y notas de entrega: se configuran en Configuración, en las pestañas Cotizaciones y Notas de entrega.
• Facturas, notas de crédito, notas de débito y guías de despacho: se configuran en Medios de Facturación, dentro del medio de emisión de tipo Forma Libre / Talonario Manual o Contingencia que no sea talonario manual.

Cada tienda tiene sus propias plantillas. En este manual encontrarás todas las variables que puedes usar, qué inserta cada una y en qué casos cambia su contenido.

---

Cómo subir tu plantilla

1. Entra al lugar donde vive la plantilla que quieres cambiar:
   • Configuración → pestaña Cotizaciones o pestaña Notas de entrega.
   • Medios de Facturación → el medio de tipo Forma Libre / Talonario Manual o Contingencia (sección de plantillas).
2. Descarga la plantilla actual con el enlace Ver plantilla actual y úsala como punto de partida.
3. Edita el archivo en Word y guarda los cambios conservando el formato .docx. No uses .doc ni cambies la extensión de otro archivo (por ejemplo, un PDF renombrado).
4. Secciónalo en el campo de archivo y guarda la configuración.

Al elegir el archivo, Cachicamo revisa la plantilla antes de subirla. Si algo está roto, la subida se detiene y te muestra el motivo:

• El archivo no es un documento de Word válido: está dañado o no es un .docx real.
• Etiquetas mal escritas: una llave quedó sin cerrar, o una lista de productos quedó abierta sin su cierre.
• Variables que no existen: la plantilla usa un nombre que no está en la lista de este manual (por ejemplo, un nombre mal escrito). El aviso te dice cuáles son para que los corrijas.

Una plantilla que pasa la revisión se guarda y se usa en la próxima emisión del documento.

---

Cómo se escriben las variables

• Una variable se escribe entre llaves, tal como aparece en este manual: {customer_name}, {document_total}, {document_note}.
• Los nombres distinguen mayúsculas y minúsculas, no llevan espacios y no deben llevar tildes ni ñ.
• Para repetir un bloque por cada elemento de una lista se usa una apertura {#lista} y un cierre {/lista}. Todo lo que esté entre ambas se repite una vez por elemento.
• Para mostrar un bloque solo cuando una condición se cumple se usa la misma sintaxis con una variable de sí o no: {#has_shipping_address}...{/has_shipping_address}. Si la condición es falsa, el bloque no aparece.
• Las variables cuyo nombre termina en Xml ya vienen con formato y saltos de línea listos (negritas, tablas, párrafos). Se usan siempre precedidas de arroba: {@document_noteXml}, {@nameXml}, {@xmlTotals}. Sin la arroba, Word imprimiría el marcado y no el contenido.
• Si una variable no aplica o no tiene valor, en la mayoría de los casos inserta -- o queda vacía, según se indica en cada tabla.

Ejemplo de una tabla de productos en Word (fila de encabezado y fila que se repite):

| Producto          | Cantidad    | Precio      | Total           |
| {#products}{name} | {quantity}  | {unit_price}| {total}{/products} |

Cada fila de la tabla se repetirá por cada producto del documento, y dentro de la fila funcionan las variables de producto ({name}, {quantity}, {unit_price}, {total}, {sku}, etc.).

---

Variables de Cotizaciones, Facturas y Notas de Débito

Los tres documentos se arman con la misma lista de variables; las diferencias entre ellos se explican al final de la sección.

Cliente

Variable	Ejemplo de lo que inserta	Cuándo aplica / notas
customer_name	Ferretería El Tornillo, C.A.	Razón social si es empresa; si no, el nombre del cliente.
customer_dni	J-12345678-9	RIF de la empresa; si no, la cédula del cliente.
customer_address	Av. Libertador, Caracas, 1010, Venezuela	Dirección fiscal completa: calle, estado, código postal y país, unidos por punto y coma.
customer_phone	0414-1234567	Teléfono del cliente.
customer_email	compras@eltornillo.com	Correo del cliente.
customer_extra_fields_plain	Vendedor: Luis; Zona: Centro	Todos los campos adicionales del cliente, separados por ; . Queda vacío si el cliente no tiene.
customer_extra_fields_xml	Vendedor: Luis; Zona: Centro	Igual que el anterior, con la etiqueta de cada campo en negrita. Se usa con {@customer_extra_fields_xml}.

Dirección de envío

Estas variables se llenan solo cuando el documento se creó con una dirección de envío. Si no la tiene, los campos de dirección quedan vacíos y los nombres caen al cliente.

Variable	Ejemplo de lo que inserta	Cuándo aplica / notas
has_shipping_address	verdadero / falso	Se usa para decidir si se imprime el bloque de envío: {#has_shipping_address}...{/has_shipping_address}.
shipping_address	Calle 5, Galpón 3, Zona Industrial	Dirección de envío tal como se escribió al emitir.
shipping_address_with_extra_fields	Dirección de Envío: Calle 5, Galpón 3... y debajo los campos adicionales del cliente.	Dirección de envío más los campos adicionales del cliente en líneas aparte.
shipping_addressXml	La misma dirección con el rótulo en negrita.	Se usa con {@shipping_addressXml}.
shipping_addressXml_with_extra_fields	Dirección y campos adicionales con formato.	Se usa con {@shipping_addressXml_with_extra_fields}.
shipping_full_name	María Rodríguez	Nombre de quien recibe. Si no se indicó, usa el del cliente.
shipping_dni	V-12345678	RIF o cédula de quien recibe. Si no se indicó, usa el del cliente.
shipping_phone	0424-7654321	Teléfono de quien recibe. Si no se indicó, usa el del cliente.

Datos del documento

Variable	Ejemplo de lo que inserta	Cuándo aplica / notas
document_number	COT-00000123	Número del documento con el prefijo y sufijo configurados en la tienda.
document_date	12/09/2026	Fecha de emisión del documento.
document_total_in_letters	CIENTO DIECISÉIS MIL BOLÍVARES CON 00/100	Total general escrito en letras.
total_quantities	12	Suma de las cantidades de todos los renglones. No incluye la unidad de medida.
is_payed	verdadero / falso	Indica si el documento ya quedó pagado por completo.
printer_error	--	Mensaje de error de la imprenta digital, cuando existe. En forma libre normalmente va vacío.
with_tax_no_invoiced	falso	Reservado para uso interno; siempre llega en falso.
invoice_number	FACT-00000987	Número de la factura a la que está vinculada la nota de débito. En cotizaciones y facturas va vacío.
invoice_date	01/09/2026	Fecha de la factura vinculada a la nota de débito. En cotizaciones y facturas va vacío.

Productos

La lista de renglones se recorre con {#products} y {/products}. Dentro del bloque se usan estas variables:

Variable	Ejemplo de lo que inserta	Cuándo aplica / notas
name	2 x Tornillo autorroscante - SKU: TOR-100, 3 x 5 cm UND (G) (E)\nMedida: 5cm; Color: Azul\nImp. LISAEA: Bs. 5,00\nNota extra: soldadura incluida\nPrecio de lista: Bs. 120,00 · Descuento: -Bs. 20,00	Descripción completa del renglón en texto plano. Puede incluir la cantidad del empaque, el SKU, el volumen, el código del impuesto, la marca (E) de exento, los atributos del producto, el monto de LISAEA, la nota extra, la personalización y el desglose de precio de lista y descuento. Cuando el renglón se factura por cuenta de un tercero, el RIF y el nombre del tercero vienen al inicio del nombre. Cada dato agregado va en su propia línea cuando corresponde.
nameXml	La misma descripción, con los rótulos en negrita y los saltos de línea ya armados.	Se usa con {@nameXml} para conservar el formato. Es la variable recomendada para la columna de producto.
quantity	2 UND	Cantidad del renglón con la abreviatura de la unidad de medida, cuando el producto la tiene.
unit_price	Bs. 45,00	Precio unitario formateado en la moneda del documento. Con precios en moneda extranjera activados, muestra primero la moneda principal y entre paréntesis la otra.
total	Bs. 90,00	Total del renglón formateado, con el mismo criterio de monedas que el precio unitario.
unit_price_raw	45	Precio unitario como número, sin símbolo ni separadores.
total_raw	90	Total del renglón como número, sin símbolo ni separadores.
sku	TOR-100	Código del producto. Queda vacío si el producto no tiene SKU.
product_name_without_sku	2 x Tornillo autorroscante, 3 x 5 cm UND (G) (E)	Descripción sin el sufijo - SKU: ....
product_categories	- Categoría: Herrajes, Tornillería	Categorías del producto precedidas por -. Queda vacío si no tiene categorías.
is_exempt	verdadero / falso	Verdadero cuando el renglón es exento, exonerado o no gravado. La letra (E) igual aparece dentro del nombre.

Totales e impuestos

Variable	Ejemplo de lo que inserta	Cuándo aplica / notas
document_subtotal	Bs. 1.000,00	Subtotal de productos.
document_total_taxes	Bs. 160,00	Suma de los impuestos del documento.
document_total	Bs. 1.160,00	Total general del documento.
total_to_pay	Bs. 1.160,00	Saldo pendiente por pagar. Si el documento tiene retención congelada, se calcula sobre el neto de esa retención.
total_taxes_retained	Bs. 116,00	Total de impuestos retenidos.
total_payed	Bs. 500,00	Total pagado hasta ahora.
total_refunded	Bs. 20,00	Total devuelto.
total_pending_refund	Bs. 0,00	Total pendiente por devolver.
credit_amount_available	Bs. 300,00	Saldo a favor disponible del cliente.
credit_amount_applied	Bs. 300,00	Saldo a favor aplicado a este documento.
document_total_percibido	Bs. 1.160,00	Base del IVA percibido, cuando la operación lo aplica.

Los impuestos se recorren con {#taxes} y {/taxes}. Cada fila trae estos campos:

Variable	Ejemplo de lo que inserta	Cuándo aplica / notas
name	IVA 16% (G)	Nombre del impuesto con su alícuota y su código.
amount	Bs. 160,00	Monto del impuesto formateado.
taxable_amount	Bs. 1.000,00	Base imponible formateada.
amount_raw	160	Monto como número, sin formato.
taxable_amount_raw	1000	Base imponible como número, sin formato.

La lista taxes_without_exempt funciona igual, pero excluye los impuestos con tasa cero: exentos, exonerados y no gravados. Exceptúa al IVA percibido y a LISAEA, que sí aparecen aunque su tasa sea cero. Si no queda ninguna fila, se agrega una fila con el IVA general (código G) en cero para que la tabla nunca quede vacía.

Formas de pago

Variable	Ejemplo de lo que inserta	Cuándo aplica / notas
payment_methods	Efectivo (Bs. 1.160,00) | Crédito por Retenciones: Bs. 116,00	Formas de pago en la moneda del documento, separadas por |. Incluye el crédito aplicado, la retención y el saldo a crédito cuando correspondan. Si no hay ninguno, inserta --.
external_payment_methods	Zelle (USD 100,00) (Bs. 3.650,00)	Formas de pago hechas en otra moneda, con el equivalente entre paréntesis. Se separan igual que las anteriores.
payment_methods_with_refund	Efectivo (Bs. 1.160,00) | Vuelto: Efectivo (Bs. 40,00)	Las formas de pago en moneda del documento más los vueltos entregados.
external_payment_methods_with_refund	Zelle (USD 100,00) (Bs. 3.650,00) | Vuelto: Zelle (USD 10,00) (Bs. 365,00)	Las formas de pago en otra moneda más los vueltos.
payment_methods_refund	Vuelto: Efectivo (Bs. 40,00)	Solo los vueltos en la moneda del documento.
external_payment_methods_refund	Vuelto: Zelle (USD 10,00)	Solo los vueltos en otra moneda.
payments	Lista de pagos	Se recorre con {#payments} y {/payments}. Cada fila trae name (forma de pago), amount (monto formateado) y amount_raw (monto como número).
payments_refund	Lista de vueltos	Se recorre con {#payments_refund} y {/payments_refund}. Cada fila trae name, amount y amount_raw.

Notas del documento

Variable	Ejemplo de lo que inserta	Cuándo aplica / notas
document_note	Entregar antes del viernes - Tasa Utilizada -> USD: 36,5000	Texto plano de las notas. Incluye la nota escrita al emitir y, cuando hay tasas de cambio, la línea con la tasa utilizada.
document_noteXml	El mismo texto con formato y justificado.	Se usa con {@document_noteXml}. Es la variable recomendada para el bloque de observaciones.
document_note_with_extra_fields	Las notas y, al final, los campos adicionales del cliente.	Texto plano.
document_noteXml_with_extra_fields	Las notas y los campos adicionales con formato.	Se usa con {@document_noteXml_with_extra_fields}.
document_note_without_days_to_pay	Las notas sin la mención de la condición de pago.	Texto plano. En facturas y notas de débito a crédito es el texto antes de anteponer la condición de pago; en cotizaciones es igual a document_note.
document_noteXml_without_days_to_pay	Las notas sin la condición de pago, con formato.	Se usa con {@document_noteXml_without_days_to_pay}.
daysToPayNote	Para pagar máximo en 30 días	Mensaje de condición de pago: pago a contado, o los días máximos para pagar. En cotizaciones va vacío y en facturas y notas de débito a crédito se antepone a document_note.

Totales en dólares y otras monedas

Estas variables insertan el equivalente en la otra moneda del documento (normalmente dólares). Cuando el documento no tiene ese equivalente, insertan --.

Variable	Ejemplo de lo que inserta
total_invoice_usd	USD 31,78
total_to_pay_usd	USD 31,78
total_products_usd	USD 27,40
total_taxes_usd	USD 4,38
total_taxes_retained_usd	USD 3,18
total_payed_usd	USD 13,70
total_refunded_usd	USD 0,55
total_pending_refund_usd	USD 0,00
document_total_percibido_usd	USD 31,78

Otras variables del documento

Variable	Ejemplo de lo que inserta	Cuándo aplica / notas
metadata	El bloque de datos internos del documento	Objeto completo con los datos guardados al emitir (nota original, dirección de envío, campos adicionales del cliente, configuración de la tienda y otros). Se lee abriendo un bloque: {#metadata}{#printer_custom_data}{clave}{/printer_custom_data}{/metadata}. Las variables con punto dentro del nombre ({metadata.note}) no funcionan: en su lugar se abre el bloque de cada dato. Solo para plantillas avanzadas: los datos internos pueden cambiar entre versiones.

Bloques XML armados

Estas variables insertan tablas completas ya armadas y con estilos, listas para pegar en la plantilla. Se usan siempre con arroba.

Variable	Qué inserta	Cuándo aplica / notas
xmlTotals	La tabla de totales del documento: subtotal, impuestos, otros impuestos, total a pagar, descuentos aplicados y las columnas en la segunda moneda cuando correspondan.	Se usa con {@xmlTotals}. Una sola variable reemplaza toda la tabla.
xmlTotalsWithExempt	La misma tabla, agregando la fila de Base Exenta cuando el documento tiene renglones exentos.	Se usa con {@xmlTotalsWithExempt}.
products	Lista de renglones. Además de las variables de cada producto, cada elemento expone nameXml, que arma la descripción con formato.	Se usa con {@nameXml} dentro del bloque.
document_noteXml	Nota del documento con formato y justificado.	Se usa con {@document_noteXml}.
shipping_addressXml	Dirección de envío con formato.	Se usa con {@shipping_addressXml}.

Campos personalizados

En la misma pantalla puedes crear campos personalizados, que son datos que tu equipo completa al emitir el documento (por ejemplo, vendedor, orden de compra o condiciones especiales). Cada campo genera una variable:

• El nombre de la variable es custom_document_data. seguido de la clave del campo.
• La clave sale de la etiqueta del campo: se pasa a minúsculas, los espacios y símbolos se vuelven guiones bajos, y las tildes se quitan. Por ejemplo, la etiqueta Vendedor produce custom_document_data.vendedor, y Número de orden produce custom_document_data.numero_de_orden.
• Si el campo no se llenó al emitir, la variable inserta un espacio vacío.

Hay dos formas de leer un campo en la plantilla:

• Directa, la más simple: {custom_document_data.numero_de_orden}.
• Agrupada, dentro de los datos del documento: {#metadata}{#printer_custom_data}{numero_de_orden}{/printer_custom_data}{/metadata}. Algunas plantillas hechas a medida usan esta forma; el bloque se oculta si el documento no guardó datos personalizados.

Ejemplo: si creaste el campo Número de orden, en la plantilla escribes {custom_document_data.numero_de_orden} y al imprimir sale OC-4521.

Diferencias entre cotización, factura y nota de débito

Las variables son las mismas, pero su contenido cambia según el documento:

Aspecto	Cotización	Factura y nota de débito
daysToPayNote	Vacío.	Trae el mensaje de pago a contado o de días máximos para pagar.
document_note	Nota escrita al emitir más la línea de tasas.	Nota escrita al emitir, las menciones legales que apliquen (por ejemplo el IGTF a crédito) y la línea de tasas. En documentos a crédito, la condición de pago va al inicio.
Línea de tasas	Muestra solo la tasa de cada moneda.	Muestra la tasa y el total convertido a esa moneda.
invoice_number / invoice_date	Vacíos.	En notas de débito traen la factura vinculada; en facturas van vacíos.

---

Variables de Notas de Crédito

Las notas de crédito usan la misma lista de la sección anterior, con estas diferencias:

No existen en notas de crédito:

Variable	Nota
payments_refund	La nota de crédito no separa los pagos devueltos en una lista aparte; el detalle de vueltos está en payment_methods_refund y external_payment_methods_refund.
with_tax_no_invoiced	Reservado para otros documentos.
total_quantities	No se expone la suma de cantidades.
printer_error	No se expone el mensaje de la imprenta.
total_refunded / total_refunded_usd	La nota de crédito en sí no tiene devoluciones.
total_pending_refund / total_pending_refund_usd	Igual que la anterior.
total_invoice_usd	El equivalente en dólares del total se llama total_refund_usd.
is_exempt	Dentro de los productos no existe esta marca.

Solo existen en notas de crédito:

Variable	Ejemplo de lo que inserta	Cuándo aplica / notas
document_total_taxes_retained	Bs. 116,00	Total de impuestos retenidos del documento.
total_refund_usd	USD 31,78	Total de la nota de crédito en su equivalente en dólares.
credit_amount_available_usd	USD 8,22	Saldo a favor disponible en su equivalente en dólares.

Además:

• document_total es el total de la nota de crédito.
• daysToPayNote siempre trae el mensaje de pago a contado.
• document_note_without_days_to_pay es igual a document_note.

---

Variables de la plantilla de Notas de Entrega

Una nota de entrega puede emitirse contra un cliente (venta aún sin facturar) o contra un proveedor (mercancía que recibes). La plantilla es la misma en ambos casos; lo que cambia es qué empresa ocupa el origen y cuál el destino, como se explica al final.

Datos del documento

Variable	Ejemplo de lo que inserta	Cuándo aplica / notas
document_number	NDE-00000045	Número de la nota de entrega con el prefijo y sufijo configurados en la tienda.
document_date	12/09/2026	Fecha de emisión de la nota.
document_note	Entregar en horario de oficina	Nota escrita al emitir. Queda vacía si no se escribió ninguna.
reason	Traslado de mercancía a sucursal	Motivo del movimiento, cuando se indicó.

Origen de la mercancía

Variable	Ejemplo de lo que inserta	Cuándo aplica / notas
src_company	Ferretería El Tornillo, C.A.	Razón social del origen.
src_vat_company	J-12345678-9	RIF del origen.
src_address	Calle 5, Galpón 3, Zona Industrial	Dirección física desde donde sale la mercancía. Si al emitir se indicó una dirección de origen, manda esa; si no, la dirección fiscal del origen.
src_store_name	Almacén Principal	Nombre del almacén de origen; si la nota se recibió de un proveedor, muestra el nombre del proveedor.

Destino de la mercancía

Variable	Ejemplo de lo que inserta	Cuándo aplica / notas
dst_company	Cliente Mayorista, C.A.	Razón social del destino.
dst_vat_company	J-98765432-1	RIF del destino.
dst_address	Av. Principal, Local 4, Valencia	Dirección física a donde llega la mercancía. Si al emitir se indicó una dirección de destino, manda esa; si no, la dirección del destino.
dst_store_name	Sucursal Valencia	Nombre del almacén de destino, cuando el destino es otro almacén propio. Si el destino es un cliente, repite el nombre del destino.

Productos

La lista se recorre con {#products} y {/products}:

Variable	Ejemplo de lo que inserta	Cuándo aplica / notas
id	1	Número de posición del renglón dentro de la nota.
name	TOR-100 Tornillo autorroscante - Medida: 5cm	SKU, nombre del producto y sus atributos, cuando tiene.
quantity	12	Cantidad de la línea, sin unidad de medida.

Condiciones que cambian los datos

• Nota emitida contra un cliente: el origen es tu empresa y el destino es el cliente. dst_company, dst_vat_company y dst_address traen los datos del cliente.
• Nota recibida de un proveedor: los datos se invierten. El origen pasa a ser el proveedor y el destino tu empresa, porque la mercancía viene del proveedor hacia ti.
• Traslado entre almacenes propios: como es el mismo contribuyente, origen y destino muestran los datos fiscales de tu empresa.
• Direcciones físicas: si al emitir la nota se escribió una dirección de origen o destino distinta a la fiscal, esa es la que se imprime. Esto permite que la nota refleje el punto real de salida y entrega de la mercancía.
• La plantilla de notas de entrega también se usa para los envíos nacionales, con las mismas variables.

---

Variables de Guías de Despacho

La guía de despacho que sale de una tienda hacia otra tienda o hacia un cliente puede usar una plantilla propia, configurada en Medios de Facturación. El traslado interno entre almacenes de la misma tienda no usa esta plantilla.

Variable	Ejemplo de lo que inserta	Cuándo aplica / notas
document_number	GD-00000045	Número de la guía con el prefijo y sufijo configurados en la tienda.
document_date	12/09/2026	Fecha de emisión de la guía.
reason	Traslado de mercancía a sucursal	Motivo del movimiento, cuando se indicó.
src_company	Ferretería El Tornillo, C.A.	Razón social de la empresa que despacha.
src_vat_company	J-12345678-9	RIF de la empresa que despacha.
src_address	Calle 5, Galpón 3, Zona Industrial	Dirección desde donde sale la mercancía, indicada al emitir la guía.
dst_company	Ferretería El Tornillo, C.A.	Razón social del destino.
dst_vat_company	J-12345678-9	RIF del destino.
dst_address	Av. Principal, Local 4, Valencia	Dirección a donde llega la mercancía, indicada al emitir la guía.
producto_type	Mercancía general	Tipo de mercancía transportada.
total_weight_or_volume	120 kg	Peso o volumen total del despacho.
driver_name	José Pérez	Nombre completo del conductor.
driver_dni	V-12345678	Tipo y número de identificación del conductor.
driver_license	5ta categoría	Tipo de licencia del conductor.
driver_contact	0414-1234567	Contacto del conductor.
driver_email	jose@ejemplo.com	Correo del conductor.
vehicle_type	Camión	Tipo de vehículo.
vehicle_number	123	Número del vehículo.
vehicle_lic_plate	AB123CD	Placa del vehículo.
vehicle_color	Blanco	Color del vehículo.
transporter_name	Transportes El Rápido, C.A.	Razón social de la empresa transportista, cuando se indicó.
transporter_vat	J-11111111-1	RIF de la empresa transportista.
transporter_address	Av. Norte, Galpón 7	Dirección fiscal de la empresa transportista.
transporter_contact	0212-5555555	Contacto de la empresa transportista.

Los renglones se recorren con {#products} y {/products}: cada fila trae id (posición del renglón), name (SKU, nombre del producto y atributos), quantity (cantidad), unit_price (precio unitario formateado) y total (precio unitario por la cantidad, formateado).

Los datos de transporte y las direcciones salen de lo que se cargó al emitir la guía; si no se cargaron, insertan vacío.

---

Ejemplos completos

Ejemplo 1: encabezado de una cotización

Texto que escribes en Word:

Cotización No. {document_number}
Fecha: {document_date}

Cliente: {customer_name}
RIF: {customer_dni}
Dirección: {customer_address}
Teléfono: {customer_phone}

Lo que se imprime al emitir la cotización:

Cotización No. COT-00000123
Fecha: 12/09/2026

Cliente: Ferretería El Tornillo, C.A.
RIF: J-12345678-9
Dirección: Av. Libertador, Caracas, 1010, Venezuela
Teléfono: 0414-1234567

Ejemplo 2: bloque de envío que solo aparece cuando existe

Texto que escribes en Word:

{#has_shipping_address}
Dirección de envío: {shipping_address}
Recibe: {shipping_full_name} - {shipping_dni} - {shipping_phone}
{/has_shipping_address}

Si el documento tiene dirección de envío, se imprime:

Dirección de envío: Calle 5, Galpón 3, Zona Industrial
Recibe: María Rodríguez - V-12345678 - 0424-7654321

Si no la tiene, no se imprime nada entre las dos etiquetas.

Ejemplo 3: tabla de productos

Fila de encabezado:

| Producto | Cantidad | Precio unitario | Total |

Fila que se repite:

| {#products}{name} | {quantity} | {unit_price} | {total}{/products} |

Lo que se imprime con dos productos:

| Producto                                      | Cantidad | Precio unitario | Total      |
| Tornillo autorroscante - SKU: TOR-100 (G)     | 2 UND    | Bs. 45,00       | Bs. 90,00  |
| Martillo de acero - SKU: MAR-200              | 1 UND    | Bs. 75,00       | Bs. 75,00  |

Si quieres que el SKU salga en negrita y con los saltos de línea del nombre ya armados, usa {@nameXml} en lugar de {name} en la celda del producto.

Ejemplo 4: totales con la tabla ya armada

Texto que escribes en Word:

{@xmlTotals}

Lo que se imprime:

Sub Total              Bs. 1.000,00     USD 27,40
Total en Impuestos     Bs. 160,00       USD 4,38
Total                  Bs. 1.160,00     USD 31,78

La tabla puede traer dos o tres columnas según el documento tenga o no equivalencia en otra moneda.

Ejemplo 5: nota y campos personalizados

Texto que escribes en Word:

{custom_document_data.vendedor}
{@document_noteXml}

Lo que se imprime:

Luis Pérez
Entregar antes del viernes - Tasa Utilizada -> USD: 36,5000

---

Ejemplo 6: factura personalizada de principio a fin

Una plantilla de factura se puede adaptar por completo: encabezado con los datos del cliente, datos propios de la empresa tomados de los campos personalizados, tabla de productos con columnas separadas, bloque de impuestos, totales, formas de pago y firmas.

Texto que escribes en Word (cada línea de la tabla va en su celda de Word):

Cliente: {customer_name}
R.I.F.: {customer_dni}
Dirección Fiscal: {customer_address}
Teléfono: {customer_phone}
{@customer_extra_fields_xml}

FACTURA NRO: {document_number}    LUGAR: Valencia    Fecha: {document_date}

Requisición: {#metadata}{#printer_custom_data}{requisicion}{/printer_custom_data}{/metadata}
Orden de Compra: {#metadata}{#printer_custom_data}{orden_de_compra}{/printer_custom_data}{/metadata}
Condiciones de Pago: {daysToPayNote}

| Código | Descripción | Precio Unitario | Cantidad | Total |
| {#products}{sku} | {product_name_without_sku} {product_categories} | {unit_price} | {quantity} | {total}{/products} |

| Impuesto | Base Imponible | Total por Impuesto |
| {#taxes}{name} | {taxable_amount} | {amount}{/taxes} |

Total en Letras: {document_total_in_letters}
{@xmlTotals}

Pago en Bolívares: {payment_methods}
Formas de Pago en Moneda Extranjera: {external_payment_methods}
Vuelto en Bolívares: {payment_methods_refund}
Vuelto en Moneda Extranjera: {external_payment_methods_refund}

{@document_noteXml_without_days_to_pay}

Nombre y Sello del Cliente          Firma Autorizada          Fecha de Recepción

Lo que se imprime al emitir la factura (datos de ejemplo):

Cliente: Comercial La Esperanza, C.A.
R.I.F.: J-40123456-7
Dirección Fiscal: Av. Industrial, Galpón 4, Valencia, Carabobo, Venezuela
Teléfono: 0241-1234567

FACTURA NRO: 001234    LUGAR: Valencia    Fecha: 12/09/2026

Requisición: REQ-88
Orden de Compra: OC-9012
Condiciones de Pago: Pago a Contado

| Código  | Descripción                                              | Precio Unitario | Cantidad | Total      |
| TOR-100 | Tornillo autorroscante 3x5 cm                            | Bs. 45,00       | 2 UND    | Bs. 90,00  |
| GUA-200 | Guantes de seguridad industrial - Categoría: Seguridad   | Bs. 75,00       | 1 PAR    | Bs. 75,00  |

| Impuesto      | Base Imponible | Total por Impuesto |
| IVA - 16% (G) | Bs. 165,00     | Bs. 26,40          |

Total en Letras: CIENTO NOVENTA Y UNO CON 40/100 CÉNTIMOS

| Sub Total | Bs. 165,00 |
| Total IVA | Bs. 26,40  |
| Total     | Bs. 191,40 |

Pago en Bolívares: Transferencia (Bs. 191,40)
Formas de Pago en Moneda Extranjera:  --
Vuelto en Bolívares:  --
Vuelto en Moneda Extranjera:  --

Entregar antes del viernes | Tasa Utilizada -> USD: 36,5000

Nombre y Sello del Cliente          Firma Autorizada          Fecha de Recepción

Qué se usó en cada parte:

• Datos propios de la empresa: Requisición y Orden de Compra son campos personalizados, leídos con el patrón agrupado o con {custom_document_data.requisicion}.
• Condiciones de pago: {daysToPayNote} imprime el mensaje de contado o de días máximos configurado para el documento.
• Productos: en lugar de usar {name} en una sola celda, se separaron {sku}, {product_name_without_sku}, {product_categories}, {unit_price}, {quantity} y {total} en columnas.
• Impuestos: {#taxes} repite la fila con el nombre, la base y el monto de cada impuesto.
• Totales: {@xmlTotals} arma la tabla de subtotal, impuestos y total a pagar; {document_total_in_letters} imprime el total en letras.
• Pagos y vueltos: cada variable agrupa su lista por separado, unida con |.
• Notas: {@document_noteXml_without_days_to_pay} imprime las observaciones y la tasa de cambio sin repetir la condición de pago, que ya salió arriba.
• Firmas: el texto final es fijo y no necesita variables.

---

Errores frecuentes

• "El archivo no es un documento de Word válido": guardaste el archivo en formato .doc, lo renombraste desde otro tipo de archivo o está dañado. Ábrelo en Word y usa Guardar como → Documento de Word (.docx).
• "Etiquetas mal escritas": alguna variable quedó con una llave sin cerrar ({customer_name sin el cierre), o una lista quedó abierta sin su cierre. Recuerda que cada {#products} necesita su {/products}.
• "Variables que no existen": el mensaje te dice cuáles. Los motivos más comunes son nombres mal escritos o tildes dentro del nombre. Copia el nombre exacto desde este manual. Si la plantilla usa campos personalizados ({custom_document_data.nombre_del_campo} o {#metadata}{#printer_custom_data}{nombre_del_campo}), el campo tiene que existir en la configuración de la tienda al momento de subir la plantilla.
• Una variable no imprime nada: revisa si aplica al caso. Por ejemplo, {shipping_address} solo tiene contenido si el documento se emitió con dirección de envío; {daysToPayNote} va vacío en cotizaciones; y los totales en dólares insertan -- cuando el documento no tiene equivalente en otra moneda.
• Aparece texto con signos de menor y mayor: usaste una variable de las que terminan en Xml sin la arroba. Deben escribirse como {@document_noteXml}, {@xmlTotals}, {@nameXml}.
• La plantilla se ve bien en Word pero imprime distinto: revisa que la variable no se haya partido en dos por un cambio de formato a mitad de la palabra. Escribe cada variable de una sola vez y aplica el formato a la etiqueta completa.
• Los estilos de fuente no se aplican: los estilos configurados en la pantalla de la plantilla se aplican a las descripciones de producto, a las notas y a las tablas XML ({@nameXml}, {@document_noteXml}, {@xmlTotals}). El texto que escribes directamente en Word conserva el formato que le diste en el archivo.