Skip to main content

Módulo 07: Veículos & FIPE

Status: Documentado

Domínio: ver Domínio/Entidade: Veículo

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

1. Visão Geral da Regra​

Todo veículo está obrigatoriamente associado a um Cliente. A avaliação do veículo usa a Tabela FIPE como referência de valor de mercado para precificação da proteção, quando exigida pelo Plano contratado.

O sistema implementa uma estratégia dupla e tolerante a falhas para a consulta FIPE, garantindo continuidade do processo comercial mesmo diante de indisponibilidades de API.

2. Estratégia FIPE: Cache Local + API Externa​

2.1 Fonte Primária — Sincronização Local (CSV Mensal)​

  • Um job agendado (Cron) roda todo dia 1º de cada mês para baixar o CSV oficial atualizado da Tabela FIPE e importá-lo para o banco de dados do CRM.
  • É a fonte primária durante o fluxo de cotação padrão (seleção por Tipo → Marca → Modelo → Ano).
  • Vantagens: consultas instantâneas, tolerante a falhas de internet, sem custo por requisição.
  • A importação é assíncrona (processamento em background) para não degradar a performance do banco durante a inserção de milhares de registros.
  • A tabela fipe_historico armazena o mês de referência de cada valor, garantindo auditoria histórica.

2.2 Fonte Secundária — API Externa (Busca por Placa / Fallback)​

  • Integração com fornecedor de dados veiculares (ex: Parallelum, InfoSimples).
  • Permite buscar o código FIPE e os dados completos do veículo (Marca, Modelo, Ano, Chassi, Renavam) digitando apenas a Placa — experiência mais rápida para o consultor.
  • Utilizada em dois cenários:
    1. O consultor digita a placa no cadastro do veículo para autocompletar os dados (enriquecimento).
    2. Como fallback: quando a tabela local não está sincronizada ou o código FIPE específico não é encontrado no cache.

3. Regras de Negócio FIPE​

  1. Imutabilidade na Proposta: O valor FIPE gravado em uma Proposta é o valor do momento da criação daquela Proposta. Se a tabela atualizar no mês seguinte, propostas existentes mantêm o valor cotado (respeitando a validade em dias configurada no tenant).
  2. Congelamento: O campo codigo_fipe fica no Veículo (referência permanente); o valor monetário correspondente é consultado e congelado na Proposta no momento da criação.
  3. Tratamento de Lançamentos 0km sem FIPE (Fallback por Nota Fiscal): Caso o veículo seja um lançamento 0km e ainda não conste na FIPE oficial (fipe_status = PENDENTE_CADASTRO_FIPE), o sistema permite a geração de Propostas e Contratos que exigem FIPE utilizando as informações obrigatórias da Nota Fiscal de Fábrica (Número, Emissão e Valor) como valor de cotação temporário. O Contrato incorpora uma cláusula contratual de transição que valida a indenização com base no valor da Nota Fiscal por até 90 dias ou até a publicação oficial na FIPE.
  4. Atualização na Renovação (configurável por Tenant): O sistema deve permitir configurar se, na renovação anual do contrato, o valor de proteção e indenização será atualizado para o valor FIPE corrente.
  5. Veículos não tabelados: Para planos de proteção de bens não cobertos pela FIPE (ex: Bicicletas), o consultor informa o valor_base_informado (valor declarado ou de nota fiscal). Esse valor serve como base para indenização conforme as regras do Plano.
  6. Auto-Conciliação FIPE (Job em Background): A cada importação mensal da FIPE (dia 1º), o sistema executa um Job de conciliação assíncrona que varre todos os veículos ativos com fipe_status = PENDENTE_CADASTRO_FIPE. O worker tenta realizar o pareamento (Marca, Modelo, Ano e Motorização) contra a nova base de dados. Ao encontrar correspondência, o sistema vincula o codigo_fipe ao Veículo e altera o status para VINCULADO. Se o veículo completar 90 dias sem pareamento, o sistema gera uma tarefa de follow-up (Módulo 14) de alta prioridade para o consultor e o gestor fazerem a vinculação manual.

3.1 Conformidade Jurídica e Criptografia do Contrato Assinado​

Como o PDF do Contrato é assinado digitalmente e possui um hash criptográfico inviolável, o arquivo PDF original jamais pode ser editado ou modificado após a assinatura para inclusão do código FIPE. Para garantir validade jurídica total, o CRM implementa a seguinte abordagem parametrizável por Tenant:

  • Estratégia Padrão (Cláusula de Indexação Automática): O PDF original do contrato é gerado contendo uma cláusula dinâmica de transição de cobertura. Ela estabelece que o veículo em estado de lançamento 0km está coberto temporariamente pelo valor da Nota Fiscal informada e que, assim que o indexador oficial for disponibilizado pela FIPE, a base de cálculo de indenização e mensalidade será migrada eletrônica e automaticamente para o respectivo código FIPE. A vinculação posterior ocorre estritamente a nível de banco de dados e timeline de auditoria do CRM, sem violar a integridade criptográfica do PDF assinado.
  • Estratégia Estrita (Termo Aditivo Digital): Se configurado pelo Tenant, a vinculação do código FIPE pós-lançamento gera automaticamente no CRM um Termo Aditivo Digital. Este pequeno documento complementar detalha o vínculo do código FIPE e valor de indenização ao contrato principal e é enviado para a assinatura digital do cliente, complementando legalmente o contrato original.

4. Regras de Cadastro do Veículo​

  1. Veículo 0km sem placa: O sistema aceita salvar veículos sem placa (placa = null), desde que o chassi esteja preenchido como identificador alternativo. A placa pode ser atualizada posteriormente ao emplacamento.
  2. Propostas múltiplas por veículo: O mesmo veículo pode receber N propostas (diferentes coberturas, por exemplo), mas ao assinar uma, todas as demais propostas ENVIADA do mesmo veículo são automaticamente marcadas como SUBSTITUIDA.
  3. Placa única por tenant: Não podem existir dois veículos com a mesma placa dentro do mesmo tenant.
  4. Tipo imutável: O campo tipo (CARRO, MOTO, etc.) é imutável após o cadastro — define qual catálogo FIPE e quais planos são elegíveis.

5. Regras Inegociáveis​

[!IMPORTANT] O bloqueio de FIPE ocorre na Proposta, não no Veículo. O cadastro do veículo permite salvar sem codigo_fipe (ex: placa falhou, modelo 0km ainda não tabelado). A validação ocorre somente no momento de associar o veículo a um Plano que exige FIPE, aceitando Nota Fiscal como fallback se fipe_status = PENDENTE_CADASTRO_FIPE.

[!WARNING] A importação mensal do CSV da FIPE deve ser assíncrona. O processamento em background é obrigatório para não degradar a performance do banco durante a inserção em massa. A tabela fipe_historico deve registrar o mês de referência de cada conjunto de dados importado.

[!NOTE] Veículo Lançamento 0km / Nota Fiscal: Para liberar propostas e contratos de carros em lançamento sem FIPE ativa, o sistema exige a digitação e validação dos metadados da Nota Fiscal de Fábrica (Número, Emissão e Valor), que atuará como garantia de cotação temporária. O sistema gera tarefa de acompanhamento para posterior vinculação assim que catalogado.