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

Navegue até Clientes → [Selecionar Cliente]
Clique na aba Faturamento
Veja a lista de transações no primeiro cartão

Visualização em Todo o Sistema:

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

Widgets de Estatísticas de Transações

Na parte superior 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 (todo o tempo)
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" (ex: $1.5k)
Valores acima de 1.000.000: Exibir como sufixo "M" (ex: $2.3M)
Valores acima de 1.000.000.000: Exibir como sufixo "B" (ex: $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 (apenas se faturada)
Anular Transação - Marcar transação como anulada (apenas 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 Atraso - Penalidades por faturas vencidas
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 na 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 por 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 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:

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

Pesquisando e Filtrando Transações

Pesquisa

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

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, Anulado, Não Anulado
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 reverter 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:

Localize a transação na lista
Clique no menu de ações (⋮)
Selecione "Anular Transação"
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 de transações padrão
Excluída da geração de fatura
Pode ser visualizada filtrando por transações "Anuladas"
Deduza da contagem total de "Transações Não Faturadas"

Transações vinculadas à 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:
- 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 (links 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:

O sistema encontra todas as transações não faturadas para aquele cliente
Opcionalmente filtra por intervalo de datas
Transações incluídas na nova fatura
Campo invoice_id da transação populado
Transação agora marcada como "faturada"

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

Fluxos de Trabalho Comuns

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

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

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

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

Fluxo de Trabalho 3: Anulando Transação Duplicada

A equipe nota uma transação duplicada
Verifique se a transação NÃO foi faturada
Clique no menu de ações (⋮) na transação duplicada
Selecione "Anular Transação"
Confirme no modal
A transação é removida da lista
O total não faturado diminui de acordo

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

Precisa gerar fatura mensal
Clique no filtro Fatura: "Não Faturada"
Clique em Aplicar Filtros
Veja todas as transações não faturadas
Anote o valor total dos widgets
Navegue para gerar fatura
Selecione intervalo de datas (ex: 1-31 Jan)
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 o reembolso for necessário, crie uma transação de Crédito em vez disso.
Causa: Falha na reversão da recarga da 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 (apenas 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) duplicadas 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 as transações anuladas, filtre por "Anular: Anulado".

Total não faturado não corresponde ao esperado

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

Não é possível adicionar transação (campo do 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 do Cliente

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 dos clientes são totalmente modeladas com Mailjet e podem ser personalizadas para incluir o logotipo da empresa, endereço e detalhes de pagamento, e podem ser enviadas ao cliente por e-mail, ou baixadas como PDF.

Log de Atividades

Personalizando Modelos de Faturas

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

Localização do Modelo de Fatura

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

Modelos Padrão:

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

Configuração:

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

invoice:
  template_filename: 'norfone_invoice_template.html'

Variáveis de Modelo Disponíveis

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

Informações da Fatura:

{{ invoice_number }} - ID único da fatura (ex: INV-2025-001234)
{{ date }} - Data de emissão da fatura (formato ISO: 2025-01-10T12:00:00)
{{ due_date }} - Data de vencimento do pagamento (ex: 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 - Porcentagem de imposto aplicada (ex: 10 para 10%)
sub_transaction.tax_amount - Valor do imposto calculado em dólares

Exibindo Imposto em Modelos:

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

Criando um Modelo de Fatura Personalizado

Passo 1: Copiar Modelo Existente

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

Passo 2: Personalizar HTML/CSS

Edite your_company_invoice_template.html para corresponder ao seu branding:

Áreas de Personalização Chave:

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>

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>

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>

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>

Termos e Condições

<div class="terms">
    <h4>Termos de Pagamento</h4>
    <p>Pagamento devido dentro de 30 dias a partir da data da fatura.</p>
    <p>Taxas de atraso: 2% ao mês sobre saldos vencidos.</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

Navegue até um cliente com transações
Gere uma fatura de teste
Baixe o PDF para verificar a formatação
Envie a fatura para você mesmo para testar a entrega por e-mail

Personalização Avançada

Conteúdo Condicional:

Use condicionais Jinja2 para mostrar/ocultar conteúdo:

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

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

Suporte a Múltiplos Idiomas:

Crie modelos específicos para cada idioma:

invoice_template_en.html
invoice_template_es.html
invoice_template_fr.html

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

Cálculos Personalizados:

<!-- Exibir subtotal e detalhamento do imposto -->
<tr>
    <td colspan="4" class="text-right"><strong>Subtotal:</strong></td>
    <td>${{ "%.2f"|format(total_amount) }}</td>
</tr>
<tr>
    <td colspan="4" class="text-right"><strong>Imposto:</strong></td>
    <td>${{ "%.2f"|format(total_tax) }}</td>
</tr>
<tr>
    <td colspan="4" class="text-right"><strong>Total:</strong></td>
    <td>${{ "%.2f"|format(total_amount + total_tax) }}</td>
</tr>

Nota: A variável total_tax é calculada automaticamente somando o tax_amount de todas as transações na fatura. O imposto de cada transação é calculado com base no seu campo tax_percentage, que padrão é a 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 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:

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
Precisão dos Dados:
- Detalhes do cliente corretos
- Valores das transações somam corretamente
- Datas formatadas corretamente
- Todas as variáveis substituindo corretamente
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
Faturas de Múltiplas Páginas:
- Cabeçalhos se repetem em cada página
- Números de página exibidos
- Listas longas de transações paginam corretamente
Entrega de E-mail:
- PDF anexado 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
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 de 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 aparecem:

Causa: URLs relativas ou recursos externos bloqueados
Soluçã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
Solução: Use larguras percentuais, 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 de 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:

Primeira Solicitação - Quando um PDF de fatura é solicitado (download ou e-mail), o sistema:
- Gera o PDF a partir do modelo de fatura
- Codifica o PDF como Base64
- Calcula um hash SHA256 do conteúdo do PDF
- Armazena na tabela Invoice_PDF_Cache com:
  - Referência do ID da fatura
  - Dados do PDF (codificados em Base64)
  - Nome do arquivo
  - Hash do conteúdo (para verificação de integridade)
  - Timestamp de criação
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
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 (ex: 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, então 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 mudança de modelo.

Acessando Faturas

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

Visualização por Cliente:

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

Visualização em Todo o Sistema:

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

Widgets de Estatísticas de Faturas

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

Estatísticas e Lista de Faturas

Descrições dos Widgets:

Total de Faturas - Soma de todos os custos de varejo das faturas (todo o tempo) 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" (ex: $1.5k)
Valores acima de 1.000.000: Exibir como sufixo "M" (ex: $2.3M)
Valores acima de 1.000.000.000: Exibir como sufixo "B" (ex: $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
🗑️ (Deletar) - Anular fatura (apenas se não paga)
💰 (Pagar) - Pagar fatura online (apenas se não paga)
✉️ (E-mail) - Enviar e-mail da fatura para o cliente
💸 (Reembolsar) - Reembolsar pagamento do Stripe (apenas 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 Visualização de Transação

Descrições dos Campos:

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

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

O que Acontece:

O sistema encontra todas as transações não faturadas para o cliente dentro do intervalo de datas
Exibe a visualização da transação com a capacidade de incluir/excluir transações individuais
Mostra o cálculo em tempo real do subtotal, imposto e total com base nas transações selecionadas
Apenas as transações selecionadas (incluídas) são adicionadas à fatura
Gera o PDF da fatura e o armazena em cache
Marca as transações selecionadas como faturadas (invoice_id campo populado)
Transações excluídas permanecem não faturadas e disponíveis para futuras faturas
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 visualização mostra todas as transações não faturadas daquele período. Selecione todas ou exclua manualmente as específicas.

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

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

Visualizando Detalhes da Fatura

Clique em qualquer linha de fatura na tabela para 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 do Stripe (apenas faturas pagas do Stripe)
- Deletar - 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:

Clique no ícone de download ao lado da fatura
O indicador de carregamento aparece durante a geração (apenas na primeira vez)
O navegador solicita salvar o arquivo: Invoice_01234.pdf
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 do Cache - Cache limpo se a fatura for modificada ou o modelo atualizado

Solução 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 da fatura para erros de sintaxe
Falha no download - 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:

Clique no ícone de pagamento na fatura não paga
O modal de pagamento se abre mostrando os detalhes da fatura
Selecione o método de pagamento:
- Transação Stripe - Cobrança do cartão de crédito salvo (disponível para todos os usuários)
- Dinheiro - Pagamento em dinheiro manual (apenas para a equipe)
- Reembolso - Aplicar reembolso como pagamento (apenas para a equipe)
- Transa��ão POS - Terminal de ponto de venda (apenas para a equipe)
- Transferência Bancária - Transferência bancária manual (apenas para a equipe)
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
Se outro método for selecionado:
- Insira o número de referência (opcional)
Clique em "Pagar Fatura" para processar
O sistema processa o pagamento:
- Stripe - Cobra o cartão via API do Stripe
- Outros métodos - Cria transação negativa para o valor do pagamento
O status da fatura muda para "Pago"
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 houver 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 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 pedindo que ele adicione um método de pagamento antes de poder 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:

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

Destinatários do E-mail:

O e-mail é enviado a todos os contatos do cliente com o tipo "faturamento" ou ao contato principal se não houver 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 de E-mail:

E-mail não enviado - Verifique as credenciais da API do Mailjet em crm_config.yaml
Cliente não recebendo - Verifique os endereços de e-mail de contato 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 deletar (🗑️) para anular uma fatura.

Requisitos:

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

Como Anular:

Localize a fatura não paga na lista
Clique no ícone de deletar (🗑️)
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 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
A fatura aparece na lista com o prefixo "Anulado:" no título
Ações da fatura desativadas (sem download, pagamento ou e-mail)
Pode ser visualizada filtrando por faturas "Anuladas"

Notas Importantes:

Anular não é o mesmo que reembolsar
Anular = "Esta fatura nunca deveria ter existido" (erro de faturamento, 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 ser Paga
A fatura deve ser paga via Stripe
A fatura deve ter uma payment_reference válida (ID da intenção de pagamento do Stripe)
Apenas disponível para usuários da equipe (não Autoatendimento)

Como Reembolsar:

Localize a fatura paga do Stripe
Clique no ícone de reembolso (💸)
O modal de confirmação de reembolso se abre:

Modal de Confirmação de Reembolso de Fatura

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

O que Acontece Após o Reembolso:

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

Restrições de Reembolso:

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

Pesquisando e Filtrando Faturas

Pesquisa

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

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

Filtros

Aplique filtros para restringir a lista de faturas:

Filtros Disponíveis:

Status de Anulação - 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

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 reverter a direção da ordenaçã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 Faturas

Fluxo de Trabalho 1: Faturamento Mensal com Visualização de Transação

Chega o final do mês (ex: 31 de janeiro)
Navegue até Faturamento → Faturas
Clique em "+ Gerar Fatura Proforma"
Selecione o cliente (ou faça por cliente se faturando muitos clientes)
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)
A seção Visualização de Transação aparece mostrando todas as transações não faturadas de janeiro
Revise a visualização:
- Todas as transações são incluídas por padrão
- Verifique os totais: Subtotal, Imposto e Total da Fatura
- Verifique se todas as cobranças estão corretas
Clique em "Gerar Fatura" (o botão mostra a contagem de transações, ex: "Gerar Fatura (15)")
Fatura criada com todas as transações selecionadas
Clique na linha da fatura para ver detalhes e verificar
Clique no botão "Enviar E-mail" no modal de detalhes ou no ícone de e-mail na tabela
O cliente recebe o e-mail da fatura com PDF e link de pagamento

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

O cliente tem vários serviços (Móvel + Internet) e cobranças diversas
Deseja faturas separadas para cada serviço
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 visualização de transação, exclua todas as transações não móveis:
  - Clique no botão X ao lado das transações de Internet
  - Clique no botão X ao lado das cobranças diversas
  - Apenas as transações de serviço móvel 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)
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 visualização de transação:
  - Transações móveis já faturadas (não aparecem)
  - Exclua cobranças diversas usando o botão X
  - Apenas as transações de serviço de Internet permanecem
- Clique em "Gerar Fatura"
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 visualização
- Clique em "Selecionar Tudo" para incluir todas
- Clique em "Gerar Fatura"
Envie todas as três faturas para o cliente

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

Chega o final do período de faturamento
Navegue até a aba Faturamento do cliente
Clique em "+ Gerar Fatura Proforma"
Defina as datas do período de faturamento
A visualização de transação mostra 20 transações
O cliente disputou uma cobrança e outra está pendente investigação
Na visualização de transação:
- Localize a transação disputada (ex: "Cobrança por excesso de dados")
- Clique no botão X para excluí-la
- Localize a transação pendente (ex: "Taxa de instalação")
- Clique no botão X para excluí-la
- A contagem de transações é atualizada: "18 Transações selecionadas"
- Os totais recalculam automaticamente
Revise os totais atualizados (exclui os valores disputados)
Clique em "Gerar Fatura (18)"
Fatura gerada apenas com transações aprovadas
Transações disputadas/pendentes permanecem não faturadas para o próximo ciclo de faturamento

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

A equipe gera a fatura mensal
A visualização de transação mostra um total inesperadamente alto
Revise cada transação na 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 deve ser cobrada
- Clique em X para excluir a transação de teste
Os totais se atualizam em tempo real
Verifique se o novo total corresponde ao valor esperado
Clique em "Gerar Fatura" com as transações corrigidas
Volte e anule/dele as transações excluídas, se necessário
Envie a fatura para o cliente com confiança

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

O técnico de campo completa a instalação
A equipe adiciona a transação de instalação manualmente
Navegue até a aba Faturamento do cliente
Clique em "+ Gerar Fatura Proforma"
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"
A visualização de transação mostra apenas as transações de hoje
Verifique se a cobrança de instalação aparece
Exclua quaisquer cobranças recorrentes usando o botão X (se presentes)
Clique em "Gerar Fatura"
Envie para o cliente imediatamente
O cliente paga online via Stripe

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

O cliente liga com uma pergunta de faturamento
A equipe navega até a lista de faturas do cliente
Clique na linha da fatura para abrir o modal de Detalhes da Fatura
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
Responda às perguntas do cliente com detalhes exatos
Se o cliente solicitar o PDF, clique no botão "Baixar PDF" no modal
Se o cliente solicitar o reenvio do e-mail, clique no botão "Enviar E-mail"
Feche o modal quando terminar

Fluxo de Trabalho 7: Corrigindo Erro de Faturamento

O cliente relata cobrança incorreta
A equipe clica na linha da fatura para ver detalhes
Revê a lista de transações no modal de Detalhes da Fatura
Identifica a transação incorreta
A fatura está não paga, então pode ser anulada
Clique no botão "Deletar" no rodapé do modal
Confirme a anulação
As transações tornam-se não faturadas novamente
A equipe modifica ou remove a transação incorreta da lista de transações
Gere nova fatura com transações corrigidas:
- Use a visualização de transação para excluir a transação corrigida, se necessário
- Inclua apenas cobranças válidas
Envie a fatura corrigida para o cliente

Fluxo de Trabalho 8: Processando Múltiplos Pagamentos

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

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

O cliente solicita reembolso por pagamento excessivo
A equipe verifica se a fatura foi paga via Stripe
Navegue até a fatura na lista
Clique na linha da fatura para ver detalhes
Verifique as informações de pagamento e o valor
Clique no botão "Reembolsar" no rodapé do modal (apenas aparece para faturas do Stripe)
Confirme o reembolso
O sistema processa o reembolso do Stripe
O status da fatura muda para "Reembolsada"
O cliente recebe o reembolso em 3-7 dias úteis
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
Soluçã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 do PDF da fatura

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

Falha no pagamento 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, verifique o painel do Stripe para a razão 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 do Stripe ou crie uma transação de crédito manualmente.

E-mail da fatura não enviado

Causa: Credenciais da API do Mailjet inválidas, cliente sem contato de faturamento ou modelo de e-mail ausente
Soluçã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 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 do Stripe. Para outros métodos de pagamento, crie uma transação de crédito manual.

Download do PDF mostra design antigo do modelo

Causa: PDF armazenado em cache antes da atualização do modelo
Solução: Limpe o cache do 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
Solução: O cliente deve adicionar um cartão 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
Solução: Anule a fatura duplicada. Ajuste os intervalos de datas para evitar sobreposição. Use a visualização de transação para garantir conjuntos de transação exclusivos.

A visualização de transação não mostra transações

Causa: Todas as transações no intervalo de datas já foram faturadas ou não existem
Soluçã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 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 visualização com uma marca de verificação. Atualize a página e tente novamente. Limpe o cache do navegador se o problema persistir.

O 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 visualização de transação com cuidado. Verifique cada custo de varejo e imposto de 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.

O 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 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
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 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
Soluçã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

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

Transações do Cliente

Acessando Transações​

Widgets de Estatísticas de Transações​

Lista de Transações​

Tipos de Transações​

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

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

Adicionando uma Transação Manualmente​

Pesquisando e Filtrando Transações​

Pesquisa​

Filtros​

Ordenação​

Anulando Transações​

Imposto sobre Transações​

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

Transações Faturadas vs Não Faturadas​

Fluxos de Trabalho Comuns​

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

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

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

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

Solução de Problemas​

Documentação Relacionada​

Faturas do Cliente

Personalizando Modelos de Faturas​

Localização do Modelo de Fatura​

Variáveis de Modelo Disponíveis​

Criando um Modelo de Fatura Personalizado​

Personalização Avançada​

Melhores Práticas de Estilização de PDF​

Testando Modelos de Fatura​

Problemas Comuns de Modelo​

Cache de PDF de Fatura​

Acessando Faturas​

Widgets de Estatísticas de Faturas​

Lista de Faturas​

Gerando uma Fatura​

Visualizando Detalhes da Fatura​

Baixando PDFs de Faturas​

Pagando Faturas​

Enviando Faturas por E-mail​

Anulando Faturas​

Reembolsando Faturas​

Pesquisando e Filtrando Faturas​

Pesquisa​

Filtros​

Ordenação​

Paginação​

Fluxos de Trabalho Comuns de Faturas​

Fluxo de Trabalho 1: Faturamento Mensal com Visualização de Transação​

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

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

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

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

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

Fluxo de Trabalho 7: Corrigindo Erro de Faturamento​

Fluxo de Trabalho 8: Processando Múltiplos Pagamentos​

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

Solução de Problemas​

Documentação Relacionada​

Processar Pagamentos

Acessando Transações

Widgets de Estatísticas de Transações

Lista de Transações

Tipos de Transações

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

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

Adicionando uma Transação Manualmente

Pesquisando e Filtrando Transações

Pesquisa

Filtros

Ordenação

Anulando Transações

Imposto sobre Transações

Visualização de Detalhes da Transação

Transações Faturadas vs Não Faturadas

Fluxos de Trabalho Comuns

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

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

Fluxo de Trabalho 3: Anulando Transação Duplicada

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

Solução de Problemas

Documentação Relacionada

Personalizando Modelos de Faturas

Localização do Modelo de Fatura

Variáveis de Modelo Disponíveis

Criando um Modelo de Fatura Personalizado

Personalização Avançada

Melhores Práticas de Estilização de PDF

Testando Modelos de Fatura

Problemas Comuns de Modelo

Cache de PDF de Fatura

Acessando Faturas

Widgets de Estatísticas de Faturas

Lista de Faturas

Gerando uma Fatura

Visualizando Detalhes da Fatura

Baixando PDFs de Faturas

Pagando Faturas

Enviando Faturas por E-mail

Anulando Faturas

Reembolsando Faturas

Pesquisando e Filtrando Faturas

Pesquisa

Filtros

Ordenação

Paginação

Fluxos de Trabalho Comuns de Faturas

Fluxo de Trabalho 1: Faturamento Mensal com Visualização de Transação

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

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

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

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

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

Fluxo de Trabalho 7: Corrigindo Erro de Faturamento

Fluxo de Trabalho 8: Processando Múltiplos Pagamentos

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

Solução de Problemas

Documentação Relacionada