Pular para o conteúdo principal

Pagamentos, Faturas e Transações

Transações de Clientes

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 configuraçã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, 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 e Lista de Transações

Descrições dos Widgets:

  • Total de Transações - Soma de todos os custos de varejo das transações (todas as vezes)
  • 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 a 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 Equipamento - 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 de 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):

Modal de Adicionar Transação de Débito

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

Modal de Adicionar 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)
  • Percentual de Imposto - Taxa de imposto aplicada a esta transação (opcional, padrão para imposto do produto ou 0%)
  • Serviço - Vincular a transação a um serviço específico (opcional)
  • Site - Vincular a 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 faturas
  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, Anulados, Não Anulados
  • Status da Fatura - Todos, Faturados, Não Faturados

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 novo/mais antigo)
  • 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 deletadas).

Requisitos:

  • A transação NÃO deve ser 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"

Transações vinculadas a carteira (wallet_ledger_id definido):

  • O saldo da carteira é revertido antes da anulação (débito para desfazer um crédito, crédito para desfazer um débito)
  • Cartão de recarga de fundos (payment_type=wallet_topup_card): carteira debitada e cartão reembolsado
  • Recarga em dinheiro / pagamento de fatura da carteira / outras linhas de carteira: carteira ajustada apenas; sem reembolso de cartão
  • Carteira insuficiente: a anulação falha se os fundos recarregados já foram gastos (a transação permanece ativa)

Cobranças de serviço / provisionamento de captura híbrida geralmente não têm wallet_ledger_id na linha de faturamento. Anular essas linhas apenas define void=true hoje; crédito total da carteira para anulações de serviço está planejado na branch de documentos financeiros.

API: DELETE /crm/transaction/transaction_id/{transaction_id}. Veja guia_do_sistema_de_pagamento.md: Anular Transação.

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 da Transação

Comportamento do Imposto:

  • Transações de Débito (Cobranças) - O imposto é aplicado às cobranças com base em:
    • Percentual de Imposto do Produto - Se a transação estiver vinculada a um produto, o percentual de imposto do produto é aplicado automaticamente
    • Substituição Manual - A equipe pode substituir o percentual 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 percentual 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 de imposto

Exemplo de Cálculo de Imposto:

  • Produto: Plano Móvel com 10% de imposto, $50.00 de 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 o percentual 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 com 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 faturas
  • 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 filtra 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 da 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. 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 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 em Filtro de 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

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

  • Causa: Falha na reversão de recarga de carteira (saldo insuficiente na carteira)

  • Solução: O cliente já gastou os fundos recarregados. Use um débito/ajuste manual da carteira ou fluxos de reversão de documentos financeiros; não é possível anular a linha de recarga até que a carteira cubra o valor.

  • Causa: Falha no reembolso do cartão (somente recarga de fundos)

  • Solução: A reversão da carteira é revertida automaticamente. Resolva o problema do fornecedor de pagamento e tente anular novamente.

Transações duplicadas aparecendo

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

Transação não aparece na lista

  • Causa: Filtros aplicados ou transação anulada
  • Soluçã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
  • Soluçã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 de cliente desativado)

  • Causa: Visualizando a página de transações específicas do cliente
  • Soluçã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 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 é 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 taxa única.

As faturas de 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.

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:

  • sample_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: 'sample_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 da 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 nos 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 sample_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 primária da marca */
        .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. Rodapé de Informações da Empresa

    <footer>
        <p>Nome da Sua Empresa</p>
        <p>123 Rua de Negócios, 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 de impostos -->
<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">
    ![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 Estilização de 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;
}

