Saltar al contenido principal

Forma Libre

Índice​

Introducción​

Este documento explica cómo funciona el método de Forma Libre en CACHICAMO y cómo se utilizan las variables en las plantillas preestablecidas.

La Forma Libre es un método de emisión de documentos fiscales en Venezuela. Estos se presentan en forma de talonarios y son formatos creados por una imprenta autorización del ente regulador.

CACHICAMO proporciona plantillas preestablecidas que han sido diseñadas conforme a los formatos autorizados por el ente regulador. Las variables serán reemplazadas automáticamente por los valores correspondientes cuando se genere el documento, el cual posteriormente debe ser enviado a una imprenta autorizada para su impresión final.

En resumen, las variables son campos especiales dentro de la plantilla que serán reemplazados automáticamente por los valores reales cuando se utilice la plantilla. Este documento explica cómo utilizar esas variables en la plantilla para que puedas personalizar tu documento según tus necesidades.

Cómo Funciona la Plantilla​

  1. Plantillas Preestablecidas: CACHICAMO proporciona plantillas en formato DOCX que han sido diseñadas y aprobadas conforme a los formatos autorizados por el ente regulador. Estas plantillas no pueden ser modificadas por el cliente.

  2. Selección de Plantilla: En el sistema CACHICAMO, puedes seleccionar la plantilla de forma libre apropiada para el tipo de documento que deseas generar (factura, nota de crédito, etc.).

  3. Generación del Documento: El sistema toma la plantilla seleccionada y reemplaza automáticamente las variables con los datos reales de la transacción.

  4. Descarga del Documento: Una vez generado, puedes descargar el documento completado.

  5. Impresión por Imprenta Autorizada: Los documentos generados deben ser impresos inmediatamente en un documento forma libre emitido por una imprenta autorizada por el ente regulador, cumpliendo con la providencia SNAT/2011/0071.

Cómo Usar las Variables​

Las variables son elementos especiales de texto dentro del archivo DOCX que se reemplazarán automáticamente por los valores reales cuando se genere un documento. Las variables están delimitadas por llaves {} y, en algunos casos, pueden estar dentro de bucles que permiten generar una lista de elementos (como productos o pagos).

¿Cómo funciona el reemplazo de las variables?​

Cuando se genera un documento, el sistema toma el archivo DOCX y reemplaza cada variable por el valor correspondiente. Por ejemplo, la variable {customer_name} será reemplazada por el nombre del cliente, {document_number} será reemplazada por el número del documento, etc.

Ejemplo:
Si el nombre del cliente es "Juan Pérez", el sistema reemplazará {customer_name} por "Juan Pérez".

Lista de Variables Disponibles​

A continuación se muestra una lista de las variables disponibles que puedes usar en la plantilla:

Información del Cliente​

  • {customer_name}: Nombre de la empresa del cliente (o nombre personal si no tiene empresa).
  • {customer_dni}: R.I.F./C.I./Identificación Fiscal del cliente.
  • {customer_address}: Dirección fiscal del cliente.
  • {customer_phone}: Teléfono del cliente.
  • {customer_email}: Correo electrónico del cliente.

Información de Envío (Dirección de Entrega)​

Estas variables se utilizan cuando el cliente tiene una dirección de envío diferente a la dirección fiscal:

  • {has_shipping_address}: Indicador booleano (verdadero/falso) si existe una dirección de envío.
  • {shipping_address}: Dirección completa de envío del cliente.
  • {shipping_address_with_extra_fields}: Dirección de envío junto con campos adicionales del cliente.
  • {shipping_full_name}: Nombre completo de la persona receptora del envío.
  • {shipping_dni}: Identificación de la persona receptora del envío.
  • {shipping_phone}: Teléfono del lugar de envío.

Información del Documento​

  • {document_date}: Fecha del documento (formato DD-MM-YYYY).
  • {document_number}: Número de la factura o documento actual.
  • {document_type}: Tipo de documento (Factura, Nota de Crédito, Nota de Débito, etc.) - Solo para documentos de proveedor.
  • {document_control_number}: Número de control del documento (para impresoras fiscales o documentos personalizados) - Solo para documentos de proveedor.
  • {invoice_number}: Número de la factura afectada (Para notas de crédito y notas de débito).
  • {invoice_date}: Fecha de la factura afectada (Para notas de crédito y notas de débito).

