Pular para o conteúdo principal

Faturas de Clientes

Transações são agrupadas para formar uma fatura, que é enviada ao cliente para pagamento.

As faturas têm uma data de início e uma data de término, que é o período que a fatura cobre, e uma data de vencimento, que é a data em que a fatura deve ser paga.

Gerar uma Fatura Proforma

As faturas podem ser geradas automaticamente pelo sistema, por exemplo, quando um serviço é cobrado, uma fatura é criada para o custo de varejo, ou podem ser criadas manualmente, por exemplo, se um cliente solicitar uma cópia de uma fatura, ou se um cliente for cobrado por uma taxa única.

As faturas dos clientes são totalmente modeladas com Mailjet e podem ser personalizadas para incluir o logotipo da empresa, endereço e detalhes de pagamento, e podem ser enviadas ao cliente por e-mail ou baixadas como um PDF.

Registro de Atividades

Personalizando Modelos de Faturas​

OmniCRM usa modelos HTML com Jinja2 para gerar faturas. Você pode personalizar completamente o design da fatura, branding, cores e layout.

Localização do Modelo de Fatura​

Os modelos de fatura são armazenados em OmniCRM-API/invoice_templates/

Modelos Padrão:

  • norfone_invoice_template.html - Modelo de fatura de exemplo
  • cifi_invoice_template.html - Exemplo de modelo alternativo

Configuração:

O modelo de fatura ativo é especificado em OmniCRM-API/crm_config.yaml:

invoice:
  template_filename: 'norfone_invoice_template.html'

Variáveis de Modelo Disponíveis​

Os modelos de fatura têm acesso às seguintes variáveis Jinja2:

Informações da Fatura:

  • {{ invoice_number }} - ID único da fatura (por exemplo, INV-2025-001234)
  • {{ date }} - Data de emissão da fatura (formato ISO: 2025-01-10T12:00:00)
  • {{ due_date }} - Data de vencimento do pagamento (por exemplo, 2025-02-10)
  • {{ start_date }} - Data de início do período de faturamento
  • {{ end_date }} - Data de término do período de faturamento
  • {{ total_amount }} - Valor total da fatura antes do imposto (numérico)
  • {{ total_tax }} - Valor total do imposto calculado a partir de todas as transações (numérico)

Informações do Cliente:

  • {{ client.name }} - Nome completo do cliente ou nome da empresa
  • {{ client.address.address_line_1 }} - Linha de endereço 1
  • {{ client.address.address_line_2 }} - Linha de endereço 2
  • {{ client.address.city }} - Cidade
  • {{ client.address.state }} - Estado/província
  • {{ client.address.zip_code }} - Código postal/ZIP
  • {{ client.address.country }} - País

Itens de Linha de Transação:

Percorra as transações 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 Transação:

  • sub_transaction.transaction_id - ID da transação
  • sub_transaction.created - Data/hora da transação
  • sub_transaction.title - Título da transação
  • sub_transaction.description - Descrição detalhada
  • sub_transaction.retail_cost - Valor do item
  • sub_transaction.tax_percentage - Percentual de imposto aplicado (por exemplo, 10 para 10%)
  • sub_transaction.tax_amount - Valor do imposto calculado em dólares

Exibindo Imposto em Modelos:

<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>

Criando um Modelo de Fatura Personalizado​

Passo 1: Copiar Modelo Existente

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

Passo 2: Personalizar HTML/CSS

Edite your_company_invoice_template.html para corresponder ao seu branding:

