Pular para o conteúdo principal

Pagamentos, Faturas e Transações

Transações do Cliente

Qualquer coisa que custe dinheiro no sistema é registrada como uma transação sob o cliente.

Cada transação tem um valor monetário para custo de atacado e custo de varejo, e uma descrição do que a transação é.

As transações podem ser geradas automaticamente pelo sistema, por exemplo, quando um serviço é provisionado, uma transação é criada para o custo de instalação, e quando um serviço é faturado, uma transação é criada para o custo de varejo.

As transações também podem ser criadas manualmente, por exemplo, se um cliente receber um crédito, uma transação é criada para o valor do crédito, ou se uma taxa de instalação for cobrada, uma transação é criada para a taxa de instalação.

As transações são agrupadas para formar Faturas <payments_invoices>, que são enviadas ao cliente para pagamento.

Gerenciamento de Transações

Acessando Transações​

As transações 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 transações no primeiro cartão

Visualização em Todo o Sistema:

  1. Navegue até Faturamento → Transações (no menu principal)
  2. Veja todas as transações de todos os clientes

Widgets de Estatísticas de Transações​

No topo da página de transações, quatro cartões de estatísticas exibem resumos financeiros:

Estatísticas de Transação e Lista

Descrições dos Widgets:

  • Total de Transações - Soma de todos os custos de varejo das transações (todos os tempos)
  • Total de Transações Não Faturadas - Soma de transações ainda não incluídas em uma fatura
  • Total de Transações Este Mês - Soma de transações criadas neste mês calendário
  • Total de Transações Mês Passado - Soma de transações criadas no mês calendário passado

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)

Lista de Transações​

A tabela de transações exibe todas as transações com as seguintes colunas:

Descrições das Colunas:

  • ID - ID único da transação
  • Data - Data de criação da transação
  • Título - Nome curto da transação
  • Descrição - Descrição detalhada do que a transação é
  • Valor - Custo de varejo (positivo para cobranças, negativo para créditos)
  • Fatura - ID da fatura se a transação foi faturada (link clicável)
  • Status - Marca de verificação se faturada, traço se ainda não faturada

Ações Por Linha:

Cada linha tem um menu de ações (⋮) com opções:

  • Ver Detalhes - Abre o modal de detalhes da transação
  • Baixar PDF da Fatura - Baixar PDF (somente se faturada)
  • Anular Transação - Marcar transação como anulada (somente se não faturada)

Tipos de Transações​

As transações se enquadram em duas categorias principais:

Transações de Débito (Cobranças)​

Valores positivos que aumentam o saldo devedor do cliente:

  • Taxas de Configuração de Serviço - Cobranças únicas quando o serviço é provisionado
  • Taxas Mensais de Serviço - Cobranças recorrentes por serviços
  • Taxas de Instalação - Cobranças por visitas de técnicos de campo
  • Cobranças de Equipamentos - Cobranças por modems, roteadores, cartões SIM
  • Taxas de Pagamento Atrasado - Penalidades por faturas em atraso
  • Cobranças Manuais - Cobranças personalizadas adicionadas pela equipe

Transações de Crédito (Pagamentos/Reembolsos)​

Valores negativos que diminuem o saldo devedor do cliente:

  • Pagamentos em Dinheiro - Cliente pagou em dinheiro
  • Pagamentos com Cartão - Cliente pagou com cartão de crédito/débito
  • Pagamentos por Transferência Bancária - Cliente pagou via transferência bancária
  • Créditos em Conta - Créditos de boa vontade, compensação
  • Reembolsos - Dinheiro devolvido ao cliente
  • Descontos - Descontos promocionais ou de fidelidade

Adicionando uma Transação Manualmente​

Clique em "+ Adicionar Transação" para abrir o modal de adicionar transação.

Transação de Débito (Cobrança):

Adicionar Modal de Transação de Débito

Transação de Crédito (Pagamento/Reembolso):

Adicionar Modal de Transação de Crédito

