13-07-26 - Contratos Recorrentes & Itens

Visão geral

A partir desta melhoria o módulo de Contrato passa a permitir a inserção de itens, a exemplo do que ocorre em Proposta, Pedido e Fatura e passa a permitir faturamento recorrente. São seis frentes conectadas:

Como ler este guia: tudo já vem instalado e configurado no ambiente - você não precisa preparar nada. Cada frente tem a explicação (o que faz e quais campos usa). A legenda de cada imagem indica se é um print do CRM ou uma recriação.

Como funciona

Os itens são adicionados na tela de Edição do Contrato (não é edição direta no detalhe). O formulário exibe o bloco Detalhes do Item com os botões Adicionar Produto e Adicionar Serviço, que abrem os popups de seleção. Ao salvar, os totais (Total, Sub Total) são recalculados automaticamente. No detalhe, a tabela de itens é exibida igual à de uma Fatura.

Tela do CRM - Bloco Detalhes do Item na edição do contrato - botões + Produto / + Serviço, seletor de Moeda e Total Geral.

02. Configuração de recorrência

Onde fica: no detalhe de um contrato, botão Customizar → Configurar Recorrência (ou pela URL direta abaixo).

Bloco geral

Bloco por forma de pagamento (Boleto)

Estas regras alimentam o cálculo de datas do motor de recorrência.

Ponto de atenção: na tela atual só o bloco Boleto é editável - o bloco de Cartão de Crédito está desativado.

Tela do CRM - Tela Configurar Recorrência— bloco Geral + bloco Forma Pagamento: Boleto.

03. Motor de recorrência

Aqui está o coração da automação. Uma tarefa agendada roda uma vez por dia, varre todos os contratos recorrentes e, para cada ciclo devido, gera uma Fatura e quando a forma de pagamento é Boleto, um Boleto é vinculado. Não gera novos contratos.

Quando um contrato é processado

Um contrato entra na rodada do dia quando todas as condições abaixo forem observadas:

• Ativar Recorrência = Sim;
• Tem contato em Relacionado a e em Resp. Financeiro 1;
• A Próxima Recorrência (ou a data de início, ou hoje) é igual ou anterior a hoje;
• Status do contrato é Ativo ou Suspenso;
• Forma Pagamento, Dia Pagamento, Periodicidade e Tipo Pagamento preenchidos;
• O Contrato tem ao menos um item.

Campos que controlam a recorrência

Ficam no bloco Recorrência do Contrato.

Tela do CRM - Bloco Recorrênciano detalhe do contrato - o campoÚltimo Log Recorrênciamostra a Fatura FAT-000001 e o Boleto BOL-000001 gerados na última execução.

Lógica de datas (resumo)

• Vencimento = dia configurado, ajustado para não estourar o fim do mês e, depois, para cair em dia útil conforme a política e os feriados;
• Emissão = vencimento − “dias antes”, também ajustada a dia útil;
• Pré-pago no 1º ciclo: emite hoje e vence em "hoje" + “primeiro vencimento após X dias”;
• Pró-rata (1º ciclo, se ligado): fator proporcional aplicado ao preço dos itens;
• Ao terminar, o motor agenda o próximo ciclo no campo Próxima Recorrência.

Anti-duplicação: cada ciclo recebe um identificador único (a competência do mês de vencimento + o contrato), gravado no campo Ciclo Recorrência da fatura. Antes de gerar, o motor verifica se já existe fatura para aquele ciclo — se existir, não duplica; apenas garante o boleto e reagenda. O boleto tem o mesmo controle.

Regras que barram a geração: o módulo Faturas precisa estar ativo (senão o processo aborta). Fatura de Boleto com valor abaixo de R$ 7,00 vai para o status “Auditoria” e o boleto não é gerado.

Como a rotina roda

Existe uma tarefa agendada chamada “Processa Recorrência”, que roda automaticamente uma vez por dia. Ela é ligada e desligada pela tela de configuração (seção 2) - quando a recorrência é ativada, a rotina passa a rodar; quando desativada, para.

Workflows que criam os Contratos

Antes de haver recorrência, o Contrato precisa existir. Isso é feito por dois workflows a partir da Proposta/Pedido aprovado. No exemplo abaixo, Gera Contrato está ligado (roda toda vez que a condição é atendida) e Gera Contrato Recorrente está desligado (rodaria só na primeira vez) - a escolha depende da opção “Gerar Contratos” na configuração.

Tela do CRM - Workflows de geração de contrato - Gera Contrato (ligado) e Gera Contrato Recorrente (desligado).

Os dados de recorrência já ficam preenchidos na Proposta/Pedido de origem (bloco Recorrência Contrato) e são copiados para o contrato gerado:

Tela do CRM - Bloco Recorrência Contrato na Proposta que origina o contrato recorrente.

Resultado esperado

Após a execução, aparecem a Fatura e o Boleto do ciclo. Repare no Ciclo Recorrência (mesmo número nos dois) e na Fonte = CRON do boleto - é assim que se confirma que vieram da rotina automática, e não foram lançados à mão.

04. Log de itens

Auditoria de alterações nos itens. A cada salvamento, o sistema compara o “antes” e o “depois” e registra o que mudou, item a item. Disponível em vários módulos que têm itens.

O que é registrado

Cada item adicionado, alterado ou removido num salvamento é registrado com uma ação:

Grava-se o nome do produto congelado (sobrevive à exclusão do produto), o usuário e a moeda congelados, a data/hora, e um JSON só com os campos que mudaram. Campos rastreados incluem quantidade, preço, desconto, comentário, campos customizados de item e os impostos ativos.

Como é capturado

A cada salvamento, o sistema compara o “antes” e o “depois” dos itens e registra apenas o que efetivamente mudou. A comparação identifica os itens por produto e posição na lista. Só é registrada uma alteração quando algum valor realmente muda - diferenças apenas de formatação de número não geram log.

Onde o usuário vê

No detalhe do registro, botão Mais → Log Itens. Abre um popup com a linha do tempo dos salvamentos (mais recente primeiro, com scroll infinito). Cada salvamento mostra quando, quem e a contagem de adicionados/alterados/removidos; cada item mostra a ação e, nas alterações, o valor antigo → novo.

Tela do CRM - Como chegar: no detalhe do registro, Mais → Log Itens.

05. PDF de Contratos

A partir desta melhoria você poder capturar a tabela de itens do módulo de Contratos em seus Modelos de PDF 

Tela do CRM - Editor de Modelo de PDF - em Configuração Tabela, a tabela “25 - FPR - Contrato” é exclusiva do módulo de Contratos.

06. Importar / Exportar CSV

A partir desta melhoria no módulo de Contratos, os registros importados passam a ficar com a Fonte marcada como “Importação”; e o Contrato ganhou o seletor de moeda na importação/exportação, com maior precisão de câmbio. A exportação passa a trazer os itens com moeda e conversão; a importação aceita as colunas do Contrato mais as colunas de item (Produto, Quantidade, Preço).

Pontos de atenção

A tela de configuração só aparece para usuários administradores.

Na configuração, só o bloco Boleto é editável hoje; o de Cartão de Crédito está desativado.

O motor de recorrência gera Faturas (e Boletos), não novos contratos - os contratos são criados pelos workflows de geração a partir de Propostas/Pedidos.

Fatura de Boleto abaixo de R$ 7,00 vai para o status “Auditoria” e não gera boleto.

O Log Itens não restringe por perfil - qualquer usuário com acesso ao detalhe do registro consegue ver o histórico.

O campo Resp. Financeiro 2 é preenchido mas não é usado pelo motor de recorrência - é apenas informativo.