Skip to main content

Módulo 09: Propostas / Cotações

Status: Documentado

Domínio: ver Domínio/Entidade: Proposta

ATA de Referência: (Ainda não aprovada)

1. Visão Geral da Regra​

A Proposta é a oferta comercial que une Cliente, Veículo e Plano. Após aceita pelo cliente e com vistoria aprovada (quando exigida), converte-se em Contrato.

O fluxo é desenhado para ser interativo: o consultor pode gerar múltiplas propostas para o mesmo veículo simulando diferentes planos, coberturas opcionais e taxas de adesão, enviando links dinâmicos para o cliente decidir.

2. Composição de Preço (Cálculo Dinâmico)​

O valor final mensal é calculado em quatro componentes:

ComponenteDescrição
A — Valor Base do PlanoCusto mínimo da categoria (piso do plano)
B — Valor de Risco (Cota FIPE)Valor FIPE do Veículo × Coeficiente de Risco do Plano
C — Soma dos OpcionaisSomatório dos serviços opcionais selecionados (ex: Vidros R$20 + Carro Reserva R$35)
D — Desconto Aplicado% concedido pelo consultor, limitado pelo tenant
VALOR MENSALIDADE = (Max(A, B) + C) - D
  • Taxa de Adesão: Valor fixo cobrado na entrada, negociável pelo consultor, com mínimo definido na política do plano.
  • O cálculo é realizado em tempo real pelo backend enquanto o consultor configura a proposta (simulação prévia).

3. Congelamento de Valores (Snapshot)​

No momento em que a proposta passa para o status ENVIADA, os seguintes valores são congelados e nunca mais alterados:

  • Valor FIPE do veículo + mês de referência (snap_valor_fipe, snap_fipe_mes_ref)
  • Nome e condições do plano (snap_nome_plano)
  • Nome e valor de cada opcional incluído (snap_nome_opcional, snap_valor_mensal)

[!IMPORTANT] Nunca usar JOIN direto nas tabelas originais ao renderizar uma proposta histórica. Planos mudam de preço e a FIPE atualiza todo mês. Sempre renderizar a partir dos campos snap_* gravados na proposta.

  1. Ao enviar a proposta, o sistema gera uma página web com URL única (/p/{hash_publico}) onde o cliente visualiza o resumo da cotação.
  2. O link exibe: resumo do veículo, coberturas incluídas (e exclusões), valores financeiros (adesão + mensalidade) e identidade visual do tenant (white-label).
  3. O cliente pode clicar em "Aprovar Proposta" ou "Recusar" diretamente pelo link, sem precisar de login.
  4. Aprovação Assistida (Rota do Consultor): O consultor pode realizar o aceite comercial e aprovar a proposta manualmente a qualquer momento diretamente através do painel do CRM (seja a partir do status RASCUNHO ou ENVIADA), sem exigir que o cliente acesse o link público. Esta rota é comum em vendas conduzidas via telefone/WhatsApp, onde o cliente prefere que o consultor gerencie o processo e envie diretamente o link final do contrato para assinatura.
  5. O aceite pelo link ou painel não é uma assinatura jurídica — é apenas o aceite comercial. A validade jurídica ocorre no Contrato (Módulo 11).
  6. O canal de envio (WhatsApp ou e-mail) é escolhido pelo consultor no momento do envio.

5. Validade e Expiração​

  • Propostas têm prazo de validade configurado no tenant (proposta_validade_dias).
  • Ao atingir data_validade sem resposta do cliente, o status muda automaticamente para PERDIDA (motivo: "Expirado").
  • O consultor recebe alerta quando uma proposta enviada está próxima de vencer (configurável).

6. Descontos e Alçadas​

6.1 Alçadas de Desconto de Mensalidade​

CenárioComportamento
Desconto ≤ desconto_maximo_consultor_pct (tenant)Aprovado automaticamente. Proposta pode ser enviada.
Desconto > limite do consultor e ≤ desconto_maximo_gestor_pctSistema bloqueia o envio. Consultor solicita aprovação do gestor/padrinho.
Desconto > limite do gestorBloqueado. Apenas o Admin pode aprovar.
  • A checagem acontece no backend no momento do POST /api/propostas e do POST /api/propostas/{id}/enviar.
  • O frontend deve bloquear também para UX, mas a validação de segurança é exclusiva da API.

6.2 Regras de Taxa de Adesão por Canal de Vendas​

O comportamento da Taxa de Adesão na Proposta varia de acordo com o canal de vendas (canal_vendas) associado ao Usuário que a gerou:

A) Canal de Vendas: INTERNO (Vendas de Escritório / Leads Repassados)​

  • Regra: Adesão Fíxa.
  • A taxa de adesão cobrada do cliente é exatamente igual ao valor padrão configurado no Plano (taxa_adesao_base).
  • O sistema bloqueia a edição dos campos de desconto ou acréscimo de adesão: 
    taxa_adesao_acrescido = 0
    taxa_adesao_desconto = 0
    taxa_adesao_negociada = taxa_adesao_base

B) Canal de Vendas: EXTERNO (Vendas de Campo / Prospecção Ativa)​

  • Regra: Adesão Flexível (desconto ou acréscimo de comissão).
  • O consultor externo usa o taxa_adesao_base como guia de precificação sugerida.
  • Ele possui autonomia para gerenciar o valor da adesão:
    • Acréscimos (taxa_adesao_acrescido): O consultor pode elevar o valor cobrado (ex: adicionando R$200 a um valor base de R$100 para cobrar R$300 do cliente). Esse excedente é destinado integralmente como comissão direta para o consultor externo.
    • Descontos (taxa_adesao_desconto): O consultor pode conceder descontos parciais ou até totais (adesão R$0) a fim de facilitar o fechamento da venda.
  • Máscara Comercial: O cliente final visualiza apenas o valor consolidado final (taxa_adesao_negociada), tanto na tela da proposta pública quanto no PDF do Contrato. A composição interna de acréscimo de comissão é oculta para o cliente.

7. Fluxo Pós-Aceite​

Após a proposta comercial ser marcada como ACEITA (seja por clique do cliente no link ou por ação manual do consultor no painel do CRM):

8. Clonagem de Proposta​

  • Se o cliente recusou por questão de preço, o consultor pode clonar a proposta existente.
  • A proposta clonada nasce como RASCUNHO, herdando os dados do veículo, plano e opcionais.
  • O consultor ajusta os valores (ex: reduz taxa de adesão, remove um opcional) e reenvia.
  • Evita retrabalho de recadastrar veículo e selecionar plano do zero.

9. Exclusão Mútua de Propostas por Veículo​

  • Ao marcar uma proposta como CONVERTIDA (contrato gerado), todas as demais propostas ENVIADA do mesmo veículo são automaticamente marcadas como SUBSTITUIDA.
  • Garante que um veículo não entre em dois contratos ativos simultaneamente.