Descrições dos Campos:

  • Tipo de Transação - Selecione Débito (cobrança) ou Crédito (pagamento/reembolso)
  • Tipo de Crédito - Se Crédito selecionado, escolha o método de pagamento (Dinheiro, Cartão, Transferência Bancária)
  • Título - Nome curto para a transação (obrigatório)
  • Descrição - Explicação detalhada (opcional)
  • Custo de Varejo - Valor que o cliente paga (obrigatório, número positivo)
  • Custo de Atacado - Seu custo (opcional, para rastreamento de margem)
  • Porcentagem de Imposto - Taxa de imposto aplicada a esta transação (opcional, padrão para imposto do produto ou 0%)
  • Serviço - Vincular transação a um serviço específico (opcional)
  • Site - Vincular transação a um site específico (opcional)
  • Data da Transação - Data da transação (padrão para hoje)

Validação:

  • Título e custo de varejo são obrigatórios
  • O custo de varejo deve ser um número positivo
  • Se o tipo de Crédito for selecionado, um tipo de crédito deve ser escolhido

O Que Acontece:

  1. Transação criada no banco de dados
  2. Aparece na lista de transações do cliente
  3. Incluída na contagem de "Transações Não Faturadas"
  4. Disponível para inclusão na próxima geração de fatura
  5. Entrada de log de atividade criada

Pesquisando e Filtrando Transações​

Pesquisa​

Use a barra de pesquisa para encontrar transações. Pesquisas em:

  • ID da Transação
  • Título
  • Descrição
  • ID da Fatura

Filtros​

Aplique filtros para restringir a lista de transações:

Filtros Disponíveis:

  • Status de Anulação - Todos, Anulada, Não Anulada
  • Status da Fatura - Todos, Faturada, Não Faturada

Ações de Filtro:

  • Aplicar Filtros - Aplicar filtros selecionados à lista
  • Redefinir Filtros - Limpar todos os filtros e mostrar todas as transações

Ordenação​

Clique em qualquer cabeçalho de coluna para ordenar:

  • ID - Ordenar por ID da transação (mais recente/mais antiga)
  • Data - Ordenar por data da transação
  • Título - Ordenar alfabeticamente
  • Valor - Ordenar por custo de varejo (mais alto/mais baixo)
  • Fatura - Ordenar por ID da fatura

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

Anulando Transações​

Transações adicionadas por erro podem ser anuladas (marcadas como excluídas).

Requisitos:

  • A transação NÃO deve estar faturada
  • Uma vez faturadas, as transações não podem ser anuladas (devem ser reembolsadas em vez disso)

Como Anular:

  1. Localize a transação na lista
  2. Clique no menu de ações (⋮)
  3. Selecione "Anular Transação"
  4. Confirme no modal

Modal de Confirmação de Anulação de Transação

O Que Acontece:

  • Transação marcada como void = true
  • Não aparece mais na lista padrão de transações
  • Excluída da geração de faturas
  • Pode ser visualizada filtrando por transações "Anuladas"
  • Deduza do total de "Transações Não Faturadas"

Nota: Anular NÃO é o mesmo que reembolsar. Anular significa "esta transação nunca deveria ter existido." Reembolsar significa "reverter uma transação válida."

Imposto sobre Transações​

As transações podem incluir imposto, que é calculado automaticamente com base na configuração de imposto do produto ou especificado manualmente por transação.

Exibição de Imposto de Transação

Comportamento do Imposto:

  • Transações de Débito (Cobranças) - O imposto é aplicado às cobranças com base em:
    • Porcentagem de Imposto do Produto - Se a transação estiver vinculada a um produto, a porcentagem de imposto do produto é aplicada automaticamente
    • Substituição Manual - A equipe pode substituir a porcentagem de imposto ao criar uma transação
    • Valor do Imposto - Calculado como: retail_cost × (tax_percentage / 100)
    • Formato de Exibição - Exibido como: $10.00 (10%) nas listas de transações
  • Transações de Crédito (Pagamentos/Reembolsos) - Nenhum imposto é aplicado a créditos
    • O campo de porcentagem de imposto é oculto para transações de crédito
    • O imposto é automaticamente definido como 0% para todos os pagamentos e reembolsos
    • Créditos reduzem o saldo devedor do cliente sem implicações fiscais