Estilização Específica 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:
    • Tamanho do arquivo razoável (&lt;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 por Email:
    • PDF anexado ao email
    • 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
  • Solução: Verifique a ortografia exatamente (sensível a maiúsculas e minúsculas), verifique se os dados existem no banco de dados

Estilização do PDF quebrada:

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

Imagens não exibidas:

  • Causa: URLs relativas ou recursos externos bloqueados
  • Solução: Use URLs HTTPS absolutas, garanta que as imagens sejam acessíveis publicamente

Tabelas transbordando a página:

  • Causa: Larguras de coluna fixas muito largas
  • Solução: Use larguras em porcentagem, table-layout: fixed

Fontes não renderizando:

  • Causa: Fonte não incorporada ou indisponível
  • Soluçã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
  • Soluçã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 email), 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á 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/falha 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 (a partir do menu principal)
  2. Veja todas as faturas de todos os clientes

Widgets de Estatísticas de Fatura​

Na parte superior 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 (de 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 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 Devolvido
  • Ações - Ações disponíveis (variável por 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)
  • ✉️ (Email) - Enviar email 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 Geração de Fatura com Pré-visualização de Transação

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 é "Fatura para [Período]")
  • Data de Início - Início do período de faturamento (padrão é 14 dias atrás)
  • Data de Término - Fim do período de faturamento (padrão é hoje)
  • Data de Vencimento - Prazo de pagamento (padrão é 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:

  • ✓ (Mais Verde) - Clique para excluir uma transação da fatura
  • × (X Vermelho) - Clique para incluir uma transação previamente excluída
  • Selecionar Todas - Incluir todas as transações exibidas
  • Limpar Todas - 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 de 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 o 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 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 visualizar os detalhes completos 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 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 como na tabela:
    • Baixar PDF - Baixar PDF da fatura (sempre disponível)
    • Enviar Email - 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. Um 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 é 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

Solução de Problemas de Problemas 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 (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

Autoatendimento vs Pagamento de Funcionários:

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

  • Apenas pagamento via Stripe disponível
  • Deve ter um método de pagamento salvo
  • Aviso exibido se não existirem métodos de pagamento
  • 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

Enviando Faturas por Email​

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

O Que Acontece:

  1. Clique no ícone de email ao lado da fatura
  2. O sistema recupera o PDF da fatura do cache (ou gera se não estiver em cache)
  3. Envia email via Mailjet usando o modelo api_crmCommunicationCustomerInvoice
  4. O email 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: "Email da fatura enviado com sucesso"

Destinatários do Email:

Email enviado a todos os contatos do cliente com tipo "faturamento" ou contato principal se nenhum contato de faturamento existir.

Variáveis do Modelo de Email:

  • {{ 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 de Problemas de Email:

  • Email não enviado - Verifique as credenciais da API do Mailjet em crm_config.yaml
  • Cliente não recebendo - Verifique os endereços de email 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 excluir (🗑️) 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 excluir (🗑️)
  3. Confirme no modal:

Modal de Confirmação de Anulação de Fatura

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 se tornam "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 email)
  • 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 se abre:

Modal de Confirmação de Reembolso de Fatura

  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 para o 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 via dinheiro, POS ou transferência bancária (reversão manual necessária)
  • Não é possível reembolso parcial (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. Pesquisa 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, Anulado, Não Anulado
  • 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

Classificação​

Clique em qualquer cabeçalho de coluna para classificar:

  • ID - Classificar por ID da fatura (mais novo/mais antigo)
  • 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 (pago primeiro ou não pago primeiro)

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

Paginação​

Navegue por grandes listas 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 Fatura​

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 detalhes e verificar
  11. Clique no botão "Enviar Email" no modal de detalhes ou no ícone de email na tabela
  12. O cliente recebe o email da fatura com PDF e link para pagamento

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

  1. O cliente possui 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"
    • Início/Fim: 1-31 de janeiro
    • Data de Vencimento: 15 de fevereiro
    • Na pré-visualização da transação, excluir 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 os 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"
    • 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)
      • Excluir 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 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 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 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 da transação 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 uma transação de teste que não deve ser faturada
    • 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 conclui 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 Fim: 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. 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 de impostos por transação
    • Subtotal, Imposto e Total
  5. Responda às perguntas do cliente com detalhes exatos
  6. Se o cliente solicitar PDF, clique no botão "Baixar PDF" no modal
  7. Se o cliente solicitar reenvio de 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 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 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 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: Tratando 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 do Stripe
  9. O status da fatura muda para "Reembolsada"
  10. O cliente recebe o reembolso em 3-7 dias úteis
  11. A equipe acompanha o cliente para confirmar o recebimento

Resoluçã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
  • Solução: Verifique a lista de transações, confirme 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 do PDF da fatura

  • Causa: Erro de sintaxe no template, falha do WeasyPrint ou dados do cliente ausentes
  • Solução: Verifique o HTML do template da fatura em busca de erros, confirme 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
  • Solução: Tente um método de pagamento diferente, verifique se o cartão é válido, consulte o painel do Stripe para saber o motivo da recusa.

Não é possível anular a fatura

  • Causa: Fatura já paga
  • Soluçã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 do Mailjet inválidas, cliente sem contato de faturamento ou template de e-mail ausente
  • Solução: Verifique a configuração do Mailjet em crm_config.yaml, verifique os contatos do cliente, confirme se o template de e-mail da fatura existe.

Botão de reembolso não aparecendo

  • Causa: Fatura paga via dinheiro/POS/transferência bancária (não Stripe), ou fatura não paga
  • Soluçã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 do PDF mostra design antigo do template

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

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

  • Causa: Nenhum método de pagamento salvo no portal de Autoatendimento
  • Solução: O cliente deve adicionar um cartão de crédito na página Métodos de Pagamento antes de pagar as 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
  • Soluçã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 da transação não mostra transações

  • Causa: Todas as transações no intervalo de datas já estão faturadas ou não existem transações
  • Solução: Verifique se o intervalo de datas está correto. Confira 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 a transação da geração da fatura

  • Causa: Transação já faturada ou problema no navegador
  • Solução: Verifique se a transação aparece na pré-visualização com um sinal 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
  • Solução: Revise a pré-visualização da transação cuidadosamente. Verifique o custo de varejo e o imposto de cada transação. Confirme 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
  • Soluçã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 Fim. Confira se a Data de Vencimento está definida.

Modal de Detalhes da Fatura não abrindo

  • Causa: Erro de JavaScript ou página não carregada completamente
  • Soluçã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
  • Solução: Verifique se a transação tem tax_percentage definido. Confirme que 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: Fatura está anulada ou o usuário não tem permissões
  • Solução: Faturas anuladas mostram apenas o botão Baixar PDF. Verifique o status da fatura. Confira o papel e as permissões do usuário.

Documentação Relacionada​

  • integrations_mailjet - Entrega de e-mail de fatura e templates
  • administration_configuration - Configuração do template de fatura
  • payments_transaction - Criando transações que aparecem nas faturas
  • payments_process - Processando pagamentos de faturas
  • payment_system_guide - Referência da API de pagamento e configuração de fornecedores

Gestão 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, Visão Geral de Faturamento, Processamento de Pagamentos, Faturas.

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 Vencimento - Monitorar e atualizar cartões que estão prestes a vencer
  • Autoatendimento - Clientes podem gerenciar seus próprios cartões via Portal de Autoatendimento
  • Gestão de Funcionários - Funcionários de suporte podem adicionar/remover cartões em nome de 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 apenas armazenará:

  • Fornecedor de pagamento (stripe, paypal)
  • Marca do cartão (Visa, Mastercard, etc.)
  • Últimos 4 dígitos
  • Mês/Ano de vencimento
  • Nome/nome de usuário 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 Vencendo:

Veja todos os clientes com cartões prestes a vencer:

Isso mostra uma lista de cartões em todo o sistema que estão vencendo nos 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 de Trabalho")
  • Emissor - Marca do cartão e últimos 4 dígitos
  • Vencimento - Mês/Ano de vencimento (formato MM/AAAA)
  • Adicionado - Data em que o cartão foi adicionado à conta
  • Padrão - Sinal 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 o cartão da conta

Adicionando um Método de Pagamento​

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

Etapa 1: Inserir Detalhes do Cartão​

O formulário de pagamento seguro aparece (alimentado pelo 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, vencimento, CVC (validado pelo Stripe)
  • Nome do Titular do Cartão - Nome no cartão
  • País/Região - País de faturamento

Campos Opcionais:

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

Segurança:

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

Etapa 2: Enviar e Tokenizar​

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

  1. Validação do Lado do Cliente:
    • O fornecedor de pagamento valida o formato do número do cartão
    • Verifica se a data de vencimento está no futuro
    • Verifica o formato do CVC
  2. Tokenização:
    • Detalhes do cartão enviados diretamente para o fornecedor de pagamento (não para o OmniCRM)
    • O fornecedor cria um token seguro (por exemplo, pm_1A2B3C4D para Stripe)
    • Token retornado ao OmniCRM
  3. Processamento no Servidor:
    • O OmniCRM salva o token no registro do cliente com o identificador do fornecedor
    • Armazena os últimos 4 dígitos, marca, vencimento e nome do fornecedor para exibição
    • Nenhum número completo de cartão toca nos servidores do OmniCRM

Etapa 3: Confirmação​

Mensagem de sucesso aparece:

Seu Visa terminando em 1234 foi adicionado à sua conta.

O novo cartão aparece na tabela de métodos de pagamento.

Seleção Automática Padrão:

  • Se este for o primeiro cartão do cliente, ele é automaticamente definido como padrão
  • Se o cliente já tiver cartões, o novo cartão é adicionado como não padrão
  • O cliente pode mudar o padrão após a adição

Definindo o Método de Pagamento Padrão​

O método de pagamento padrão é usado para:

  • Cobranças automáticas recorrentes de serviços
  • Pagamentos de faturas
  • Recargas e recargas
  • Transações únicas (a menos que especificado de outra forma)

Para Mudar o Padrão:

  1. Localize o cartão que deseja definir como padrão na tabela de métodos de pagamento

  2. Clique no menu de ações (⋮) ao lado do cartão

  3. Selecione "Definir como Padrão"

  4. A confirmação aparece

    O Visa terminando em 5678 agora é seu método de pagamento padrão.

O sinal de verificação se move para o cartão recém-selecionado.

Indicador Visual:

Cartões padrão mostram:

na coluna Padrão, tipicamente com um distintivo de verificação verde.

Excluindo um Método de Pagamento​

Remova cartões que estão vencidos, perdidos ou não são mais necessários.

Etapa 1: Iniciar Exclusão​

  1. Encontre o cartão a ser excluído na tabela de métodos de pagamento
  2. Clique no ícone de lixeira nessa linha

Se o cliente tiver apenas um método de pagamento ativo, o ícone de lixeira está desativado. Passar o mouse sobre ele mostra uma dica:

Não é possível excluir seu único método de pagamento. Adicione outro método de pagamento primeiro.

Adicione um segundo método de pagamento antes de poder remover o existente.

Etapa 2: Confirmar Exclusão​

Quando a exclusão é permitida, um modal de confirmação aparece:

Você tem certeza de que deseja excluir este método de pagamento?

[Cancelar] [Excluir Método de Pagamento]

Se o método a ser excluído for o padrão atual e outros métodos ativos existirem, o modal observa que outro método ativo será promovido a padrão após a exclusão.

Clique em "Excluir Método de Pagamento" para confirmar.

Etapa 3: Exclusão Completa​

Mensagem de sucesso:

O cartão é removido da tabela e excluído do fornecedor de pagamento.

Restrições Importantes:

  • Não é possível excluir o único método de pagamento ativo - O controle de exclusão está desativado (com dica). A API também rejeita a solicitação. Adicione outro método de pagamento primeiro.
  • Excluindo o padrão quando outros existem - Outro método de pagamento ativo utilizável é promovido a padrão automaticamente.
  • Sem desfazer - A exclusão é permanente; o cliente deve re-adicionar o método se necessário.

Gerenciando Cartões Vencendo​

O OmniCRM rastreia as datas de vencimento dos cartões e fornece ferramentas para atualizar proativamente os cartões que estão prestes a vencer.

Painel de Cartões Vencendo​

Navegue até Faturamento → Cartões Vencendo para ver uma lista em todo o sistema:

Cliente Cartão Vencimento Dias até Ação John Smith Visa **1234 02/2025 12 dias Atualizar Acme Corp MC5678 03/2025 45 dias Atualizar Jane Doe Amex**9012 01/2025 VENCIDO Atualizar

Painel de Cartões Vencendo

Filtros:

  • Intervalo de Vencimento - Próximos 30/60/90 dias ou já vencido
  • Tipo de Cliente - Individual vs Empresarial
  • Tipo de Serviço - Filtrar por serviço que requer método de pagamento

Ações:

  • Atualizar - Abre a página de métodos de pagamento do cliente para adicionar um novo cartão
  • Notificar - Enviar lembrete por e-mail ao cliente (se Mailjet configurado)

Notificações de Vencimento​

Se o Mailjet estiver configurado, e-mails automáticos são enviados:

  • 60 dias antes do vencimento - Primeiro lembrete
  • 30 dias antes do vencimento - Segundo lembrete
  • 7 dias antes do vencimento - Aviso final
  • No vencimento - Aviso de que o cartão expirou

Os clientes podem clicar em um link no e-mail para atualizar seu método de pagamento via portal de Autoatendimento.

Variáveis do Template de E-mail:

Templates do Mailjet recebem:

  • Nome do cliente
  • Marca do cartão e últimos 4 dígitos
  • Data de vencimento
  • Link para a página de métodos de pagamento do Autoatendimento

Veja integrations_mailjet para configuração do template de e-mail.

Atualizando um Cartão Vencendo​

Fluxo de Trabalho Recomendado:

  1. O cliente recebe um e-mail de notificação de vencimento
  2. O cliente faz login no portal de Autoatendimento
  3. Navega até Faturamento → Métodos de Pagamento
  4. Clica em "Adicionar Método de Pagamento"
  5. Insere os detalhes do novo cartão (mesmo cartão com vencimento atualizado ou cartão de substituição)
  6. Define o novo cartão como padrão
  7. Exclui o cartão antigo/vencido

Fluxo de Trabalho da Equipe:

Se o cliente ligar para o suporte:

  1. A equipe abre a conta do cliente
  2. Navega até Faturamento → Métodos de Pagamento
  3. Adiciona um novo cartão em nome do cliente (o cliente fornece os detalhes por telefone)
  4. Define o novo cartão como padrão
  5. Exclui o cartão vencido
  6. Confirma com o cliente
aviso

Nunca peça aos clientes para enviar detalhes do cartão por e-mail ou mensagem. Sempre use:

  • Portal seguro de Autoatendimento para autoatendimento
  • Telefone com a equipe inserindo detalhes diretamente no sistema
  • Pessoalmente em local de varejo

O Que Acontece Quando os Cartões Expiram​

Quando um cartão de pagamento atinge sua data de vencimento e não é atualizado:

Efeitos Imediatos:

  1. Pagamentos Automáticos Falham
    • O fornecedor de pagamento rejeita transações com cartões expirados
    • Renovações mensais de serviços falham ao processar
    • Recargas automáticas falham
    • Pagamentos automáticos de faturas falham
  2. Notificações ao Cliente
    • O sistema tenta cobrar o cartão
    • Notificação de falha de pagamento enviada
    • E-mail "Atualizar Método de Pagamento" enviado com link para o portal de Autoatendimento
  3. Mudanças no Status do Serviço
    • Serviços Pós-Pagos - Podem continuar temporariamente com saldo pendente
    • Serviços Pré-Pagos - Suspensão do serviço quando o saldo se esgota
    • Serviços de Renovação Automática - A renovação falha, o serviço pode expirar

Ações Subsequentes:

Dia 1-3 (Período de Graça):

  • O serviço continua normalmente
  • O cliente recebe o primeiro aviso de falha de pagamento
  • O sistema tenta a nova tentativa (dependendo da configuração)

Dia 4-7:

  • Segunda tentativa de pagamento (se configurada)
  • E-mail de aviso enviado
  • O serviço de atendimento ao cliente pode entrar em contato com o cliente

Dia 8-14:

  • O serviço pode ser suspenso por falta de pagamento
  • O status suspenso impede o uso, mas preserva a conta
  • O cliente pode restaurar atualizando o método de pagamento e pagando o saldo devedor

Dia 15+:

  • O serviço pode ser encerrado por falta de pagamento
  • Inventário (chips SIM, equipamentos) marcado para devolução
  • Aviso final enviado
  • Conta encaminhada para cobrança (se aplicável)

Prevenindo Interrupção do Serviço:

Para evitar interrupções no serviço:

  • Atualize os cartões 30 dias antes do vencimento
  • Adicione múltiplos métodos de pagamento para redundância
  • Ative alertas de falha de pagamento
  • Monitore o painel de Cartões Vencendo semanalmente

Restaurando o Serviço Após o Vencimento:

Se o serviço foi suspenso devido a um cartão expirado:

  1. Adicione um novo método de pagamento válido
  2. Defina como padrão
  3. Pague o saldo devedor (se houver)
  4. Entre em contato com o suporte para reativar o serviço
  5. Serviço restaurado em minutos a horas

Segurança do Método de Pagamento​

Tokenização​

OmniCRM usa tokenização de fornecedores para garantir segurança:

  1. Cliente insere o cartão → Enviado diretamente para os servidores do fornecedor de pagamento
  2. Fornecedor valida e tokeniza → Cria um token único
  3. Token armazenado no OmniCRM → Número completo do cartão nunca é armazenado
  4. Processamento de pagamento → Token enviado ao fornecedor, fornecedor cobra o cartão

O que o OmniCRM Armazena:

{
  "vendor": "stripe",
  "vendor_payment_method_id": "pm_1A2B3C4D5E6F",
  "payment_type": "card",
  "brand": "visa",
  "last4": "1234",
  "exp_month": 12,
  "exp_year": 2026,
  "name": "John Smith",
  "nickname": "Personal Card",
  "is_default": true
}

O que o OmniCRM NÃO Armazena:

  • Número completo do cartão
  • Código CVV/CVC
  • Dados da faixa magnética
  • Números PIN

Conformidade PCI​

Ao usar formulários de pagamento hospedados por fornecedores:

  • Escopo PCI reduzido - Dados do cartão nunca tocam os servidores do OmniCRM
  • Campos hospedados pelo fornecedor - A entrada do cartão acontece no iframe seguro do fornecedor
  • Sem armazenamento de cartões - Tokens usados em vez de dados brutos do cartão
  • Transmissão segura - Toda comunicação via HTTPS/TLS

Veja o Guia do Sistema de Pagamento para detalhes de segurança do fornecedor de pagamento.

Fluxos de Trabalho Comuns​

Fluxo de Trabalho 1: Cliente Adiciona Primeiro Método de Pagamento​

Cenário: Novo cliente se inscrevendo para o serviço

  1. O cliente cria uma conta
  2. Seleciona o plano de serviço
  3. Solicitado a adicionar um método de pagamento durante o checkout
  4. Insere os detalhes do cartão no modal do Stripe
  5. Cartão tokenizado e salvo
  6. Automaticamente definido como padrão
  7. Serviço provisionado
  8. Primeira cobrança processada

Fluxo de Trabalho 2: Cliente Atualiza Cartão Vencendo​

Cenário: Cartão de crédito prestes a vencer

  1. O cliente recebe notificação por e-mail (60 dias antes do vencimento)
  2. Faz login no portal de Autoatendimento
  3. Navega até Faturamento → Métodos de Pagamento
  4. Revê o cartão atual que vence em 12/2025
  5. Clica em "Adicionar Método de Pagamento"
  6. Insere o cartão de substituição com vencimento em 12/2028
  7. Define o novo cartão como padrão
  8. Exclui o cartão antigo
  9. E-mail de confirmação enviado

Fluxo de Trabalho 3: Funcionário Ajuda Cliente pelo Telefone​

Cenário: Cliente liga: "Meu cartão foi recusado"

  1. O cliente liga para o suporte
  2. O funcionário verifica a identidade (perguntas de segurança)
  3. O funcionário verifica os métodos de pagamento: Cartão expirado 01/2025
  4. Funcionário: "Seu cartão expirou. Você tem um novo cartão?"
  5. O cliente fornece os detalhes do novo cartão pelo telefone
  6. O funcionário navega até Clientes → [Cliente] → Faturamento
  7. Clica em "Adicionar Método de Pagamento"
  8. Insere os detalhes do cartão enquanto o cliente os lê
  9. Define o novo cartão como padrão
  10. Exclui o cartão expirado
  11. Tenta novamente o pagamento falhado
  12. Confirma com o cliente: "Pagamento bem-sucedido, serviço restaurado"

Fluxo de Trabalho 4: Cliente Empresarial com Vários Cartões​

Cenário: A empresa quer cartões diferentes para diferentes propósitos

  1. O cliente empresarial adiciona o cartão principal (Visa terminando em 1111)
  2. Define como padrão para cobranças mensais de serviço
  3. Adiciona cartão de backup (Mastercard terminando em 2222) para recargas
  4. Adiciona cartão de compras (Amex terminando em 3333) para compras de equipamentos
  5. Ao fazer uma recarga, seleciona manualmente o Mastercard no checkout
  6. O Visa padrão ainda é usado para faturamento automático mensal

Fluxo de Trabalho 5: Gerenciando Cartões Vencendo (Admin)​

Cenário: Gestão proativa de vencimentos

  1. O administrador navega até Faturamento → Cartões Vencendo
  2. Filtros: "Próximos 30 dias"
  3. Vê 15 clientes com cartões vencendo
  4. Seleciona todos → "Enviar E-mails de Lembrete"
  5. Mailjet envia e-mails personalizados para cada cliente
  6. Clientes atualizam cartões via Autoatendimento
  7. O administrador revisa a lista 1 semana depois
  8. Liga para os clientes restantes que não atualizaram
  9. Auxilia com atualizações de cartões pelo telefone

Solução de Problemas​

"Cartão recusado" ao adicionar método de pagamento

  • Causa: Stripe rejeitou o cartão (fundos insuficientes, prevenção de fraudes, recusa do emissor)
  • Solução:
    • Tente um cartão diferente
    • Entre em contato com o emissor do cartão para autorizar a transação
    • Certifique-se de que o cartão suporta compras online
    • Verifique se o endereço de cobrança corresponde ao cartão registrado

"Erro ao adicionar método de pagamento" (erro genérico)

  • Causa: Erro da API do fornecedor de pagamento ou problema de rede
  • Solução:
    • Atualize a página e tente novamente
    • Verifique a conexão com a internet
    • Verifique se a configuração do fornecedor de pagamento está correta nas configurações do sistema
    • Verifique o console do navegador para mensagens de erro específicas
    • Tente um navegador diferente (desative bloqueadores de anúncios)

Não é possível excluir método de pagamento (botão desativado)

  • Causa: É o único método de pagamento ativo do cliente
  • Solução:
    • Adicione um novo método de pagamento primeiro, depois exclua o antigo
    • Passe o mouse sobre o ícone de lixeira desativado para a explicação da dica

Cartão aparece como expirado, mas não na lista de "Cartões Vencendo"

  • Causa: O cartão expirou recentemente, cache não atualizado
  • Solução:
    • Atualize a página
    • Verifique os filtros no painel de Cartões Vencendo
    • Cartões expirados podem mudar para uma visualização diferente

Novo cartão não aparece imediatamente

  • Causa: A página não foi atualizada após a adição do cartão
  • Solução:
    • A tabela de métodos de pagamento deve atualizar automaticamente
    • Se não, atualize manualmente o navegador
    • Verifique se ocorreu um erro durante o processo de adição

Modal de pagamento não carrega

  • Causa: SDK do fornecedor de pagamento não carregando, problema com a chave da API ou extensão do navegador bloqueando
  • Solução:
    • Verifique o console do navegador para erros
    • Desative bloqueadores de anúncios e proteção contra rastreamento
    • Verifique a configuração do fornecedor de pagamento nas configurações do sistema
    • Certifique-se de que o script do SDK do fornecedor carrega (verifique a aba Rede)
    • Tente o modo de navegação anônima/privada

Cliente não recebe notificações de vencimento

  • Causa: Mailjet não configurado ou modelo de e-mail ausente
  • Solução:
    • Verifique as credenciais do Mailjet em crm_config.yaml
    • Verifique se o modelo de e-mail existe para vencimento de cartão
    • Confirme se o endereço de e-mail do cliente é válido
    • Verifique os logs do Mailjet para falhas de entrega

Melhores Práticas​

Para Clientes:

  • Adicione o método de pagamento antes da ativação do serviço para evitar atrasos
  • Mantenha pelo menos 2 cartões registrados para redundância
  • Atualize cartões vencendo 30+ dias antes do vencimento
  • Exclua cartões antigos/vencidos para evitar confusão
  • Use apelidos descritivos ("Visa Pessoal", "Amex de Trabalho")
  • Verifique se o método de pagamento padrão está correto para faturamento automático

Para Funcionários de Suporte:

  • Verifique a identidade do cliente antes de acessar os métodos de pagamento
  • Nunca peça aos clientes que enviem detalhes do cartão por e-mail/SMS/chat
  • Processe adições de cartões imediatamente durante as chamadas (não adie)
  • Confirme se o novo cartão está definido como padrão após a adição
  • Exclua cartões antigos apenas após confirmar que o novo cartão funciona
  • Teste o pagamento após atualizar o cartão expirado (processo de autorização de £0.01)

Para Administradores:

  • Monitore o painel de Cartões Vencendo semanalmente
  • Envie e-mails de lembrete 60/30/7 dias antes do vencimento
  • Mantenha as chaves de teste/produção do fornecedor de pagamento separadas para dev vs produção
  • Certifique-se de que os modelos do Mailjet estão configurados para notificações de vencimento
  • Revise relatórios de pagamento falhado para identificar cartões expirados
  • Treine a equipe sobre procedimentos seguros de manuseio de cartões

Melhores Práticas de Segurança:

  • Use apenas chaves publicáveis do fornecedor (nunca chaves secretas no frontend)
  • Certifique-se de que todas as páginas de pagamento carreguem via HTTPS
  • Revise regularmente o painel do fornecedor de pagamento em busca de atividades suspeitas
  • Ative regras de prevenção de fraudes do fornecedor
  • Exija CVC para todas as transações sem cartão presente
  • Registre alterações no método de pagamento no log de atividades

Documentação Relacionada​

  • Guia do Sistema de Pagamento - Configuração e integração do fornecedor de pagamento
  • payments_process - Processamento de pagamentos com métodos de pagamento armazenados
  • payments_invoices - Pagamento automático de faturas usando o cartão padrão
  • features_topup_recharge - Sistema de recarga usando métodos de pagamento
  • basics_payment - Conceitos gerais de pagamento e faturamento
  • customer_care - Portal de Autoatendimento para clientes gerenciarem seus próprios cartões

Interface de Gerenciamento de Métodos de Pagamento

Processar Pagamentos

A maioria dos pagamentos será processada automaticamente pelo sistema, mas há momentos em que você pode precisar processar um pagamento manualmente.

Para pagar uma fatura, selecione a fatura não paga e clique no botão "Pagar".

Isso abrirá um formulário de pagamento, onde você pode inserir o método de pagamento e clicar em "Enviar" para processar o pagamento.

O cliente receberá automaticamente um recibo pelo pagamento, e a fatura será marcada como paga.

Para transferências bancárias, você pode inserir a referência de pagamento e a data em que o pagamento foi feito (se diferente da data atual).

Pagar uma Fatura

Pagar uma Fatura

Última atualização em