Saltar al contenido principal

Facturas de Clientes

Transacciones se agrupan para formar una factura, que se envía al cliente para su pago.

Las facturas tienen una fecha de inicio y una fecha de finalización, que es el período que cubre la factura, y una fecha de vencimiento, que es la fecha en que la factura debe ser pagada.

Generar una Factura Proforma

Las facturas pueden ser generadas automáticamente por el sistema, por ejemplo, cuando se factura un servicio, se crea una factura por el costo al por menor, o pueden ser creadas manualmente, por ejemplo, si un cliente solicita una copia de una factura, o si un cliente es facturado por un cargo único.

Las facturas de los clientes están completamente plantilladas con Mailjet y pueden ser personalizadas para incluir el logotipo de la empresa, la dirección y los detalles de pago, y pueden ser enviadas al cliente por correo electrónico, o descargadas como un PDF.

Registro de Actividad

Personalizando Plantillas de Facturas​

OmniCRM utiliza plantillas HTML con Jinja2 para generar facturas. Puedes personalizar completamente el diseño de la factura, la marca, los colores y el diseño.

Ubicación de la Plantilla de Factura​

Las plantillas de factura se almacenan en OmniCRM-API/invoice_templates/

Plantillas Predeterminadas:

  • norfone_invoice_template.html - Plantilla de factura de muestra
  • cifi_invoice_template.html - Ejemplo de plantilla alternativa

Configuración:

La plantilla de factura activa se especifica en OmniCRM-API/crm_config.yaml:

invoice:
  template_filename: 'norfone_invoice_template.html'

Variables de Plantilla Disponibles​

Las plantillas de factura tienen acceso a las siguientes variables de Jinja2:

Información de la Factura:

  • {{ invoice_number }} - ID único de la factura (por ejemplo, INV-2025-001234)
  • {{ date }} - Fecha de emisión de la factura (formato ISO: 2025-01-10T12:00:00)
  • {{ due_date }} - Fecha de vencimiento del pago (por ejemplo, 2025-02-10)
  • {{ start_date }} - Fecha de inicio del período de facturación
  • {{ end_date }} - Fecha de finalización del período de facturación
  • {{ total_amount }} - Monto total de la factura antes de impuestos (numérico)
  • {{ total_tax }} - Monto total de impuestos calculado a partir de todas las transacciones (numérico)

Información del Cliente:

  • {{ client.name }} - Nombre completo del cliente o nombre de la empresa
  • {{ client.address.address_line_1 }} - Línea de dirección 1
  • {{ client.address.address_line_2 }} - Línea de dirección 2
  • {{ client.address.city }} - Ciudad
  • {{ client.address.state }} - Estado/provincia
  • {{ client.address.zip_code }} - Código postal
  • {{ client.address.country }} - País

Artículos de Línea de Transacción:

Recorre las transacciones usando:

{% for sub_transaction in transactions %}
    <tr>
        <td>{{ sub_transaction.transaction_id }}</td>
        <td>{{ sub_transaction.created.split("T")[0] }}</td>
        <td>{{ sub_transaction.title }}</td>
        <td>{{ sub_transaction.description }}</td>
        <td>${{ "%.2f"|format(sub_transaction.retail_cost) }}</td>
    </tr>
{% endfor %}

Campos de Transacción:

  • sub_transaction.transaction_id - ID de la transacción
  • sub_transaction.created - Fecha/hora de la transacción
  • sub_transaction.title - Título de la transacción
  • sub_transaction.description - Descripción detallada
  • sub_transaction.retail_cost - Monto del artículo
  • sub_transaction.tax_percentage - Porcentaje de impuesto aplicado (por ejemplo, 10 para 10%)
  • sub_transaction.tax_amount - Monto de impuesto calculado en dólares

Mostrando Impuestos en Plantillas:

<td>
    {% if sub_transaction.tax_amount and sub_transaction.tax_amount > 0 %}
        ${{ "%.2f"|format(sub_transaction.tax_amount) }} ({{ sub_transaction.tax_percentage }}%)
    {% else %}
        -
    {% endif %}
</td>

Creando una Plantilla de Factura Personalizada​

Paso 1: Copiar Plantilla Existente

cd OmniCRM-API/invoice_templates/
cp norfone_invoice_template.html your_company_invoice_template.html

Paso 2: Personalizar HTML/CSS

Edita your_company_invoice_template.html para que coincida con tu marca:

Áreas Clave de Personalización:

  1. Logotipo y Marca de la Empresa

    <!-- Reemplaza con la URL de tu logotipo -->
    <img src="https://yourcompany.com/logo.png" alt="Tu Empresa" width="200">

    <!-- Actualiza el nombre de la empresa -->
    <h1>Nombre de Tu Empresa</h1>

  2. Esquema de Colores

    <style>
        /* Color de marca principal */
        .navbar {
            background: linear-gradient(to bottom right, #your-color-1, #your-color-2);
        }

        /* Encabezados de tabla */
        .table thead th {
            background-color: #your-brand-color !important;
            color: white !important;
        }

        /* Botones y enlaces */
        .btn-primary {
            background-color: #your-brand-color;
        }
    </style>

  3. Información de la Empresa en el Pie de Página

    <footer>
        <p>Nombre de Tu Empresa</p>
        <p>Calle 123, Ciudad, País</p>
        <p>Teléfono: +1-555-123-4567 | Correo: billing@yourcompany.com</p>
        <p>ABN/ID Fiscal: 12345678900</p>
    </footer>

  4. Instrucciones de Pago

    <div class="payment-info">
        <h3>Métodos de Pago</h3>
        <p><strong>En Línea:</strong> Paga en https://yourcompany.com/pay</p>
        <p><strong>Transferencia Bancaria:</strong></p>
        <ul>
            <li>Nombre de la Cuenta: Your Company Ltd</li>
            <li>BSB: 123-456</li>
            <li>Número de Cuenta: 987654321</li>
            <li>Referencia: {{ invoice_number }}</li>
        </ul>
    </div>

  5. Términos y Condiciones

    <div class="terms">
        <h4>Términos de Pago</h4>
        <p>Pago debido dentro de los 30 días a partir de la fecha de la factura.</p>
        <p>Recargos por pago tardío: 2% por mes sobre saldos vencidos.</p>
        <p>Para consultas de facturación: billing@yourcompany.com</p>
    </div>

Paso 3: Actualizar Configuración

Edita OmniCRM-API/crm_config.yaml:

invoice:
  template_filename: 'your_company_invoice_template.html'

Paso 4: Reiniciar API

cd OmniCRM-API
sudo systemctl restart omnicrm-api

Paso 5: Probar la Generación de Facturas

  1. Navega a un cliente con transacciones
  2. Genera una factura de prueba
  3. Descarga el PDF para verificar el formato
  4. Envía la factura a ti mismo para probar la entrega del correo electrónico

Personalización Avanzada​

Contenido Condicional:

Usa condicionales de Jinja2 para mostrar/ocultar contenido:

{% if total_amount > 1000 %}
    <div class="high-value-notice">
        <p><strong>Nota:</strong> Saldo alto - Plan de pago disponible a solicitud.</p>
    </div>
{% endif %}

{% if client.address.country == "Australia" %}
    <p>GST Incluido: ${{ "%.2f"|format(total_amount * 0.10) }}</p>
{% endif %}

Soporte Multilingüe:

Crea plantillas específicas para cada idioma:

invoice_template_en.html
invoice_template_es.html
invoice_template_fr.html

Configura según la preferencia de idioma del cliente.

Cálculos Personalizados:

<!-- Mostrar subtotal y desglose de impuestos -->
<tr>
    <td colspan="4" class="text-right"><strong>Subtotal:</strong></td>
    <td>${{ "%.2f"|format(total_amount) }}</td>
</tr>
<tr>
    <td colspan="4" class="text-right"><strong>Impuesto:</strong></td>
    <td>${{ "%.2f"|format(total_tax) }}</td>
</tr>
<tr>
    <td colspan="4" class="text-right"><strong>Total:</strong></td>
    <td>${{ "%.2f"|format(total_amount + total_tax) }}</td>
</tr>

Nota: La variable total_tax se calcula automáticamente sumando el tax_amount de todas las transacciones en la factura. El impuesto de cada transacción se calcula en función de su campo tax_percentage, que por defecto es el tax_percentage del producto o 0% si no se especifica.

Código QR para Pago:

Genera un código QR para el pago móvil:

<div class="qr-payment">
    <img src="https://api.qrserver.com/v1/create-qr-code/?size=150x150&data={{ payment_url }}"
         alt="Escanea para Pagar">
    <p>Escanea con tu teléfono para pagar al instante</p>
</div>

Mejores Prácticas de Estilo para PDF​

OmniCRM utiliza WeasyPrint para convertir HTML a PDF. Sigue estas pautas:

CSS Soportado:

  • La mayoría de las propiedades CSS 2.1
  • CSS3 limitado (flexbox, algunas transformaciones)
  • Fuentes web a través de @font-face

No Soportado:

  • JavaScript
  • CSS Grid (usa tablas en su lugar)
  • Animaciones complejas
  • Algunas propiedades CSS modernas

Tamaño de Página y Márgenes:

@page {
    size: A4;
    margin: 1cm;
}

body {
    font-family: Arial, sans-serif;
    font-size: 10pt;
}

Estilo Específico para Impresión:

@media print {
    .no-print {
        display: none;
    }

    .page-break {
        page-break-after: always;
    }
}

Diseño de Tabla:

.table {
    table-layout: fixed;
    width: 100%;
}

.table th, .table td {
    word-wrap: break-word;
    padding: 4px;
}

Incorporación de Fuentes:

Para fuentes personalizadas, usa fuentes seguras para la web o incorpora:

@font-face {
    font-family: 'YourFont';
    src: url('https://yourcompany.com/fonts/yourfont.woff2') format('woff2');
}

body {
    font-family: 'YourFont', Arial, sans-serif;
}

Pruebas de Plantillas de Facturas​

Lista de Verificación de Pruebas:

  1. Inspección Visual:
    • El logotipo se muestra correctamente
    • Los colores coinciden con las pautas de la marca
    • El texto es legible (no demasiado pequeño)
    • Las tablas están alineadas correctamente
    • Todas las secciones están presentes
  2. Precisión de Datos:
    • Los detalles del cliente son correctos
    • Los montos de las transacciones suman correctamente
    • Las fechas están formateadas correctamente
    • Todas las variables se sustituyen correctamente
  3. Calidad del PDF:
    • El tamaño del archivo es razonable (<5MB)
    • Las imágenes son nítidas y claras
    • No hay texto cortado o desbordado
    • Los saltos de página están en lugares apropiados
  4. Facturas de Múltiples Páginas:
    • Los encabezados se repiten en cada página
    • Los números de página se muestran
    • Las listas de transacciones largas se paginan correctamente
  5. Entrega de Correo Electrónico:
    • El PDF se adjunta al correo electrónico
    • El tamaño del archivo está por debajo del límite de Mailjet (15MB)
    • Se renderiza en Gmail, Outlook, Apple Mail

Comando de Prueba (Generación Manual):

Puedes probar la generación de facturas a través de la API:

curl -X GET "http://localhost:5000/crm/invoice/{invoice_id}/pdf" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     --output test_invoice.pdf

Problemas Comunes de Plantillas​

Variables no sustituidas:

  • Causa: Error tipográfico en el nombre de la variable o datos faltantes
  • Solución: Verifica la ortografía exactamente (sensible a mayúsculas y minúsculas), verifica que los datos existan en la base de datos

Estilo del PDF roto:

  • Causa: Propiedad CSS no soportada
  • Solución: Usa propiedades CSS 2.1, prueba con CSS compatible con WeasyPrint

Imágenes no se muestran:

  • Causa: URLs relativas o recursos externos bloqueados
  • Solución: Usa URLs absolutas HTTPS, asegúrate de que las imágenes sean accesibles públicamente

Tablas desbordando la página:

  • Causa: Anchos de columna fijos demasiado anchos
  • Solución: Usa anchos porcentuales, table-layout: fixed

Fuentes no se renderizan:

  • Causa: Fuente no incorporada o no disponible
  • Solución: Usa fuentes seguras para la web (Arial, Times New Roman, etc.) o incorpora correctamente fuentes personalizadas

Fallo en la generación de PDF:

  • Causa: Errores de sintaxis HTML o fallo de WeasyPrint
  • Solución: Valida HTML, verifica los registros de WeasyPrint, simplifica diseños complejos

Caché de PDF de Factura​

Para mejorar el rendimiento y reducir la generación redundante de PDF, OmniCRM incluye un sistema de caché de PDF de factura. Cuando se genera un PDF de factura por primera vez, se almacena en la base de datos para solicitudes posteriores.

Cómo Funciona la Caché de PDF:

  1. Primera Solicitud - Cuando se solicita un PDF de factura (descarga o correo electrónico), el sistema:
    • Genera el PDF a partir de la plantilla de factura
    • Codifica el PDF como Base64
    • Calcula un hash SHA256 del contenido del PDF
    • Almacena en la tabla Invoice_PDF_Cache con:
      • Referencia de ID de factura
      • Datos del PDF (codificados en Base64)
      • Nombre del archivo
      • Hash de contenido (para verificación de integridad)
      • Marca de tiempo de creación
  2. Solicitudes Posteriores - Cuando se solicita la misma factura nuevamente:
    • El sistema verifica si hay un PDF en caché por invoice_id
    • Si la caché existe y es válida, devuelve el PDF en caché inmediatamente
    • Actualiza la marca de tiempo last_accessed para rastrear el uso de la caché
  3. Invalidación de Caché - Los PDFs en caché se invalidan cuando:
    • La factura se modifica (transacciones añadidas/eliminadas, detalles cambiados)
    • La plantilla de factura se actualiza
    • Se activa la limpieza manual de caché

Beneficios:

  • Rendimiento - Entrega instantánea de PDF para solicitudes repetidas (sin retraso de regeneración)
  • Consistencia - El mismo PDF para todas las descargas de una factura (a menos que la factura se modifique)
  • Carga del Servidor - Reduce el uso de CPU por la generación de PDF
  • Experiencia del Usuario - Un indicador de carga aparece durante la generación inicial, las solicitudes posteriores son instantáneas

Gestión de Caché:

La Caché de PDF de Factura es gestionada automáticamente por el sistema. Las entradas de caché antiguas o no utilizadas pueden ser eliminadas periódicamente según:

  • Edad (por ejemplo, eliminar entradas de caché de más de 90 días)
  • Patrones de acceso (eliminar entradas no accedidas en 30 días)
  • Límites de almacenamiento (implementar límites de tamaño de caché si es necesario)

Comportamiento de la API:

Al descargar una factura a través de la API o la interfaz de usuario:

  • Primera solicitud: Muestra un indicador de carga mientras se genera el PDF, luego se almacena en caché
  • Solicitudes posteriores: Descarga inmediata desde la caché
  • El acierto/fallo de caché es transparente para el usuario

Importante: Cuando actualices tu plantilla de factura, limpia la caché para asegurarte de que las nuevas facturas utilicen el diseño actualizado:

-- Limpiar todos los PDFs de factura en caché (ejecutar en MySQL)
DELETE FROM Invoice_PDF_Cache;

O actualiza crm_config.yaml para invalidar automáticamente la caché al cambiar la plantilla.

Accediendo a Facturas​

Las facturas se pueden ver a nivel del sistema o por cliente:

Vista por Cliente:

  1. Navega a Clientes → [Seleccionar Cliente]
  2. Haz clic en la pestaña Facturación
  3. Ver lista de facturas en la tercera tarjeta

Vista a Nivel del Sistema:

  1. Navega a Facturación → Facturas (desde el menú principal)
  2. Ver todas las facturas de todos los clientes

Widgets de Estadísticas de Facturas​

En la parte superior de la página de facturas, cuatro tarjetas de estadísticas muestran resúmenes financieros.

Estadísticas de Facturas y Lista{.align-center width="800px"}

Descripciones de Widgets:

  • Total de Facturas - Suma de todos los costos de facturas al por menor (todo el tiempo) y cuenta de facturas enviadas
  • Facturas No Pagadas - Suma de facturas aún no pagadas y cuenta de facturas no pagadas
  • Facturas Este Mes - Suma de facturas creadas este mes calendario con cuenta
  • Facturas del Mes Pasado - Suma de facturas creadas el mes calendario pasado con cuenta

Formato de Valores:

  • Valores superiores a 1,000: Mostrar como sufijo "k" (por ejemplo, $1.5k)
  • Valores superiores a 1,000,000: Mostrar como sufijo "M" (por ejemplo, $2.3M)
  • Valores superiores a 1,000,000,000: Mostrar como sufijo "B" (por ejemplo, $1.1B)

Indicadores de Tendencia:

  • Widgets para "Este Mes" y "Mes Pasado" muestran cambio porcentual
  • Flecha verde hacia arriba: Aumento respecto al período anterior
  • Flecha roja hacia abajo: Disminución respecto al período anterior
  • Flecha gris hacia la derecha: Sin cambio

Lista de Facturas​

La tabla de facturas muestra todas las facturas con las siguientes columnas:

Lista Global de Facturas

Descripciones de Columnas:

  • ID - ID único de la factura
  • Título - Título/descripción de la factura
  • Período - Período de facturación (fecha de inicio - fecha de finalización) o "N/A" para facturas únicas
  • Fecha de Vencimiento - Fecha de vencimiento del pago
  • Creado - Fecha de creación de la factura
  • Monto - Monto total de la factura (costo al por menor)
  • Estado - Pagado, No Pagado o Reembolsado
  • Acciones - Acciones disponibles (varía según el estado)

Íconos de Acción:

  • ⬇ (Descargar) - Descargar PDF de la factura
  • 🗑️ (Eliminar) - Anular factura (solo si no está pagada)
  • 💰 (Pagar) - Pagar factura en línea (solo si no está pagada)
  • ✉️ (Correo) - Enviar correo electrónico de la factura al cliente
  • 💸 (Reembolsar) - Reembolsar pago de Stripe (solo para facturas de Stripe pagadas)

Generando una Factura​

Haz clic en "+ Generar Factura Proforma" para crear una nueva factura.

Modal de Generación de Factura con Vista Previa de Transacción{.align-center width="800px"}

Descripciones de Campos:

  • Buscar Clientes - Seleccionar cliente (solo se muestra en vista a nivel de sistema, pre-llenado en vista de cliente)
  • Título - Título/nombre de la factura (opcional, por defecto es "Factura por [Período]")
  • Fecha de Inicio - Inicio del período de facturación (por defecto hace 14 días)
  • Fecha de Finalización - Fin del período de facturación (por defecto hoy)
  • Fecha de Vencimiento - Fecha límite de pago (por defecto hoy)
  • Vista Previa de Transacción - Muestra todas las transacciones no facturadas en el rango de fechas con la capacidad de incluir/excluir transacciones específicas

Selección de Transacciones:

  • ✓ (Más Verde) - Haz clic para excluir una transacción de la factura
  • × (X Roja) - Haz clic para incluir una transacción previamente excluida
  • Seleccionar Todo - Incluir todas las transacciones mostradas
  • Limpiar Todo - Excluir todas las transacciones
  • Las transacciones excluidas aparecen atenuadas con texto tachado
  • Los totales se actualizan en tiempo real a medida que seleccionas/deseleccionas transacciones

Qué Ocurre:

  1. El sistema encuentra todas las transacciones no facturadas para el cliente dentro del rango de fechas
  2. Muestra la vista previa de transacciones con la capacidad de incluir/excluir transacciones individuales
  3. Muestra el cálculo en tiempo real de subtotal, impuesto y total basado en las transacciones seleccionadas
  4. Solo las transacciones seleccionadas (incluidas) se añaden a la factura
  5. Genera el PDF de la factura y lo almacena en caché
  6. Marca las transacciones seleccionadas como facturadas (campo invoice_id poblado)
  7. Las transacciones excluidas permanecen no facturadas y disponibles para futuras facturas
  8. La factura aparece en la lista con el estado "No Pagada"

Ejemplos de Casos de Uso:

Facturación Mensual: Establece la fecha de inicio al primer día del mes, la fecha de finalización al último día del mes, la vista previa muestra todas las transacciones no facturadas de ese período. Selecciona todo o excluye manualmente transacciones específicas.

Factura Específica de Servicio: Usa el mismo rango de fechas, luego excluye manualmente transacciones no deseadas (por ejemplo, excluye transacciones no móviles para crear una factura solo móvil).

Factura Única: Establece tanto la fecha de inicio como la de finalización al mismo día, la vista previa muestra solo las transacciones de esa fecha. Excluye cualquier cargo que no sea relevante para esta factura específica.

Visualizando Detalles de la Factura​

Haz clic en cualquier fila de factura en la tabla para ver los detalles completos de la factura, incluyendo todas las transacciones, totales y acciones disponibles.

Vista de Detalles de la Factura{.align-center width="800px"}

Modal de Detalles de la Factura:

  • Información de la Factura - Muestra ID de factura, título, fechas, estado de pago y estado de anulación
  • Lista de Transacciones - Muestra todas las transacciones incluidas en la factura con:
    • Fecha de transacción
    • Título y descripción
    • Costo al por menor
    • Monto y porcentaje de impuesto (formateado como $10.00 (10%))
    • Las transacciones exentas de impuestos muestran "-" en la columna de Impuesto
  • Resumen de Totales - Cálculo en tiempo real que muestra:
    • Conteo de transacciones
    • Subtotal (suma de todos los costos al por menor)
    • Impuesto (suma de todos los montos de impuestos)
    • Total de la Factura (subtotal + impuesto)
  • Botones de Acción - Las mismas acciones disponibles que en la tabla:
    • Descargar PDF - Descargar PDF de la factura (siempre disponible)
    • Enviar Correo - Enviar factura al cliente (facturas no anuladas)
    • Pagar Factura - Procesar pago (solo facturas no pagadas y no anuladas)
    • Reembolsar - Reembolsar pago de Stripe (solo facturas de Stripe pagadas)
    • Eliminar - Anular factura (solo facturas no pagadas y no anuladas)

Descargando PDFs de Facturas​

Haz clic en el ícono de descarga (⬇) en la tabla o en el botón "Descargar PDF" en el modal de detalles de la factura para descargar una factura como PDF.

Proceso de Descarga:

  1. Haz clic en el ícono de descarga junto a la factura
  2. El spinner de carga aparece durante la generación (solo la primera vez)
  3. El navegador solicita guardar el archivo: Invoice_01234.pdf
  4. El PDF se abre o se guarda en la carpeta de Descargas

Comportamiento de Caché de PDF:

  • Primera Descarga - PDF generado a partir de la plantilla, almacenado en caché en la base de datos (puede tardar 2-3 segundos)
  • Descargas Posteriores - Descarga instantánea desde la caché
  • Invalidación de Caché - Caché limpiada si la factura se modifica o la plantilla se actualiza

Solucionando Problemas de Descarga:

  • El spinner nunca se detiene - Verifica la consola del navegador, la API puede estar caída
  • PDF en blanco o dañado - Verifica la plantilla de factura en busca de errores de sintaxis
  • La descarga falla - Verifica la configuración del bloqueador de ventanas emergentes, prueba con otro navegador

Pagando Facturas​

Haz clic en el ícono de pago (💰) para pagar una factura en línea.

Modal de Pago de Factura{.align-center width="800px"}

Proceso de Pago:

  1. Haz clic en el ícono de pago en la factura no pagada
  2. Se abre el modal de pago mostrando los detalles de la factura
  3. Selecciona el método de pago:
    • Transacción de Stripe - Cargar tarjeta de crédito guardada (disponible para todos los usuarios)
    • Efectivo - Pago en efectivo manual (solo personal)
    • Reembolso - Aplicar reembolso como pago (solo personal)
    • Transacción POS - Terminal de punto de venta (solo personal)
    • Transferencia Bancaria - Transferencia bancaria manual (solo personal)
  4. Si se selecciona Stripe:
    • Selecciona la tarjeta de los métodos de pago guardados
    • La tarjeta predeterminada se preselecciona
    • Haz clic para seleccionar una tarjeta diferente
  5. Si se selecciona otro método:
    • Ingresa el número de referencia (opcional)
  6. Haz clic en "Pagar Factura" para procesar
  7. El sistema procesa el pago:
    • Stripe - Carga la tarjeta a través de la API de Stripe
    • Otros métodos - Crea una transacción negativa por el monto del pago
  8. El estado de la factura cambia a "Pagada"
  9. Se muestra una notificación de éxito

Auto-Cuidado vs Pago del Personal:

:doc:`Portal de Auto-Cuidado <self_care_portal>` (Clientes):

  • Solo está disponible el pago de Stripe
  • Debe tener un método de pago guardado
  • Se muestra una advertencia si no existen métodos de pago
  • Se proporciona un enlace para agregar un método de pago

Portal del Personal (Administradores):

  • Todos los métodos de pago están disponibles
  • Puede marcar la factura como pagada manualmente (efectivo, POS, transferencia bancaria)
  • Puede ingresar números de referencia para seguimiento

Advertencia de Método de Pago:

Si el cliente no tiene métodos de pago guardados, se muestra una advertencia instándolo a agregar un método de pago antes de poder pagar facturas.

Advertencia de Método de Pago Faltante{.align-center width="800px"}

Enviando Facturas por Correo Electrónico​

Haz clic en el ícono de correo electrónico (✉️) para enviar la factura al cliente.

Qué Ocurre:

  1. Haz clic en el ícono de correo electrónico junto a la factura
  2. El sistema recupera el PDF de la factura de la caché (o genera si no está en caché)
  3. Envía el correo electrónico a través de Mailjet utilizando la plantilla api_crmCommunicationCustomerInvoice
  4. El correo electrónico incluye:
    • PDF de la factura como archivo adjunto
    • Nombre del cliente
    • Número de factura y fecha de vencimiento
    • Monto total debido
    • Enlace para pagar la factura en línea
    • Enlace para ver/descargar la factura
  5. Notificación de éxito: "Correo electrónico de factura enviado con éxito"

Destinatarios del Correo Electrónico:

El correo electrónico se envía a todos los contactos del cliente con tipo "facturación" o contacto principal si no existe contacto de facturación.

Variables de Plantilla de Correo Electrónico:

  • {{ var:customer_name }} - Nombre completo del cliente
  • {{ var:invoice_number }} - ID de la factura
  • {{ var:invoice_date }} - Fecha de emisión de la factura
  • {{ var:due_date }} - Fecha de vencimiento del pago
  • {{ var:total_amount }} - Monto total debido
  • {{ var:invoice_url }} - Enlace para ver/descargar PDF
  • {{ var:pay_url }} - Enlace para pagar la factura en línea

Solucionando Problemas de Correo Electrónico:

  • Correo electrónico no enviado - Verifica las credenciales de la API de Mailjet en crm_config.yaml
  • Cliente no recibe - Verifica las direcciones de correo electrónico de contacto del cliente
  • PDF no adjunto - Verifica que la generación del PDF haya tenido éxito (intenta descargar primero)

Anulando Facturas​

Haz clic en el ícono de eliminar (🗑️) para anular una factura.

Requisitos:

  • La factura debe estar No Pagada
  • Las facturas pagadas no pueden ser anuladas (deben ser reembolsadas en su lugar)

Cómo Anular:

  1. Localiza la factura no pagada en la lista
  2. Haz clic en el ícono de eliminar (🗑️)
  3. Confirma en el modal:

Modal de Confirmación de Anulación de Factura{.align-center width="600px"}

Qué Ocurre:

  • La factura se marca como void = true
  • Todas las transacciones se desvinculan de la factura (invoice_id se establece en null)
  • Las transacciones se convierten nuevamente en "no facturadas"
  • Las transacciones pueden incluirse en una nueva factura
  • La factura aparece en la lista con el prefijo "Anulada:" en el título
  • Las acciones de la factura están deshabilitadas (sin descarga, pago o correo electrónico)
  • Se puede ver filtrando por facturas "Anuladas"

Notas Importantes:

  • Anular NO es lo mismo que reembolsar
  • Anular = "Esta factura nunca debió existir" (error de facturación, duplicado)
  • Reembolsar = "Revertir una factura válida pagada" (devolver dinero al cliente)

Reembolsando Facturas​

Haz clic en el ícono de reembolso (💸) para reembolsar una factura pagada.

Requisitos:

  • La factura debe estar Pagada
  • La factura debe haber sido pagada a través de Stripe
  • La factura debe tener un payment_reference válido (ID de intención de pago de Stripe)
  • Solo disponible para usuarios del personal (no para Auto-Cuidado)

Cómo Reembolsar:

  1. Localiza la factura de Stripe pagada
  2. Haz clic en el ícono de reembolso (💸)
  3. Se abre el modal de confirmación de reembolso:

Modal de Confirmación de Reembolso de Factura{.align-center width="800px"}

  1. Haz clic en "Confirmar Reembolso"
  2. El sistema procesa el reembolso de Stripe:
    • Llama a la API de Stripe para reembolsar el pago
    • Crea una transacción de reembolso en Stripe
    • Actualiza la factura con refund_reference
  3. El estado de la factura cambia a "Reembolsada"
  4. Se muestra una notificación de éxito

Qué Ocurre Después del Reembolso:

  • La factura permanece en el sistema (no anulada)
  • El estado muestra "Reembolsada"
  • Las transacciones permanecen vinculadas a la factura
  • El cliente recibe el reembolso en el método de pago original (3-7 días hábiles)
  • El panel de Stripe muestra la transacción de reembolso

Restricciones de Reembolso:

  • No se pueden reembolsar facturas pagadas en efectivo, POS o transferencia bancaria (se requiere reversión manual)
  • No se puede reembolsar parcialmente (solo el monto total de la factura)
  • No se puede reembolsar dos veces

Buscando y Filtrando Facturas​

Buscar​

Usa la barra de búsqueda para encontrar facturas. Busca en:

  • ID de factura
  • Título de factura
  • Nombre del cliente (solo vista a nivel de sistema)

Filtros​

Aplica filtros para reducir la lista de facturas:

Filtros Disponibles:

  • Estado de Anulación - Todos, Anuladas, No Anuladas
  • Estado de Pago - Todos, Pagadas, No Pagadas

Acciones de Filtro:

  • Aplicar Filtros - Aplicar filtros seleccionados a la lista
  • Restablecer Filtros - Limpiar todos los filtros y mostrar todas las facturas

Ordenar​

Haz clic en cualquier encabezado de columna para ordenar:

  • ID - Ordenar por ID de factura (más nuevo/más antiguo)
  • Título - Ordenar alfabéticamente
  • Fecha de Vencimiento - Ordenar por fecha de vencimiento
  • Creado - Ordenar por fecha de creación
  • Monto - Ordenar por costo al por menor (más alto/más bajo)
  • Estado - Ordenar por estado de pago (pagado primero o no pagado primero)

Haz clic nuevamente para invertir la dirección de ordenación (ascendente ↔ descendente).

Paginación​

Navega a través de listas grandes de facturas con controles de página que muestran la página actual, el total de páginas y un selector de elementos por página (10, 25, 50 o 100 elementos).

Flujos de Trabajo Comunes de Facturas​

Flujo de Trabajo 1: Facturación Mensual con Vista Previa de Transacción​

  1. Llega el final del mes (por ejemplo, 31 de enero)
  2. Navega a Facturación → Facturas
  3. Haz clic en "+ Generar Factura Proforma"
  4. Selecciona cliente (o hazlo por cliente si facturas a muchos clientes)
  5. Establece las fechas:
    • Fecha de Inicio: 2025-01-01
    • Fecha de Finalización: 2025-01-31
    • Fecha de Vencimiento: 2025-02-15 (15 días a partir de ahora)
    • Título: "Servicios de enero de 2025" (opcional)
  6. La sección de Vista Previa de Transacción aparece mostrando todas las transacciones no facturadas de enero
  7. Revisa la vista previa:
    • Todas las transacciones están incluidas por defecto
    • Verifica los totales: Subtotal, Impuesto y Total de la Factura
    • Verifica que todos los cargos sean correctos
  8. Haz clic en "Generar Factura" (el botón muestra el conteo de transacciones, por ejemplo, "Generar Factura (15)")
  9. Factura creada con todas las transacciones seleccionadas
  10. Haz clic en la fila de la factura para ver detalles y verificar
  11. Haz clic en el botón "Enviar Correo" en el modal de detalles o en el ícono de correo en la tabla
  12. El cliente recibe un correo electrónico de factura con PDF y enlace de pago

Flujo de Trabajo 2: Facturación Selectiva de Transacciones​

  1. El cliente tiene múltiples servicios (Móvil + Internet) y cargos varios
  2. Quiere facturas separadas para cada servicio
  3. Generar primera factura (Servicios Móviles):
    • Haz clic en "+ Generar Factura Proforma"
    • Título: "Servicios Móviles - Enero 2025"
    • Inicio/Fin: 1-31 de enero
    • Fecha de Vencimiento: 15 de febrero
    • En la vista previa de transacciones, excluye todas las transacciones no móviles:
      • Haz clic en el botón X junto a las transacciones de Internet
      • Haz clic en el botón X junto a los cargos varios
      • Solo permanecen seleccionadas las transacciones de servicios móviles
    • Verifica que los totales reflejen solo servicios móviles
    • Haz clic en "Generar Factura" (muestra el conteo de transacciones móviles)
  4. Generar segunda factura (Servicios de Internet):
    • Haz clic en "+ Generar Factura Proforma" nuevamente
    • Título: "Servicios de Internet - Enero 2025"
    • Inicio/Fin: 1-31 de enero (mismo período)
    • En la vista previa de transacciones:
      • Las transacciones móviles ya facturadas (no aparecen)
      • Excluye los cargos varios usando el botón X
      • Solo permanecen las transacciones de servicios de Internet
    • Haz clic en "Generar Factura"
  5. Generar tercera factura (Cargos Adicionales):
    • Haz clic en "+ Generar Factura Proforma" nuevamente
    • Título: "Cargos Adicionales - Enero 2025"
    • Solo aparecen en la vista previa los cargos varios no facturados
    • Haz clic en "Seleccionar Todo" para incluir todos
    • Haz clic en "Generar Factura"
  6. Envía las tres facturas al cliente

Flujo de Trabajo 3: Excluyendo Transacciones Disputadas o Pendientes​

  1. Llega el final del período de facturación
  2. Navega a la pestaña de Facturación del cliente
  3. Haz clic en "+ Generar Factura Proforma"
  4. Establece las fechas del período de facturación
  5. La vista previa de transacciones muestra 20 transacciones
  6. El cliente ha disputado un cargo y otro está pendiente de investigación
  7. En la vista previa de transacciones:
    • Localiza la transacción disputada (por ejemplo, "Cargo por exceso de datos")
    • Haz clic en el botón X para excluirla
    • Localiza la transacción pendiente (por ejemplo, "Cargo de instalación")
    • Haz clic en el botón X para excluirla
    • El conteo de transacciones se actualiza: "18 Transacciones seleccionadas"
    • Los totales se recalculan automáticamente
  8. Revisa los totales actualizados (excluye los montos disputados)
  9. Haz clic en "Generar Factura (18)"
  10. Factura generada con solo las transacciones aprobadas
  11. Las transacciones disputadas/pendientes permanecen no facturadas para el próximo ciclo de facturación

Flujo de Trabajo 4: Revisión Rápida de Factura y Ajuste​

  1. El personal genera la factura mensual
  2. La vista previa de transacciones muestra un total inesperadamente alto
  3. Revisa cada transacción en la vista previa:
    • Nota un cargo duplicado por el mismo servicio
    • Haz clic en X para excluir el duplicado
    • Nota una transacción de prueba que no debería ser facturada
    • Haz clic en X para excluir la transacción de prueba
  4. Los totales se actualizan en tiempo real
  5. Verifica que el nuevo total coincida con el monto esperado
  6. Haz clic en "Generar Factura" con las transacciones corregidas
  7. Regresa y anula/elimina las transacciones excluidas si es necesario
  8. Envía la factura al cliente con confianza

Flujo de Trabajo 5: Factura de Instalación Única​

  1. El técnico de campo completa la instalación
  2. El personal agrega la transacción de instalación manualmente
  3. Navega a la pestaña de Facturación del cliente
  4. Haz clic en "+ Generar Factura Proforma"
  5. Establece las fechas:
    • Fecha de Inicio: hoy
    • Fecha de Finalización: hoy
    • Fecha de Vencimiento: hoy + 7 días
    • Título: "Servicios de Instalación"
  6. La vista previa de transacciones muestra solo las transacciones de hoy
  7. Verifica que el cargo de instalación aparezca
  8. Excluye cualquier cargo recurrente usando el botón X (si está presente)
  9. Haz clic en "Generar Factura"
  10. Envía al cliente de inmediato
  11. El cliente paga en línea a través de Stripe

Flujo de Trabajo 6: Revisando la Factura Antes del Contacto con el Cliente​

  1. El cliente llama con una pregunta de facturación
  2. El personal navega a la lista de facturas del cliente
  3. Haz clic en la fila de la factura para abrir el modal de Detalles de la Factura
  4. Revisa la información de la factura:
    • ID de factura, fechas, estado
    • Todas las transacciones incluidas con descripciones
    • Desglose de impuestos por transacción
    • Subtotal, Impuesto y Totales
  5. Responde a las preguntas del cliente con detalles exactos
  6. Si el cliente solicita el PDF, haz clic en el botón "Descargar PDF" en el modal
  7. Si el cliente solicita reenvío de correo electrónico, haz clic en el botón "Enviar Correo"
  8. Cierra el modal cuando termines

Flujo de Trabajo 7: Corrigiendo un Error de Facturación​

  1. El cliente informa un cargo incorrecto
  2. El personal hace clic en la fila de la factura para ver detalles
  3. Revisa la lista de transacciones en el modal de Detalles de la Factura
  4. Identifica la transacción incorrecta
  5. La factura está no pagada, por lo que puede ser anulada
  6. Haz clic en el botón "Eliminar" en el pie del modal
  7. Confirma la anulación
  8. Las transacciones se convierten nuevamente en no facturadas
  9. El personal modifica o elimina la transacción incorrecta de la lista de transacciones
  10. Genera una nueva factura con las transacciones corregidas:
    • Usa la vista previa de transacciones para excluir la transacción corregida si es necesario
    • Incluye solo cargos válidos
  11. Envía la factura corregida al cliente

Flujo de Trabajo 8: Procesando Múltiples Pagos​

  1. El cliente trae efectivo para pagar múltiples facturas
  2. Navega a la pestaña de Facturación del cliente
  3. Ver facturas no pagadas
  4. Haz clic en la primera fila de la factura para ver detalles
  5. Verifica el monto y las transacciones
  6. Haz clic en el botón "Pagar Factura" en el pie del modal
  7. Selecciona el método de pago "Efectivo"
  8. Ingresa la referencia: "Efectivo pagado 2025-01-15"
  9. Haz clic en "Pagar Factura"
  10. El modal se cierra, la factura se marca como "Pagada"
  11. Repite para las facturas restantes
  12. Todas las facturas ahora marcadas como "Pagadas"

Flujo de Trabajo 9: Manejo de Solicitud de Reembolso​

  1. El cliente solicita un reembolso por sobrepago
  2. El personal verifica que la factura fue pagada a través de Stripe
  3. Navega a la factura en la lista
  4. Haz clic en la fila de la factura para ver detalles
  5. Verifica la información de pago y el monto
  6. Haz clic en el botón "Reembolsar" en el pie del modal (solo aparece para facturas de Stripe)
  7. Confirma el reembolso
  8. El sistema procesa el reembolso de Stripe
  9. El estado de la factura cambia a "Reembolsada"
  10. El cliente recibe el reembolso en 3-7 días hábiles
  11. El personal sigue con el cliente para confirmar la recepción

Solucionando Problemas​

No se puede generar factura - No se encontraron transacciones

  • Causa: No hay transacciones no facturadas en el rango de fechas especificado
  • Solución: Verifica la lista de transacciones, asegúrate de que existan y no estén ya facturadas. Ajusta el rango de fechas o elimina el filtro.

Fallo en la generación del PDF de la factura

  • Causa: Error de sintaxis en la plantilla, fallo de WeasyPrint o falta de datos del cliente
  • Solución: Verifica la plantilla HTML de la factura en busca de errores, verifica que los campos de dirección del cliente estén poblados, revisa los registros de la API.

Fallo en el pago con error de Stripe

  • Causa: Tarjeta rechazada, fondos insuficientes, tarjeta expirada o problema con la API de Stripe
  • Solución: Prueba con otro método de pago, verifica que la tarjeta sea válida, revisa el panel de Stripe para ver el motivo del rechazo.

No se puede anular la factura

  • Causa: La factura ya está pagada
  • Solución: Las facturas pagadas no pueden ser anuladas. Si se necesita un reembolso, usa la función de reembolso para facturas de Stripe o crea una transacción de crédito manualmente.

El correo electrónico de la factura no se envía

  • Causa: Credenciales de la API de Mailjet inválidas, el cliente no tiene contacto de facturación o falta la plantilla de correo electrónico
  • Solución: Verifica la configuración de Mailjet en crm_config.yaml, revisa los contactos del cliente, verifica que exista la plantilla de correo electrónico de la factura.

El botón de reembolso no aparece

  • Causa: La factura fue pagada en efectivo/POS/transferencia bancaria (no Stripe), o la factura no está pagada
  • Solución: El botón de reembolso solo aparece para pagos de Stripe. Para otros métodos de pago, crea una transacción de crédito manual.

La descarga del PDF muestra el diseño de plantilla antiguo

  • Causa: PDF almacenado en caché antes de la actualización de la plantilla
  • Solución: Limpia la caché de PDF de la factura: DELETE FROM Invoice_PDF_Cache WHERE invoice_id = X;

El cliente no puede pagar la factura (sin métodos de pago)

  • Causa: No hay métodos de pago guardados en el portal de Auto-Cuidado
  • Solución: El cliente debe agregar una tarjeta de crédito en la página de Métodos de Pago antes de pagar facturas.

Se generaron múltiples facturas para el mismo período

  • Causa: El personal generó la factura dos veces, o los rangos de fechas se superponen
  • Solución: Anula la factura duplicada. Ajusta los rangos de fechas para evitar superposiciones. Usa la vista previa de transacciones para asegurar conjuntos de transacciones únicos.

La vista previa de transacciones no muestra transacciones

  • Causa: Todas las transacciones en el rango de fechas ya están facturadas o no existen transacciones
  • Solución: Verifica que el rango de fechas sea correcto. Verifica la lista de transacciones para confirmar que existan. Filtra las facturas para ver qué factura contiene las transacciones.

No se puede excluir la transacción de la generación de la factura

  • Causa: La transacción ya está facturada o hay un problema con el navegador
  • Solución: Verifica que la transacción se muestre en la vista previa con una marca de verificación. Actualiza la página y vuelve a intentarlo. Limpia la caché del navegador si el problema persiste.

El total de la factura no coincide con el monto esperado

  • Causa: Se incluyeron transacciones inesperadas, no se calculó el impuesto o las transacciones excluidas aún se cuentan
  • Solución: Revisa cuidadosamente la vista previa de transacciones. Verifica el costo al por menor y el impuesto de cada transacción. Verifica que las transacciones excluidas estén atenuadas. Revisa el distintivo de conteo de transacciones en el botón Generar Factura.

El botón Generar Factura está deshabilitado

  • Causa: No se seleccionaron transacciones o el rango de fechas es inválido
  • Solución: Asegúrate de que al menos una transacción esté incluida (no excluida). Verifica que la Fecha de Inicio sea anterior a la Fecha de Finalización. Asegúrate de que la Fecha de Vencimiento esté establecida.

El modal de Detalles de la Factura no se abre

  • Causa: Error de JavaScript o la página no se cargó completamente
  • Solución: Actualiza la página. Verifica la consola del navegador en busca de errores. Prueba con otro navegador. Verifica la conexión a internet.

El impuesto de la transacción no se muestra en los Detalles de la Factura

  • Causa: La transacción tiene un impuesto del 0% o tax_amount es nulo
  • Solución: Verifica que la transacción tenga tax_percentage establecido. Verifica que tax_amount se haya calculado cuando se creó la transacción. Actualiza la transacción si es necesario.

Faltan botones de acción en el modal de Detalles de la Factura

  • Causa: La factura está anulada o el usuario no tiene permisos
  • Solución: Las facturas anuladas solo muestran el botón Descargar PDF. Verifica el estado de la factura. Revisa el rol y los permisos del usuario.

Documentación Relacionada​

  • integrations_mailjet - Entrega de facturas por correo electrónico y plantillas
  • administration_configuration - Configuración de plantillas de factura
  • payments_transaction - Creación de transacciones que aparecen en las facturas
  • payments_process - Procesamiento de pagos de facturas
  • basics_payment - Métodos de pago e integración de Stripe