Exemplo de Cálculo de Imposto:

  • Produto: Plano Móvel com 10% de imposto, $50.00 custo de varejo
  • Cálculo Automático de Imposto: $50.00 × 0.10 = $5.00
  • Exibição: $5.00 (10%)

Imposto Zero (NIL/Isento):

  • Produtos podem ser isentos de imposto definindo a porcentagem de imposto como 0
  • O imposto padrão é 0% se não especificado
  • Transações isentas de imposto mostram "-" na coluna de Imposto

Transação de Imposto Zero

Visualização de Detalhes da Transação​

Clique em uma transação para ver todos os detalhes:

Transações Faturadas vs Não Faturadas​

Transações Não Faturadas:

  • Ainda não incluídas em nenhuma fatura
  • Disponíveis para a próxima geração de fatura
  • Podem ser anuladas
  • Contam para o total de "Transações Não Faturadas"
  • Status mostra traço (-)

Transações Faturadas:

  • Incluídas em uma fatura
  • Não podem ser anuladas (devem ser reembolsadas se necessário)
  • ID da fatura clicável (link para detalhes da fatura)
  • Status mostra marca de verificação (✓)
  • Não podem ser modificadas

Geração de Fatura:

Quando você gera uma fatura para um cliente:

  1. O sistema encontra todas as transações n��o faturadas para aquele cliente
  2. Opcionalmente, filtre por intervalo de datas
  3. Transações incluídas na nova fatura
  4. Campo invoice_id da transação populado
  5. Transação agora marcada como "faturada"

Veja payments_invoices para detalhes sobre geração de faturas.

Fluxos de Trabalho Comuns​

Fluxo de Trabalho 1: Crédito Manual por Interrupção de Serviço​

  1. Cliente liga: "O serviço ficou fora do ar por 2 dias"
  2. A equipe decide creditar £10
  3. Navegue até a aba Faturamento do cliente
  4. Clique em "+ Adicionar Transação"
  5. Selecione o tipo de transação Crédito
  6. Selecione o tipo de crédito Pagamento em Dinheiro
  7. Insira o título: "Crédito por Interrupção de Serviço"
  8. Insira a descrição: "Compensação por interrupção de 2 dias 8-9 Jan"
  9. Insira o custo de varejo: 10.00
  10. Selecione o serviço afetado no dropdown
  11. Clique em "Adicionar Transação"
  12. A transação aparece com valor de -£10.00
  13. Será incluída na próxima fatura como crédito

Fluxo de Trabalho 2: Taxa de Instalação Manual​

  1. O técnico de campo instala o serviço
  2. A equipe precisa cobrar £75 de taxa de instalação
  3. Navegue até a aba Faturamento do cliente
  4. Clique em "+ Adicionar Transação"
  5. Selecione o tipo de transação Débito
  6. Insira o título: "Taxa de Instalação"
  7. Insira a descrição: "Visita do técnico de campo para instalação de fibra"
  8. Insira o custo de varejo: 75.00
  9. Insira o custo de atacado: 45.00 (opcional, para rastreamento de margem)
  10. Selecione o serviço instalado
  11. Selecione o site onde foi instalado
  12. Clique em "Adicionar Transação"
  13. A transação aparece na lista de não faturadas
  14. Será incluída na próxima fatura

Fluxo de Trabalho 3: Anulando Transação Duplicada​

  1. A equipe nota uma transação duplicada
  2. Verifique se a transação NÃO foi faturada
  3. Clique no menu de ações (⋮) na transação duplicada
  4. Selecione "Anular Transação"
  5. Confirme no modal
  6. Transação removida da lista
  7. Total não faturado diminui de acordo

Fluxo de Trabalho 4: Encontrando Transações para Fatura​

  1. Necessidade de gerar fatura mensal
  2. Clique no filtro Fatura: "Não Faturada"
  3. Clique em Aplicar Filtros
  4. Veja todas as transações não faturadas
  5. Anote o valor total dos widgets
  6. Navegue para gerar fatura
  7. Selecione intervalo de datas (por exemplo, 1-31 Jan)
  8. Transações no intervalo incluídas na fatura