Detalles de los Productos​

  • {#products}: Marca el inicio de un grupo de productos (se usa para crear listas de productos).
    • {name}: Nombre del producto con detalles adicionales (SKU, atributos, volumen, impuestos aplicados, etc.).
    • {unit_price}: Precio unitario del producto (puede mostrar dos líneas si hay conversión de moneda).
    • {quantity}: Cantidad del producto con su unidad de medida.
    • {total}: Total por producto (cantidad × precio unitario).
    • {total_raw}: Valor numérico bruto del total del producto (sin formato).
    • {unit_price_raw}: Valor numérico bruto del precio unitario (sin formato).
  • {/}: Marca el final del grupo.

Ejemplo: {#products}{name} {unit_price} {quantity} {total}{/}: Esto indica que la información del producto se repetirá para cada producto que se agregue a la factura.

Impuestos​

  • {#taxes}: Marca el inicio de un grupo de impuestos.
    • {name}: Nombre del impuesto con porcentaje (ej: "IVA - 16%").
    • {taxable_amount}: Base imponible del impuesto (monto sobre el cual se calcula el impuesto).
    • {amount}: Monto del impuesto calculado.
    • {amount_raw}: Valor numérico bruto del monto del impuesto (sin formato).
    • {taxable_amount_raw}: Valor numérico bruto de la base imponible (sin formato).
  • {/}: Marca el final del grupo.

Ejemplo: {#taxes}{name} {taxable_amount} {amount}{/}: Similar a los productos, esto repetirá la información de cada impuesto.

Forma de Pago​

  • {payment_methods}: Métodos de pago utilizados (en formato legible separado por "|").
  • {external_payment_methods}: Métodos de pago en moneda extranjera (con tasas de cambio).
  • {payment_methods_with_refund}: Métodos de pago incluyendo vueltos/cambio si aplica.
  • {external_payment_methods_with_refund}: Métodos de pago externos con vueltos si aplica.
  • {payment_methods_refund}: Solo los vueltos/cambios otorgados.
  • {external_payment_methods_refund}: Solo los vueltos/cambios en moneda extranjera.
  • {#payments}: Marca el inicio de un grupo de pagos (útil cuando hay más de una forma de pago).
    • {name}: Nombre del método de pago.
    • {amount}: Monto pagado con ese método (formateado con moneda).
    • {amount_raw}: Valor numérico bruto del monto pagado (sin formato).
  • {/}: Marca el final del grupo de pagos.
  • {#payments_refund}: Marca el inicio de un grupo de reembolsos/vueltos.
    • {name}: Nombre del método de reembolso.
    • {amount}: Monto del reembolso (formateado con moneda).
    • {amount_raw}: Valor numérico bruto del reembolso (sin formato).
  • {/}: Marca el final del grupo de reembolsos.

Ejemplo: {#payments}{name}: {amount}{/}: Se repite para cada método de pago.

Notas del Documento​

  • {document_note}: Nota general del documento (sin incluir información de días de pago).
  • {document_note_with_extra_fields}: Nota del documento con campos extra del cliente.
  • {document_note_without_days_to_pay}: Nota del documento sin el mensaje de días para pagar.
  • {daysToPayNote}: Mensaje sobre días de pago o pago de contado.

Notas especiales:

  • {document_noteXml}: Versión de la nota con formato para estilos especiales (negritas, cursivas, etc.).
  • {document_noteXml_with_extra_fields}: Nota con formato y campos extra del cliente.
  • {document_noteXml_without_days_to_pay}: Nota con formato sin el mensaje de días de pago.

Totales​

  • {document_subtotal}: Subtotal de la factura antes de impuestos.
  • {document_total_taxes}: Total de los impuestos aplicados.
  • {document_total_taxes_retained}: Total de los impuestos retenidos.
  • {document_total}: Total de la factura (incluyendo impuestos).
  • {document_total_in_letters}: Total de la factura escrito en letras (ej: "Mil Doscientos Treinta y Cuatro Bolívares").

Información de Estado de Pago​

  • {is_payed}: Indicador booleano (verdadero/falso) si la factura está pagada completamente.
  • {total_payed}: Monto total pagado de la factura.
  • {total_to_pay}: Monto pendiente por pagar.
  • {total_pending_refund}: Monto pendiente a reembolsar al cliente.
  • {total_refunded}: Monto total reembolsado.
  • {total_taxes_retained}: Total de impuestos retenidos.
  • {printer_error}: Mensaje de error si hubo un problema con la impresora fiscal.

Totales en USD (Moneda Extranjera)​

Estas variables se utilizan cuando hay productos o pagos en moneda extranjera:

  • {total_payed_usd}: Monto pagado en USD.
  • {total_to_pay_usd}: Monto pendiente en USD.
  • {total_pending_refund_usd}: Monto pendiente a reembolsar en USD.
  • {total_refunded_usd}: Monto reembolsado en USD.
  • {total_invoice_usd}: Total de la factura en USD.
  • {total_products_usd}: Subtotal de productos en USD.
  • {total_taxes_usd}: Total de impuestos en USD.
  • {total_taxes_retained_usd}: Total de impuestos retenidos en USD.

Tabla Dinámica de Totales​

  • {xmlTotals}: Tabla formateada dinámicamente con subtotal, impuestos y total. Se adapta automáticamente para mostrar una, dos o tres columnas según si hay tasas de cambio de moneda.

Casos de Uso Comunes​

Factura Simple con Pago en Efectivo​

Factura: {document_number}
Fecha: {document_date}

Cliente: {customer_name}
RIF: {customer_dni}
Dirección: {customer_address}

{#products}
{name} - Qty: {quantity} x {unit_price} = {total}
{/}

Subtotal: {document_subtotal}
Impuestos: {document_total_taxes}
Total: {document_total}

Forma de Pago: {payment_methods}

Factura con Dirección de Envío Diferente​

{#if has_shipping_address}
ENVIAR A:
{shipping_full_name}
{shipping_address}
Teléfono: {shipping_phone}
{/if}

Factura con Múltiples Monedas​

Cuando tienes productos o pagos en diferentes monedas, el sistema incluye automáticamente:

  • Los precios en ambas monedas
  • Las tasas de cambio utilizadas
  • Los totales en USD cuando aplica

Ejemplos de Plantillas Oficiales​

Puedes descargar las plantillas oficiales de ejemplo para ver cómo se estructuran y dónde se colocan las variables:

Ejemplos en tamaño media carta:

Ejemplos en tamaño carta:

Notas Importantes Sobre las Variables​

Variables Booleanas​

Algunas variables como {is_payed} y {has_shipping_address} son booleanas (verdadero/falso). Puedes usarlas en condicionales en tu plantilla DOCX para mostrar u ocultar contenido según sea necesario.

Formatos XML​

Las variables con sufijo Xml (ej: {document_noteXml}) permiten usar formato especial dentro de las plantillas DOCX para aplicar estilos como negritas, cursivas, etc. usando sintaxis de Markdown simple:

  • *texto* para negritas
  • /texto/ para cursivas
  • `código` para monoespaciado