Áreas de Personalização Chave:

  1. Logotipo e Branding da Empresa

    <!-- Substitua pela URL do seu logotipo -->
    <img src="https://yourcompany.com/logo.png" alt="Sua Empresa" width="200">

    <!-- Atualize o nome da empresa -->
    <h1>Nome da Sua Empresa</h1>

  2. Esquema de Cores

    <style>
        /* Cor primária da marca */
        .navbar {
            background: linear-gradient(to bottom right, #your-color-1, #your-color-2);
        }

        /* Cabeçalhos da tabela */
        .table thead th {
            background-color: #your-brand-color !important;
            color: white !important;
        }

        /* Botões e links */
        .btn-primary {
            background-color: #your-brand-color;
        }
    </style>

  3. Informações da Empresa no Rodapé

    <footer>
        <p>Nome da Sua Empresa</p>
        <p>123 Business Street, Cidade, País</p>
        <p>Telefone: +1-555-123-4567 | Email: billing@yourcompany.com</p>
        <p>ABN/Tax ID: 12345678900</p>
    </footer>

  4. Instruções de Pagamento

    <div class="payment-info">
        <h3>Métodos de Pagamento</h3>
        <p><strong>Online:</strong> Pague em https://yourcompany.com/pay</p>
        <p><strong>Transferência Bancária:</strong></p>
        <ul>
            <li>Nome da Conta: Sua Empresa Ltd</li>
            <li>BSB: 123-456</li>
            <li>Número da Conta: 987654321</li>
            <li>Referência: {{ invoice_number }}</li>
        </ul>
    </div>

  5. Termos e Condições

    <div class="terms">
        <h4>Termos de Pagamento</h4>
        <p>Pagamento devido dentro de 30 dias a partir da data da fatura.</p>
        <p>Taxas de atraso: 2% ao mês sobre saldos em atraso.</p>
        <p>Para consultas de faturamento: billing@yourcompany.com</p>
    </div>

Passo 3: Atualizar Configuração

Edite OmniCRM-API/crm_config.yaml:

invoice:
  template_filename: 'your_company_invoice_template.html'

Passo 4: Reiniciar API

cd OmniCRM-API
sudo systemctl restart omnicrm-api

Passo 5: Testar Geração de Faturas

  1. Navegue até um cliente com transações
  2. Gere uma fatura de teste
  3. Baixe o PDF para verificar a formatação
  4. Envie a fatura para si mesmo para testar a entrega por e-mail

Personalização Avançada​

Conteúdo Condicional:

Use condicionais Jinja2 para mostrar/ocultar conteúdo:

{% if total_amount > 1000 %}
    <div class="high-value-notice">
        <p><strong>Nota:</strong> Saldo alto - Plano de pagamento disponível mediante solicitação.</p>
    </div>
{% endif %}

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

Suporte a Múltiplos Idiomas:

Crie modelos específicos para cada idioma:

invoice_template_en.html
invoice_template_es.html
invoice_template_fr.html

Configure com base na preferência de idioma do cliente.

Cálculos Personalizados:

<!-- Exibir subtotal e detalhamento do imposto -->
<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>Imposto:</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: A variável total_tax é calculada automaticamente somando o tax_amount de todas as transações na fatura. O imposto de cada transação é calculado com base no campo tax_percentage, que por padrão é o tax_percentage do produto ou 0% se não especificado.

Código QR para Pagamento:

Gere um código QR para pagamento móvel:

<div class="qr-payment">
    <img src="https://api.qrserver.com/v1/create-qr-code/?size=150x150&data={{ payment_url }}"
         alt="Escaneie para Pagar">
    <p>Escaneie com seu telefone para pagar instantaneamente</p>
</div>

Melhores Práticas de Estilo para PDF​

OmniCRM utiliza WeasyPrint para converter HTML em PDF. Siga estas diretrizes:

CSS Suportado:

  • A maioria das propriedades CSS 2.1
  • CSS3 limitado (flexbox, algumas transformações)
  • Fontes da web via @font-face

Não Suportado:

  • JavaScript
  • CSS Grid (use tabelas em vez disso)
  • Animações complexas
  • Algumas propriedades CSS modernas

Tamanho da Página e Margens:

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

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

Estilo Específico para Impressão:

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

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

Layout da Tabela:

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

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

Incorporação de Fontes:

Para fontes personalizadas, use fontes seguras para a web ou incorpore:

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

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

Testando Modelos de Fatura​

Lista de Verificação de Teste:

  1. Inspeção Visual:
    • O logotipo é exibido corretamente
    • As cores correspondem às diretrizes da marca
    • O texto é legível (não muito pequeno)
    • As tabelas estão alinhadas corretamente
    • Todas as seções estão presentes
  2. Precisão dos Dados:
    • Detalhes do cliente corretos
    • Os valores das transações somam corretamente
    • As datas estão formatadas corretamente
    • Todas as variáveis estão substituindo corretamente
  3. Qualidade do PDF:
    • O tamanho do arquivo é razoável (<5MB)
    • As imagens estão nítidas e claras
    • Sem texto cortado ou transbordamento
    • Quebras de página em lugares apropriados
  4. Faturas de Múltiplas Páginas:
    • Os cabeçalhos se repetem em cada página
    • Os números das páginas são exibidos
    • Listas longas de transações paginam corretamente
  5. Entrega por E-mail:
    • O PDF é anexado ao e-mail
    • O tamanho do arquivo está abaixo do limite do Mailjet (15MB)
    • Renderiza no Gmail, Outlook, Apple Mail

Comando de Teste (Geração Manual):

Você pode testar a geração de faturas via API:

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

Problemas Comuns de Modelo​

Variáveis não substituindo:

  • Causa: Erro de digitação no nome da variável ou dados ausentes
  • Correção: Verifique a ortografia exatamente (sensível a maiúsculas e minúsculas), verifique se os dados existem no banco de dados

Estilo do PDF quebrado:

  • Causa: Propriedade CSS não suportada
  • Correção: Use propriedades CSS 2.1, teste com CSS compatível com WeasyPrint

Imagens não exibindo:

  • Causa: URLs relativas ou recursos externos bloqueados
  • Correção: Use URLs HTTPS absolutas, certifique-se de que as imagens sejam acessíveis publicamente

Tabelas transbordando a página:

  • Causa: Larguras de coluna fixas muito largas
  • Correção: Use larguras percentuais, table-layout: fixed

Fontes não renderizando:

  • Causa: Fonte não incorporada ou indisponível
  • Correção: Use fontes seguras para a web (Arial, Times New Roman, etc.) ou incorpore corretamente fontes personalizadas

Falha na geração do PDF:

  • Causa: Erros de sintaxe HTML ou falha do WeasyPrint
  • Correção: Valide o HTML, verifique os logs do WeasyPrint, simplifique layouts complexos

Cache de PDF de Fatura​

Para melhorar o desempenho e reduzir a geração redundante de PDFs, o OmniCRM inclui um sistema de cache de PDF de fatura. Quando um PDF de fatura é gerado pela primeira vez, ele é armazenado em cache no banco de dados para solicitações subsequentes.

Como Funciona o Cache de PDF:

  1. Primeira Solicitação - Quando um PDF de fatura é solicitado (download ou e-mail), o sistema:
    • Gera o PDF a partir do modelo de fatura
    • Codifica o PDF como Base64
    • Calcula um hash SHA256 do conteúdo do PDF
    • Armazena na tabela Invoice_PDF_Cache com:
      • Referência do ID da fatura
      • Dados do PDF (codificados em Base64)
      • Nome do arquivo
      • Hash do conteúdo (para verificação de integridade)
      • Timestamp de criação
  2. Solicitações Subsequentes - Quando a mesma fatura é solicitada novamente:
    • O sistema verifica se há um PDF em cache pelo invoice_id
    • Se o cache existir e for válido, retorna o PDF em cache imediatamente
    • Atualiza o timestamp last_accessed para rastrear o uso do cache
  3. Invalidade do Cache - PDFs em cache são invalidados quando:
    • A fatura é modificada (transações adicionadas/removidas, detalhes alterados)
    • O modelo de fatura é atualizado
    • A limpeza manual do cache é acionada

Benefícios:

  • Desempenho - Entrega instantânea de PDF para solicitações repetidas (sem atraso de regeneração)
  • Consistência - Mesmo PDF para todos os downloads de uma fatura (a menos que a fatura seja modificada)
  • Carga do Servidor - Reduz o uso da CPU na geração de PDFs
  • Experiência do Usuário - Um indicador de carregamento aparece durante a geração inicial, solicitações subsequentes são instantâneas

Gerenciamento de Cache:

O Cache de PDF de Fatura é gerenciado automaticamente pelo sistema. Entradas de cache antigas ou não utilizadas podem ser purgadas periodicamente com base em:

  • Idade (por exemplo, remover entradas de cache com mais de 90 dias)
  • Padrões de acesso (remover entradas não acessadas em 30 dias)
  • Limites de armazenamento (implementar limites de tamanho de cache, se necessário)

Comportamento da API:

Ao baixar uma fatura via API ou UI:

  • Primeira solicitação: Mostra indicador de carregamento enquanto o PDF é gerado, depois armazena em cache
  • Solicitações subsequentes: Download imediato do cache
  • Acerto de cache é transparente para o usuário

Importante: Quando você atualizar seu modelo de fatura, limpe o cache para garantir que novas faturas usem o design atualizado:

-- Limpar todos os PDFs de fatura em cache (executar no MySQL)
DELETE FROM Invoice_PDF_Cache;

Ou atualize crm_config.yaml para invalidar automaticamente o cache na alteração do modelo.

Acessando Faturas​

As faturas podem ser visualizadas no nível do sistema ou por cliente:

Visualização por Cliente:

  1. Navegue até Clientes → [Selecionar Cliente]
  2. Clique na aba Faturamento
  3. Veja a lista de faturas no terceiro cartão

Visualização em Todo o Sistema:

  1. Navegue até Faturamento → Faturas (no menu principal)
  2. Veja todas as faturas de todos os clientes

Widgets de Estatísticas de Faturas​

Na parte superior da página de faturas, quatro cartões de estatísticas exibem resumos financeiros.

Estatísticas de Fatura e Lista{.align-center width="800px"}

Descrições dos Widgets:

  • Total de Faturas - Soma de todos os custos de varejo das faturas (todos os tempos) e contagem de faturas enviadas
  • Faturas Não Pagas - Soma de faturas ainda não pagas e contagem de faturas não pagas
  • Faturas Este Mês - Soma de faturas criadas neste mês calendário com contagem
  • Faturas Mês Passado - Soma de faturas criadas no mês calendário passado com contagem

Formatação de Valores:

  • Valores acima de 1.000: Exibir como sufixo "k" (por exemplo, $1.5k)
  • Valores acima de 1.000.000: Exibir como sufixo "M" (por exemplo, $2.3M)
  • Valores acima de 1.000.000.000: Exibir como sufixo "B" (por exemplo, $1.1B)

Indicadores de Tendência:

  • Widgets para "Este Mês" e "Mês Passado" mostram a variação percentual
  • Seta verde para cima: Aumento em relação ao período anterior
  • Seta vermelha para baixo: Diminuição em relação ao período anterior
  • Seta cinza para a direita: Sem alteração

Lista de Faturas​

A tabela de faturas exibe todas as faturas com as seguintes colunas:

Lista Global de Faturas

Descrições das Colunas:

  • ID - ID único da fatura
  • Título - Título/descrição da fatura
  • Período - Período de faturamento (data de início - data de término) ou "N/A" para faturas únicas
  • Data de Vencimento - Data de vencimento do pagamento
  • Criado - Data de criação da fatura
  • Valor - Valor total da fatura (custo de varejo)
  • Status - Pago, Não Pago ou Reembolsado
  • Ações - Ações disponíveis (varia conforme o status)

Ícones de Ação:

  • ⬇ (Baixar) - Baixar PDF da fatura
  • 🗑️ (Excluir) - Anular fatura (somente se não estiver paga)
  • 💰 (Pagar) - Pagar fatura online (somente se não estiver paga)
  • ✉️ (E-mail) - Enviar e-mail da fatura para o cliente
  • 💸 (Reembolsar) - Reembolsar pagamento do Stripe (somente para faturas pagas do Stripe)

Gerando uma Fatura​

Clique em "+ Gerar Fatura Proforma" para criar uma nova fatura.

Modal de Gerar Fatura com Pré-visualização de Transação{.align-center width="800px"}

Descrições dos Campos:

  • Pesquisar Clientes - Selecionar cliente (apenas exibido na visualização em todo o sistema, preenchido automaticamente na visualização do cliente)
  • Título - Título/nome da fatura (opcional, padrão para "Fatura por [Período]")
  • Data de Início - Início do período de faturamento (padrão para 14 dias atrás)
  • Data de Término - Término do período de faturamento (padrão para hoje)
  • Data de Vencimento - Prazo de pagamento (padrão para hoje)
  • Pré-visualização de Transação - Mostra todas as transações não faturadas no intervalo de datas com a capacidade de incluir/excluir transações específicas

Seleção de Transação:

  • ✓ (Sinal Verde) - Clique para excluir uma transação da fatura
  • × (X Vermelho) - Clique para incluir uma transação previamente excluída
  • Selecionar Tudo - Incluir todas as transações exibidas
  • Limpar Tudo - Excluir todas as transações
  • Transações excluídas aparecem esmaecidas com texto riscado
  • Totais em tempo real são atualizados à medida que você seleciona/deseleciona transações

O que Acontece:

  1. O sistema encontra todas as transações não faturadas para o cliente dentro do intervalo de datas
  2. Exibe a pré-visualização da transação com a capacidade de incluir/excluir transações individuais
  3. Mostra o cálculo em tempo real do subtotal, imposto e total com base nas transações selecionadas
  4. Apenas as transações selecionadas (incluídas) são adicionadas à fatura
  5. Gera o PDF da fatura e o armazena em cache
  6. Marca as transações selecionadas como faturadas (campo invoice_id populado)
  7. Transações excluídas permanecem não faturadas e disponíveis para futuras faturas
  8. A fatura aparece na lista com status "Não Pago"

Exemplos de Casos de Uso:

Faturamento Mensal: Defina a data de início para o primeiro dia do mês, a data de término para o último dia do mês, a pré-visualização mostra todas as transações não faturadas daquele período. Selecione todas ou exclua manualmente as específicas.

Fatura Específica de Serviço: Use o mesmo intervalo de datas, depois exclua manualmente as transações indesejadas (por exemplo, exclua transações não móveis para criar uma fatura apenas para móveis).

Fatura Única: Defina a data de início e a data de término para o mesmo dia, a pré-visualização mostra apenas transações daquela data. Exclua quaisquer cobranças que não sejam relevantes para esta fatura específica.

Visualizando Detalhes da Fatura​

Clique em qualquer linha de fatura na tabela para visualizar todos os detalhes da fatura, incluindo todas as transações, totais e ações disponíveis.

Visualização de Detalhes da Fatura{.align-center width="800px"}

Modal de Detalhes da Fatura:

  • Informações da Fatura - Mostra ID da fatura, título, datas, status de pagamento e status de anulação
  • Lista de Transações - Exibe todas as transações incluídas na fatura com:
    • Data da transação
    • Título e descrição
    • Custo de varejo
    • Valor e percentual do imposto (formatado como $10.00 (10%))
    • Transações isentas de imposto mostram "-" na coluna de Imposto
  • Resumo dos Totais - Cálculo em tempo real mostrando:
    • Contagem de transações
    • Subtotal (soma de todos os custos de varejo)
    • Imposto (soma de todos os valores de imposto)
    • Total da Fatura (subtotal + imposto)
  • Botões de Ação - Mesmas ações disponíveis que na tabela:
    • Baixar PDF - Baixar PDF da fatura (sempre disponível)
    • Enviar E-mail - Enviar fatura para o cliente (faturas não anuladas)
    • Pagar Fatura - Processar pagamento (apenas faturas não pagas e não anuladas)
    • Reembolsar - Reembolsar pagamento do Stripe (apenas faturas pagas do Stripe)
    • Excluir - Anular fatura (apenas faturas não pagas e não anuladas)

Baixando PDFs de Faturas​

Clique no ícone de download (⬇) na tabela ou no botão "Baixar PDF" no modal de detalhes da fatura para baixar uma fatura como PDF.

Processo de Download:

  1. Clique no ícone de download ao lado da fatura
  2. O indicador de carregamento aparece durante a geração (apenas da primeira vez)
  3. O navegador solicita para salvar o arquivo: Invoice_01234.pdf
  4. O PDF é aberto ou salvo na pasta Downloads

Comportamento de Cache de PDF:

  • Primeiro Download - PDF gerado a partir do modelo, armazenado em cache no banco de dados (pode levar 2-3 segundos)
  • Downloads Subsequentes - Download instantâneo do cache
  • Invalidade de Cache - Cache limpo se a fatura for modificada ou o modelo atualizado

Resolvendo Problemas de Download:

  • O indicador de carregamento nunca para - Verifique o console do navegador, a API pode estar inativa
  • PDF em branco ou corrompido - Verifique o modelo de fatura quanto a erros de sintaxe
  • Download falha - Verifique as configurações do bloqueador de pop-ups, tente um navegador diferente

Pagando Faturas​

Clique no ícone de pagamento (💰) para pagar uma fatura online.

Modal de Pagamento da Fatura{.align-center width="800px"}

Processo de Pagamento:

  1. Clique no ícone de pagamento na fatura não paga
  2. O modal de pagamento é aberto mostrando os detalhes da fatura
  3. Selecione o método de pagamento:
    • Transação Stripe - Cobrar cartão de crédito salvo (disponível para todos os usuários)
    • Dinheiro - Pagamento manual em dinheiro (apenas para funcionários)
    • Reembolso - Aplicar reembolso como pagamento (apenas para funcionários)
    • Transação POS - Terminal de ponto de venda (apenas para funcionários)
    • Transferência Bancária - Transferência bancária manual (apenas para funcionários)
  4. Se Stripe for selecionado:
    • Selecione o cartão dos métodos de pagamento salvos
    • O cartão padrão é pré-selecionado
    • Clique para selecionar um cartão diferente
  5. Se outro método for selecionado:
    • Insira o número de referência (opcional)
  6. Clique em "Pagar Fatura" para processar
  7. O sistema processa o pagamento:
    • Stripe - Cobra o cartão via API do Stripe
    • Outros métodos - Cria uma transação negativa para o valor do pagamento
  8. O status da fatura muda para "Pago"
  9. Notificação de sucesso exibida

Portal de Autoatendimento vs Pagamento de Funcionários:

:doc:`Portal de Autoatendimento <self_care_portal>` (Clientes):

  • Apenas pagamento Stripe disponível
  • Deve ter método de pagamento salvo
  • Aviso exibido se não houver métodos de pagamento existentes
  • Link para adicionar método de pagamento fornecido

Portal de Funcionários (Administradores):

  • Todos os métodos de pagamento disponíveis
  • Pode marcar a fatura como paga manualmente (dinheiro, POS, transferência bancária)
  • Pode inserir números de referência para rastreamento

Aviso de Método de Pagamento:

Se o cliente não tiver métodos de pagamento salvos, um aviso é exibido solicitando que ele adicione um método de pagamento antes de poder pagar faturas.

Aviso de Método de Pagamento Ausente{.align-center width="800px"}

Enviando Faturas por E-mail​

Clique no ícone de e-mail (✉️) para enviar a fatura ao cliente.

O que Acontece:

  1. Clique no ícone de e-mail ao lado da fatura
  2. O sistema recupera o PDF da fatura do cache (ou gera se não estiver em cache)
  3. Envia e-mail via Mailjet usando o modelo api_crmCommunicationCustomerInvoice
  4. O e-mail inclui:
    • PDF da fatura como anexo
    • Nome do cliente
    • Número da fatura e data de vencimento
    • Valor total devido
    • Link para pagar a fatura online
    • Link para visualizar/baixar a fatura
  5. Notificação de sucesso: "E-mail da fatura enviado com sucesso"

Destinatários do E-mail:

O e-mail é enviado a todos os contatos do cliente com o tipo "faturamento" ou ao contato principal se não existir contato de faturamento.

Variáveis do Modelo de E-mail:

  • {{ var:customer_name }} - Nome completo do cliente
  • {{ var:invoice_number }} - ID da fatura
  • {{ var:invoice_date }} - Data de emissão da fatura
  • {{ var:due_date }} - Data de vencimento do pagamento
  • {{ var:total_amount }} - Valor total devido
  • {{ var:invoice_url }} - Link para visualizar/baixar PDF
  • {{ var:pay_url }} - Link para pagar a fatura online

Resolvendo Problemas de E-mail:

  • E-mail não enviado - Verifique as credenciais da API do Mailjet em crm_config.yaml
  • Cliente não recebendo - Verifique os endereços de e-mail dos contatos do cliente
  • PDF não anexado - Verifique se a geração do PDF foi bem-sucedida (tente baixar primeiro)

Anulando Faturas​

Clique no ícone de exclusão (🗑️) para anular uma fatura.

Requisitos:

  • A fatura deve estar Não Paga
  • Faturas pagas não podem ser anuladas (devem ser reembolsadas em vez disso)

Como Anular:

  1. Localize a fatura não paga na lista
  2. Clique no ícone de exclusão (🗑️)
  3. Confirme no modal:

Modal de Confirmação de Anulação de Fatura{.align-center width="600px"}

O que Acontece:

  • A fatura é marcada como void = true
  • Todas as transações são desvinculadas da fatura (campo invoice_id definido como nulo)
  • As transações tornam-se "não faturadas" novamente
  • As transações podem ser incluídas em uma nova fatura
  • A fatura aparece na lista com o prefixo "Anulado:" no título
  • Ações da fatura desativadas (sem download, pagamento ou e-mail)
  • Pode ser visualizada filtrando por faturas "Anuladas"

Notas Importantes:

  • Anular não é o mesmo que reembolsar
  • Anular = "Esta fatura nunca deveria ter existido" (erro de faturamento, duplicata)
  • Reembolsar = "Reverter uma fatura válida paga" (devolver dinheiro ao cliente)

Reembolsando Faturas​

Clique no ícone de reembolso (💸) para reembolsar uma fatura paga.

Requisitos:

  • A fatura deve estar Paga
  • A fatura deve ter sido paga via Stripe
  • A fatura deve ter uma payment_reference válida (ID da intenção de pagamento do Stripe)
  • Disponível apenas para usuários do staff (não para Autoatendimento)

Como Reembolsar:

  1. Localize a fatura paga do Stripe
  2. Clique no ícone de reembolso (💸)
  3. O modal de confirmação de reembolso é aberto:

Modal de Confirmação de Reembolso de Fatura{.align-center width="800px"}

  1. Clique em "Confirmar Reembolso"
  2. O sistema processa o reembolso do Stripe:
    • Chama a API do Stripe para reembolsar o pagamento
    • Cria uma transação de reembolso no Stripe
    • Atualiza a fatura com refund_reference
  3. O status da fatura muda para "Reembolsada"
  4. Notificação de sucesso exibida

O que Acontece Após o Reembolso:

  • A fatura permanece no sistema (não é anulada)
  • O status mostra "Reembolsada"
  • As transações permanecem vinculadas à fatura
  • O cliente recebe o reembolso no método de pagamento original (3-7 dias úteis)
  • O painel do Stripe mostra a transação de reembolso

Restrições de Reembolso:

  • Não é possível reembolsar faturas pagas em dinheiro, POS ou transferência bancária (reversão manual necessária)
  • Não é possível reembolsar parcialmente (apenas valor total da fatura)
  • Não é possível reembolsar duas vezes

Pesquisando e Filtrando Faturas​

Pesquisa​

Use a barra de pesquisa para encontrar faturas. Pesquisas abrangem:

  • ID da fatura
  • Título da fatura
  • Nome do cliente (apenas visualização em todo o sistema)

Filtros​

Aplique filtros para restringir a lista de faturas:

Filtros Disponíveis:

  • Status de Anulação - Todas, Anuladas, Não Anuladas
  • Status de Pagamento - Todas, Pagas, Não Pagas

Ações de Filtro:

  • Aplicar Filtros - Aplicar filtros selecionados à lista
  • Redefinir Filtros - Limpar todos os filtros e mostrar todas as faturas

Classificação​

Clique em qualquer cabeçalho de coluna para classificar:

  • ID - Classificar por ID da fatura (mais recente/mais antiga)
  • Título - Classificar alfabeticamente
  • Data de Vencimento - Classificar por data de vencimento
  • Criado - Classificar por data de criação
  • Valor - Classificar por custo de varejo (mais alto/mais baixo)
  • Status - Classificar por status de pagamento (pagas primeiro ou não pagas primeiro)

Clique novamente para inverter a direção da classificação (crescente ↔ decrescente).

Paginação​

Navegue por listas grandes de faturas com controles de página mostrando a página atual, total de páginas e seletor de itens por página (10, 25, 50 ou 100 itens).

Fluxos de Trabalho Comuns de Faturas​

Fluxo de Trabalho 1: Faturamento Mensal com Pré-visualização de Transação​

  1. O final do mês chega (por exemplo, 31 de janeiro)
  2. Navegue até Faturamento → Faturas
  3. Clique em "+ Gerar Fatura Proforma"
  4. Selecione o cliente (ou faça por cliente se faturando muitos clientes)
  5. Defina as datas:
    • Data de Início: 2025-01-01
    • Data de Término: 2025-01-31
    • Data de Vencimento: 2025-02-15 (15 dias a partir de agora)
    • Título: "Serviços de Janeiro de 2025" (opcional)
  6. A seção Pré-visualização de Transação aparece mostrando todas as transações não faturadas de janeiro
  7. Revise a pré-visualização:
    • Todas as transações estão incluídas por padrão
    • Verifique os totais: Subtotal, Imposto e Total da Fatura
    • Verifique se todas as cobranças estão corretas
  8. Clique em "Gerar Fatura" (o botão mostra a contagem de transações, por exemplo, "Gerar Fatura (15)")
  9. Fatura criada com todas as transações selecionadas
  10. Clique na linha da fatura para visualizar os detalhes e verificar
  11. Clique no botão "Enviar E-mail" no modal de detalhes ou no ícone de e-mail na tabela
  12. O cliente recebe o e-mail da fatura com PDF e link de pagamento

Fluxo de Trabalho 2: Faturamento Seletivo de Transações​

  1. O cliente tem vários serviços (Móvel + Internet) e cobranças diversas
  2. Deseja faturas separadas para cada serviço
  3. Gerar a primeira fatura (Serviços Móveis):
    • Clique em "+ Gerar Fatura Proforma"
    • Título: "Serviços Móveis - Janeiro de 2025"
    • Data de Início/Fim: 1-31 de janeiro
    • Data de Vencimento: 15 de fevereiro
    • Na pré-visualização da transação, exclua todas as transações não móveis:
      • Clique no botão X ao lado das transações de Internet
      • Clique no botão X ao lado das cobranças diversas
      • Apenas as transações de serviços móveis permanecem selecionadas
    • Verifique se os totais refletem apenas serviços móveis
    • Clique em "Gerar Fatura" (mostra a contagem de transações móveis)
  4. Gerar a segunda fatura (Serviços de Internet):
    • Clique em "+ Gerar Fatura Proforma" novamente
    • Título: "Serviços de Internet - Janeiro de 2025"
    • Data de Início/Fim: 1-31 de janeiro (mesmo período)
    • Na pré-visualização da transação:
      • Transações móveis já faturadas (não aparecem)
      • Exclua cobranças diversas usando o botão X
      • Apenas as transações de serviços de Internet permanecem
    • Clique em "Gerar Fatura"
  5. Gerar a terceira fatura (Cobranças Adicionais):
    • Clique em "+ Gerar Fatura Proforma" novamente
    • Título: "Cobranças Adicionais - Janeiro de 2025"
    • Apenas cobranças diversas não faturadas aparecem na pré-visualização
    • Clique em "Selecionar Tudo" para incluir todas
    • Clique em "Gerar Fatura"
  6. Envie todas as três faturas para o cliente

Fluxo de Trabalho 3: Excluindo Transações Disputadas ou Pendentes​

  1. O final do período de faturamento chega
  2. Navegue até a aba de Faturamento do cliente
  3. Clique em "+ Gerar Fatura Proforma"
  4. Defina as datas do período de faturamento
  5. A pré-visualização da transação mostra 20 transações
  6. O cliente disputou uma cobrança e outra está pendente de investigação
  7. Na pré-visualização da transação:
    • Localize a transação disputada (por exemplo, "cobrança de excesso de dados")
    • Clique no botão X para excluí-la
    • Localize a transação pendente (por exemplo, "taxa de instalação")
    • Clique no botão X para excluí-la
    • A contagem de transações é atualizada: "18 Transações selecionadas"
    • Os totais são recalculados automaticamente
  8. Revise os totais atualizados (exclui os valores disputados)
  9. Clique em "Gerar Fatura (18)"
  10. Fatura gerada com apenas transações aprovadas
  11. Transações disputadas/pendentes permanecem não faturadas para o próximo ciclo de faturamento

Fluxo de Trabalho 4: Revisão Rápida da Fatura e Ajuste​

  1. O funcionário gera a fatura mensal
  2. A pré-visualização da transação mostra um total inesperadamente alto
  3. Revise cada transação na pré-visualização:
    • Note uma cobrança duplicada pelo mesmo serviço
    • Clique em X para excluir a duplicata
    • Note uma transação de teste que não deveria ser cobrada
    • Clique em X para excluir a transação de teste
  4. Os totais são atualizados em tempo real
  5. Verifique se o novo total corresponde ao valor esperado
  6. Clique em "Gerar Fatura" com as transações corrigidas
  7. Volte e anule/exclua as transações excluídas, se necessário
  8. Envie a fatura para o cliente com confiança

Fluxo de Trabalho 5: Fatura de Instalação Única​

  1. O técnico de campo completa a instalação
  2. O funcionário adiciona a transação de instalação manualmente
  3. Navegue até a aba de Faturamento do cliente
  4. Clique em "+ Gerar Fatura Proforma"
  5. Defina as datas:
    • Data de Início: hoje
    • Data de Término: hoje
    • Data de Vencimento: hoje + 7 dias
    • Título: "Serviços de Instalação"
  6. A pré-visualização da transação mostra apenas as transações de hoje
  7. Verifique se a cobrança de instalação aparece
  8. Exclua quaisquer cobranças recorrentes usando o botão X (se presente)
  9. Clique em "Gerar Fatura"
  10. Envie para o cliente imediatamente
  11. O cliente paga online via Stripe

Fluxo de Trabalho 6: Revisando a Fatura Antes do Contato com o Cliente​

  1. O cliente liga com uma pergunta sobre faturamento
  2. O funcionário navega até a lista de faturas do cliente
  3. Clique na linha da fatura para abrir o modal de Detalhes da Fatura
  4. Revise as informações da fatura:
    • ID da fatura, datas, status
    • Todas as transações incluídas com descrições
    • Detalhamento do imposto por transação
    • Subtotal, Imposto e Totais
  5. Responda às perguntas do cliente com detalhes exatos
  6. Se o cliente solicitar o PDF, clique no botão "Baixar PDF" no modal
  7. Se o cliente solicitar o reenvio do e-mail, clique no botão "Enviar E-mail"
  8. Feche o modal quando terminar

Fluxo de Trabalho 7: Corrigindo Erro de Faturamento​

  1. O cliente relata uma cobrança incorreta
  2. O funcionário clica na linha da fatura para visualizar os detalhes
  3. Revê a lista de transações no modal de Detalhes da Fatura
  4. Identifica a transação incorreta
  5. A fatura está não paga, então pode ser anulada
  6. Clique no botão "Excluir" no rodapé do modal
  7. Confirme a anulação
  8. As transações tornam-se não faturadas novamente
  9. O funcionário modifica ou remove a transação incorreta da lista de transações
  10. Gere uma nova fatura com as transações corrigidas:
    • Use a pré-visualização da transação para excluir a transação corrigida, se necessário
    • Inclua apenas cobranças válidas
  11. Envie a fatura corrigida para o cliente

Fluxo de Trabalho 8: Processando Vários Pagamentos​

  1. O cliente traz dinheiro para pagar várias faturas
  2. Navegue até a aba de Faturamento do cliente
  3. Veja as faturas não pagas
  4. Clique na primeira linha da fatura para visualizar os detalhes
  5. Verifique o valor e as transações
  6. Clique no botão "Pagar Fatura" no rodapé do modal
  7. Selecione o método de pagamento "Dinheiro"
  8. Insira a referência: "Dinheiro pago 2025-01-15"
  9. Clique em "Pagar Fatura"
  10. O modal se fecha, a fatura é marcada como "Paga"
  11. Repita para as faturas restantes
  12. Todas as faturas agora marcadas como "Pagas"

Fluxo de Trabalho 9: Lidando com Solicitação de Reembolso​

  1. O cliente solicita reembolso por pagamento excessivo
  2. O funcionário verifica se a fatura foi paga via Stripe
  3. Navegue até a fatura na lista
  4. Clique na linha da fatura para visualizar os detalhes
  5. Verifique as informações de pagamento e o valor
  6. Clique no botão "Reembolsar" no rodapé do modal (apenas aparece para faturas do Stripe)
  7. Confirme o reembolso
  8. O sistema processa o reembolso do Stripe
  9. O status da fatura muda para "Reembolsada"
  10. O cliente recebe o reembolso em 3-7 dias úteis
  11. O funcionário acompanha o cliente para confirmar o recebimento

Resolvendo Problemas​

Não é possível gerar fatura - Nenhuma transação encontrada

  • Causa: Nenhuma transação não faturada no intervalo de datas especificado
  • Correção: Verifique a lista de transações, verifique se as transações existem e não estão faturadas. Ajuste o intervalo de datas ou remova o filtro.

Falha na geração do PDF da fatura

  • Causa: Erro de sintaxe no modelo, falha do WeasyPrint ou dados do cliente ausentes
  • Correção: Verifique o HTML do modelo de fatura em busca de erros, verifique se os campos de endereço do cliente estão preenchidos, revise os logs da API.

Pagamento falha com erro do Stripe

  • Causa: Cartão recusado, fundos insuficientes, cartão expirado ou problema na API do Stripe
  • Correção: Tente um método de pagamento diferente, verifique se o cartão é válido, verifique o painel do Stripe para a razão da recusa.

Não é possível anular a fatura

  • Causa: A fatura já foi paga
  • Correção: Faturas pagas não podem ser anuladas. Se o reembolso for necessário, use a função de reembolso para faturas do Stripe ou crie uma transação de crédito manualmente.

E-mail da fatura não enviado

  • Causa: Credenciais da API do Mailjet inválidas, cliente não tem contato de faturamento ou modelo de e-mail ausente
  • Correção: Verifique a configuração do Mailjet em crm_config.yaml, verifique os contatos do cliente, verifique se o modelo de e-mail da fatura existe.

Botão de reembolso não aparecendo

  • Causa: Fatura paga em dinheiro/POS/transferência bancária (não Stripe), ou fatura não paga
  • Correção: O botão de reembolso aparece apenas para pagamentos do Stripe. Para outros métodos de pagamento, crie uma transação de crédito manual.

Download do PDF mostra design antigo do modelo

  • Causa: PDF armazenado em cache antes da atualização do modelo
  • Correção: Limpe o cache do PDF da fatura: DELETE FROM Invoice_PDF_Cache WHERE invoice_id = X;

Cliente não pode pagar a fatura (sem métodos de pagamento)

  • Causa: Nenhum método de pagamento salvo no portal de Autoatendimento
  • Correção: O cliente deve adicionar um cartão de crédito na página Métodos de Pagamento antes de pagar faturas.

Múltiplas faturas geradas para o mesmo período

  • Causa: Funcionário gerou a fatura duas vezes ou os intervalos de datas se sobrepõem
  • Correção: Anule a fatura duplicada. Ajuste os intervalos de datas para evitar sobreposição. Use a pré-visualização da transação para garantir conjuntos de transações exclusivos.

Pré-visualização de transação mostra nenhuma transação

  • Causa: Todas as transações no intervalo de datas já estão faturadas ou não existem transações
  • Correção: Verifique se o intervalo de datas está correto. Verifique a lista de transações para confirmar se as transações existem. Filtre as faturas para ver qual fatura contém as transações.

Não é possível excluir transação da geração da fatura

  • Causa: Transação já faturada ou problema no navegador
  • Correção: Verifique se a transação aparece na pré-visualização com um sinal. Atualize a página e tente novamente. Limpe o cache do navegador se o problema persistir.

Total da fatura não corresponde ao valor esperado

  • Causa: Transações inesperadas incluídas, imposto não calculado ou transações excluídas ainda contadas
  • Correção: Revise a pré-visualização da transação com cuidado. Verifique o custo de varejo e o imposto de cada transação. Verifique se as transações excluídas estão esmaecidas. Verifique o distintivo de contagem de transações no botão Gerar Fatura.

Botão Gerar Fatura está desativado

  • Causa: Nenhuma transação selecionada ou intervalo de datas inválido
  • Correção: Certifique-se de que pelo menos uma transação esteja incluída (não excluída). Verifique se a Data de Início é anterior à Data de Término. Verifique se a Data de Vencimento está definida.

Modal de Detalhes da Fatura não abrindo

  • Causa: Erro de JavaScript ou página não totalmente carregada
  • Correção: Atualize a página. Verifique o console do navegador em busca de erros. Tente um navegador diferente. Verifique a conexão com a internet.

Imposto da transação não exibindo nos Detalhes da Fatura

  • Causa: Transação tem imposto de 0% ou tax_amount é nulo
  • Correção: Verifique se a transação tem tax_percentage definido. Verifique se tax_amount foi calculado quando a transação foi criada. Atualize a transação se necessário.

Botões de ação ausentes no modal de Detalhes da Fatura

  • Causa: A fatura foi anulada ou o usuário não tem permissões
  • Correção: Faturas anuladas mostram apenas o botão Baixar PDF. Verifique o status da fatura. Verifique o papel e as permissões do usuário.

Documentação Relacionada​

  • integrations_mailjet - Entrega de fatura por e-mail e modelos
  • administration_configuration - Configuração do modelo de fatura
  • payments_transaction - Criando transações que aparecem nas faturas
  • payments_process - Processando pagamentos de faturas
  • basics_payment - Métodos de pagamento e integração com Stripe