Solução de Problemas​

Não é possível anular a transação

  • Causa: Transação já faturada
  • Correção: A transação faz parte do histórico de faturas. Se o reembolso for necessário, crie uma transação de Crédito em vez disso.

Transações duplicadas aparecendo

  • Causa: Serviço cobrado várias vezes ou erro de provisionamento
  • Correção: Anule a(s) transação(ões) duplicadas se não faturadas. Se faturadas, emita crédito.

Transação não aparece na lista

  • Causa: Filtros aplicados ou transação anulada
  • Correção: Clique em "Redefinir Filtros" para mostrar todas as transações. Para ver transações anuladas, filtre por "Anular: Anulada".

Total não faturado não corresponde ao esperado

  • Causa: Algumas transações já faturadas ou transações anuladas excluídas
  • Correção: Aplique o filtro "Fatura: Não Faturada" para ver apenas as não faturadas. Verifique transações anuladas separadamente.

Não é possível adicionar transação (campo cliente desativado)

  • Causa: Visualizando a página de transações específicas do cliente
  • Correção: O cliente está pré-selecionado. Se você precisar adicionar uma transação para um cliente diferente, vá para a página de Transações em todo o sistema.

Documentação Relacionada​

  • payments_invoices - Geração e gerenciamento de faturas
  • payments_process - Processamento de pagamentos contra faturas
  • basics_payment - Visão geral dos métodos de pagamento
  • csa_activity_log - Visualizando o histórico de transações no log de atividades

Faturas do Cliente

Transações </payments_transaction> 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 é faturado, 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 cobrança única.

As faturas dos clientes são totalmente modeladas com Mailjet <integrations_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 PDF.

Log de Atividades

Personalizando Modelos de Fatura​

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 - Porcentagem de imposto aplicada (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 à sua marca:

Áreas de Personalização Chave:

  1. Logotipo da Empresa e Branding

    <!-- Substitua pela URL do seu logotipo -->
    ![Sua Empresa](https://yourcompany.com/logo.png)

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

  2. Esquema de Cores

    <style>
        /* Cor da marca principal */
        .navbar {
            background: linear-gradient(to bottom right, #sua-cor-1, #sua-cor-2);
        }

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

        /* Botões e links */
        .btn-primary {
            background-color: #sua-cor-da-marca;
        }
    </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/ID Fiscal: 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 pagamento atrasado: 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 Fatura

  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 você mesmo para testar a entrega do 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 em seu campo tax_percentage, que padrão é a tax_percentage do produto ou 0% se não especificado.

QR Code para Pagamento:

Gere um QR code para pagamento móvel:

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

Melhores Práticas de Estilo para PDF​

OmniCRM usa 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 Fonte:

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

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

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

Testando Modelos de Fatura​

Checklist de Teste:

  1. Inspeção Visual:
    • Logotipo é exibido corretamente
    • Cores correspondem às diretrizes da marca
    • Texto é legível (não muito pequeno)
    • Tabelas estão alinhadas corretamente
    • Todas as seções estão presentes
  2. Precisão dos Dados:
    • Detalhes do cliente estão corretos
    • Valores das transações somam corretamente
    • Datas estão formatadas corretamente
    • Todas as variáveis estão substituindo corretamente
  3. Qualidade do PDF:
    • Tamanho do arquivo razoável (<5MB)
    • Imagens nítidas e claras
    • Sem corte ou transbordamento de texto
    • Quebras de página em locais apropriados
  4. Faturas de Múltiplas Páginas:
    • Cabeçalhos se repetem em cada página
    • Números de página são exibidos
    • Listas longas de transações paginam corretamente
  5. Entrega de E-mail:
    • PDF anexa ao e-mail
    • Tamanho do arquivo 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 aparecem:

  • Causa: URLs relativas ou recursos externos bloqueados
  • Correção: Use URLs absolutas HTTPS, 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 de 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 de 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á 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. Invalidando o 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 - 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​

No topo da página de faturas, quatro cartões de estatísticas exibem resumos financeiros.

Estatísticas de Fatura e Lista

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 mudança 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 mudança

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 paga)
  • 💰 (Pagar) - Pagar fatura online (somente se não paga)
  • ✉️ (E-mail) - Enviar e-mail da fatura para o cliente
  • 💸 (Reembolsar) - Reembolsar pagamento Stripe (somente para faturas Stripe pagas)

Gerando uma Fatura​

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

Modal de Geração de Fatura com Pré-visualização de Transação

Descrições dos Campos:

  • Pesquisar Clientes - Selecionar cliente (apenas mostrado na visualização em todo o sistema, pré-preenchido na visualização do cliente)
  • Título - Título/nome da fatura (opcional, padrão para "Fatura para [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ções:

  • ✓ (Sinal Verde) - Clique para excluir uma transação da fatura
  • × (Sinal Vermelho) - Clique para incluir uma transação anteriormente 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 atualizam conforme 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 das transações 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 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 (invoice_id campo 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 desse 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 tanto a data de início quanto a data de término para o mesmo dia, a pré-visualização mostra apenas transações dessa data. Exclua quaisquer cobranças não relevantes para esta fatura específica.

Visualizando Detalhes da Fatura​

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

Visualização de Detalhes da Fatura

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 do imposto e porcentagem (formatado como $10.00 (10%))
    • Transações isentas de imposto mostram "-" na coluna de Imposto
  • Resumo de 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 como 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 (faturas não pagas, não anuladas apenas)
    • Reembolsar - Reembolsar pagamento Stripe (apenas faturas Stripe pagas)
    • Excluir - Anular fatura (faturas não pagas, não anuladas apenas)

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 na primeira vez)
  3. O navegador solicita salvar o arquivo: Invoice_01234.pdf
  4. O PDF abre 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
  • Invalidando o Cache - Cache limpo se a fatura for modificada ou o modelo for atualizado

Solução de Problemas para Questões de Download:

  • O indicador de carregamento nunca para - Verifique o console do navegador, a API pode estar fora do ar
  • PDF em branco ou corrompido - Verifique o modelo de fatura para 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 de Fatura

Processo de Pagamento:

  1. Clique no ícone de pagamento na fatura não paga
  2. O modal de pagamento se abre 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 (somente para a equipe)
    • Reembolso - Aplicar reembolso como pagamento (somente para a equipe)
    • Transação POS - Terminal de ponto de venda (somente para a equipe)
    • Transferência Bancária - Transferência bancária manual (somente para a equipe)
  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 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 da Equipe:

: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 existirem métodos de pagamento
  • Link para adicionar método de pagamento fornecido

Portal da Equipe (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 que possa pagar faturas.

Aviso de Método de Pagamento Ausente

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 <integrations_mailjet> usando o modelo api_crmCommunicationCustomerInvoice
  4. O e-mail inclui:
    • PDF da fatura como anexo
    • Nome do cliente
    • ID 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 para todos os contatos do cliente com tipo "faturamento" ou 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

Solução de Problemas para Questões de E-mail:

  • E-mail não enviado - Verifique as credenciais da API 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

O Que Acontece:

  • Fatura marcada como void = true
  • Todas as transações desvinculadas da fatura (invoice_id definido como nulo)
  • Transações tornam-se "não faturadas" novamente
  • Transações podem ser incluídas em nova fatura
  • Fatura aparece na lista com prefixo "Anulada:" 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, duplicado)
  • Reembolsar = "Reverter uma fatura paga válida" (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 um payment_reference válido (ID de intenção de pagamento Stripe)
  • Disponível apenas para usuários da equipe (n��o para Autoatendimento)

Como Reembolsar:

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

Modal de Confirmação de Reembolso de Fatura

  1. Clique em "Confirmar Reembolso"
  2. O sistema processa o reembolso da Stripe:
    • Chama a API da Stripe para reembolsar o pagamento
    • Cria uma transação de reembolso na 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 da 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 em:

  • 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 - Todos, Anulada, Não Anulada
  • Status de Pagamento - Todos, Pago, Não Pago

Ações de Filtro:

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

Ordenação​

Clique em qualquer cabeçalho de coluna para ordenar:

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

Clique novamente para inverter a direção da ordenaçã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 ver 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: Jan 1-31
    • Data de Vencimento: Feb 15
    • Na pré-visualização de transações, 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ço móvel 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: Jan 1-31 (mesmo período)
    • Na pré-visualização de transações:
      • Transações móveis já faturadas (não aparecem)
      • Exclua cobranças diversas usando o botão X
      • Apenas as transações de serviço 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 Faturamento do cliente
  3. Clique em "+ Gerar Fatura Proforma"
  4. Defina as datas do período de faturamento
  5. A pré-visualização de transações mostra 20 transações
  6. O cliente disputou uma cobrança e outra está pendente de investigação
  7. Na pré-visualização de transações:
    • Localize a transação disputada (por exemplo, "Cobrança por 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 atualiza: "18 Transações selecionadas"
    • Os totais recalculam automaticamente
  8. Revise os totais atualizados (exclui 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. A equipe gera a fatura mensal
  2. A pré-visualização de transa��ões mostra um total inesperadamente alto
  3. Revise cada transação na pré-visualização:
    • Note a cobrança duplicada pelo mesmo serviço
    • Clique em X para excluir a duplicata
    • Note a transação de teste que não deveria ser cobrada
    • Clique em X para excluir a transação de teste
  4. Os totais atualizam 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. A equipe adiciona a transação de instalação manualmente
  3. Navegue até a aba 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 de transações 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 de faturamento
  2. A equipe 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 Valores 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 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. A equipe clica na linha da fatura para ver 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. A equipe 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 de transações 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 Múltiplos Pagamentos​

  1. O cliente traz dinheiro para pagar várias faturas
  2. Navegue até a aba Faturamento do cliente
  3. Veja as faturas não pagas
  4. Clique na primeira linha da fatura para ver 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 em 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 estão marcadas como "Pagas"

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

  1. O cliente solicita reembolso por pagamento em excesso
  2. A equipe verifica se a fatura foi paga via Stripe
  3. Navegue até a fatura na lista
  4. Clique na linha da fatura para ver 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 Stripe)
  7. Confirme o reembolso
  8. O sistema processa o reembolso da Stripe
  9. O status da fatura muda para "Reembolsada"
  10. O cliente recebe o reembolso em 3-7 dias úteis
  11. A equipe acompanha com o cliente para confirmar o recebimento

Solução de 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 já faturadas. Ajuste o intervalo de datas ou remova o filtro.

Falha na geração de 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 da Stripe

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

Não é possível anular a fatura

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

E-mail da fatura não enviado

  • Causa: Credenciais da API Mailjet inválidas, cliente sem 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 Stripe. Para outros métodos de pagamento, crie uma transação de crédito manual.

Download de PDF mostra design antigo do modelo

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

Cliente não pode pagar 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: A equipe 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 de transações para garantir conjuntos de transações exclusivos.

Pré-visualização de transações não mostra transações

  • 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 de fatura

  • Causa: Transação já faturada ou problema no navegador
  • Correção: Verifique se a transação aparece na pré-visualização com marca de verificação. 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 de transações 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 exibido 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 definida. 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 está 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 e-mail de fatura e modelos
  • administration_configuration - Configuração do modelo de fatura
  • payments_transaction - Criando transações que aparecem nas faturas
  • payments_process - Processando pagamentos com métodos de pagamento armazenados
  • payment_system_guide - Referência da API de pagamento e configuração de fornecedores

Gerenciamento de Métodos de Pagamento

O sistema de Métodos de Pagamento do OmniCRM permite que clientes e funcionários gerenciem cartões de pagamento de forma segura usando processamento de pagamento de múltiplos fornecedores (Stripe, PayPal, etc.). Os métodos de pagamento permitem faturamento automático para serviços, pagamentos únicos e cobranças recorrentes sem armazenar dados sensíveis do cartão no OmniCRM.

Veja também: Guia do Sistema de Pagamento <payment_system_guide>, Visão Geral de Faturamento <billing_overview>, Processamento de Pagamento <payments_process>, Faturas <payments_invoices>.

Visão Geral​

O sistema de métodos de pagamento fornece:

  • Armazenamento Seguro de Cartões - Cartões tokenizados por fornecedores de pagamento (Stripe, PayPal), nunca armazenados no OmniCRM
  • Suporte a Múltiplos Fornecedores - Métodos de pagamento Stripe e PayPal suportados
  • Múltiplos Cartões - Clientes podem armazenar múltiplos métodos de pagamento
  • Seleção Padrão - Designar método de pagamento preferido para cobranças automáticas
  • Rastreamento de Expiração - Monitorar e atualizar cartões que estão expirando
  • Autoatendimento - Clientes podem gerenciar seus próprios cartões via Portal de Autoatendimento <self_care_portal>
  • Gerenciamento pela Equipe - A equipe de suporte pode adicionar/remover cartões em nome dos clientes

Métodos de Pagamento Suportados:

  • Cartões de Crédito (Visa, Mastercard, American Express, Discover)
  • Cartões de Débito
  • Cartões Pré-pagos (se suportados pela rede de cartões)

Não Armazenados no OmniCRM:

Os detalhes do cartão são tokenizados pelos fornecedores de pagamento e armazenados de forma segura. O OmniCRM armazena apenas:

  • Fornecedor de pagamento (stripe, paypal)
  • Marca do cartão (Visa, Mastercard, etc.)
  • Últimos 4 dígitos
  • Mês/Ano de expiração
  • Nome/nome de apelido do titular do cartão
  • Token de método de pagamento específico do fornecedor

Acessando Métodos de Pagamento​

Da Página do Cliente:

  1. Navegue até Clientes → [Selecionar Cliente]
  2. Clique na aba Faturamento
  3. Role até a seção Métodos de Pagamento

Ou diretamente:

Do Painel de Cartões que Estão Expirando:

Veja todos os clientes com cartões que estão expirando:

Isso mostra uma lista em todo o sistema de cartões que expiram dentro dos próximos 60 dias.

Lista de Métodos de Pagamento​

A tabela de métodos de pagamento exibe todos os cartões armazenados para um cliente:

Lista de Métodos de Pagamento

Descrições das Colunas:

  • Apelido - Nome amigável para o cartão (por exemplo, "Cartão Pessoal", "Visa do Trabalho")
  • Emissor - Marca do cartão e últimos 4 dígitos
  • Expiração - Mês/ano de expiração (formato MM/AAAA)
  • Adicionado - Data em que o cartão foi adicionado à conta
  • Padrão - Marca de verificação indica o método de pagamento padrão para cobranças automáticas

Ações Por Cartão:

Cada linha tem um menu de ações (⋮) com opções:

  • Definir como Padrão - Tornar este o método de pagamento padrão
  • Excluir - Remover cartão da conta

Adicionando um Método de Pagamento​

Clique em "Adicionar Método de Pagamento" para abrir o modal de pagamento seguro.

Passo 1: Inserir Detalhes do Cartão​

O formulário de pagamento seguro aparece (alimentado por Stripe Elements ou PayPal SDK):

Modal de Adicionar Método de Pagamento

Campos Obrigatórios:

  • Informações do Cartão - Número do cartão, expiração, CVC (validado pela Stripe)
  • Nome do Titular do Cartão - Nome no cartão
  • País/Região - País de cobrança

Campos Opcionais:

  • Apelido do Cartão - Rótulo amigável para distinguir entre cartões

Segurança:

  • Detalhes do cartão inseridos diretamente em iframe seguro hospedado pelo fornecedor (Stripe Elements / PayPal SDK)
  • O OmniCRM nunca vê ou armazena números de cartão completos
  • Conformidade com PCI DSS tratada pelo fornecedor de pagamento
  • Validação em tempo real evita números de cartão inválidos

Passo 2: Enviar e Tokenizar​

Quando você clicar em "Adicionar Método de Pagamento":

  1. Validação do Lado do Cliente:
    • O fornecedor de pagamento valida o formato do