Importação de Histórico de negociações CRM

# Manual do Usuário - Importação de Histórico de Negociações (CRM)

**Data:** 29/07/2026
**Projeto:** V3ndor — Multipanel (CRM) / Redline
**Sistema:** Multipanel CRM — Importações
**Chamado de referência:** 0000568560

---

## 1. Introdução

O processo de **Importação de Histórico de Negociações** permite carregar, em massa, negociações antigas (de uma planilha ou de um CRM anterior) diretamente para dentro do CRM do sistema — sem perder as datas originais de cada etapa da negociação.

### O que o processo faz?

- Lê uma planilha **XLSX** com uma negociação por linha
- Cria (ou localiza) o cliente/empresa de cada linha, sem duplicar cadastro
- Cria a negociação (deal) com as **datas reais e históricas** de cada etapa (criação, prospecção, lead, oportunidade, ganho, perda) — nunca usa a data de hoje
- Cria automaticamente comentários no histórico da negociação e contatos do cliente, se informados na planilha
- Permite reprocessar a mesma planilha sem gerar duplicidade (usando uma coluna de identificador)

---

## 2. Acessando o processo

### 2.1. Navegação

No menu lateral, acesse **CRM → Importar negociações**.

_(inserir print do menu lateral aqui)_

Isso abre a tela de **Importações de negociações** (URL `/crm/importacoes`), que lista todas as importações já feitas e seus progressos.

### 2.2. Iniciando uma nova importação

No topo da tela, clique em **Importar XLSX**.

_(inserir print do botão "Importar XLSX" aqui)_

Será exibida uma tela para escolher o **tipo de importação**. Selecione **Histórico de Negociações** e clique em **Continuar**.

> **⚠️ IMPORTANTE**: existe também o tipo "Negociações" (importação simples por lista de CNPJ). Não confunda os dois — o tipo "Histórico de Negociações" é o único que preserva datas antigas e aceita comentários/contatos por planilha.

---

## 3. Passo a passo do assistente de importação

O assistente é dividido em **4 etapas**, navegadas pelos botões **Voltar** / **Avançar** no topo da tela.

### 3.1. Etapa 1 — Arquivo e padrões do lote

_(inserir print da etapa 1 aqui)_

1. Envie o arquivo **XLSX** no campo de upload.
2. Se a planilha tiver mais de uma aba, o sistema pergunta **qual aba** usar.
3. Informe a **linha do cabeçalho** (linha onde estão os nomes das colunas) — o padrão é a linha 1; altere apenas se o cabeçalho estiver em outra linha.
4. Preencha os **padrões do lote** — valores usados para *todas* as linhas da planilha quando a coluna correspondente não for mapeada (ou não tiver de-para definido na etapa 3):
   - **Departamento**
   - **Usuário responsável (padrão)** — obrigatório
   - **Pipeline** — obrigatório
   - **Origem (padrão)**
   - **Estratégia (padrão)**
   - **Enquete (padrão)**
   - **Status padrão** — uma das opções: Prospect, Lead, Oportunidade, Negócio, Perdido

> **💡 DICA**: os padrões do lote funcionam como um "fallback" — preencha-os mesmo que a planilha já tenha essas colunas, para cobrir linhas com informação faltando.

### 3.2. Etapa 2 — Mapeamento de colunas

_(inserir print da etapa 2 aqui)_

Para cada campo do sistema, escolha a coluna correspondente da planilha (campos sem coluna selecionada usam o padrão do lote definido na Etapa 1):

| Campo do sistema | O que representa |
|---|---|
| Empresa (nome) | Nome do cliente/empresa |
| Documento (CNPJ ou CPF) | Documento do cliente |
| Identificador da negociação (opcional) | Código único da negociação na planilha/CRM antigo |
| Valor | Valor da negociação |
| Data de captação (criação) | Data em que o cadastro foi criado |
| Data de prospecção / Data de lead / Data da oportunidade / Data de ganho / Data de perda / Data de encerramento | Datas de cada etapa da negociação |
| Status / Situação | Situação da negociação na planilha (será tratada na Etapa 3) |
| Responsável | Responsável pela negociação na planilha (Etapa 3) |
| Origem | Origem do lead na planilha (Etapa 3) |
| Logradouro, Número, Complemento, Bairro, CEP, Cidade | Endereço do cliente (usado só se o cliente ainda não tiver endereço cadastrado) |

### 3.3. Etapa 3 — De-Para (reconciliação de valores)

_(inserir print da etapa 3 aqui)_

Nesta etapa o sistema lista **todos os valores distintos** encontrados nas colunas de Status, Origem, Responsável e Cidade (as que foram mapeadas na Etapa 2), e pede para indicar a qual registro do sistema cada valor corresponde:

- **Status → Etapa da pipeline / Situação**: para cada valor de status da planilha (ex.: "Fechado", "Perdido"), escolha a **etapa da pipeline** e a **situação** (Prospect/Lead/Oportunidade/Negócio/Perdido) correspondente.
- **Origem → Cadastro de origem**: associe cada valor de origem da planilha a uma origem já cadastrada no CRM.
- **Responsável → Usuário**: associe cada nome de responsável da planilha a um usuário do sistema.
- **Cidade → Município (IBGE)**: associe cada nome de cidade da planilha ao município correto.

Ainda nesta etapa é possível configurar dois recursos opcionais:

**Comentário compilado (observação)** — gera um único comentário na timeline de cada negociação juntando o conteúdo de colunas escolhidas (ex.: observações antigas do CRM anterior). Pode-se definir um formato usando `{nome_da_coluna}`; sem formato, o sistema monta automaticamente "coluna: valor". Se nenhuma coluna for escolhida, este comentário não é gerado.

**Comentários (histórico)** e **Contatos do cliente** — listas de 0 a N itens, adicionadas com o botão **"Adicionar comentário"** / **"Adicionar contato"**:
- Cada **comentário** vira um registro no histórico da negociação (coluna de descrição obrigatória; coluna de data opcional — se vazia, usa a data de criação do registro).
- Cada **contato** vira um telefone, celular ou e-mail na ficha do cliente (coluna de valor e tipo, ambos obrigatórios). Só são criados os contatos que o cliente ainda não tiver.

> **💡 DICA**: sem adicionar nenhum item nessas listas, nada é gerado — são totalmente opcionais.

### 3.4. Etapa 4 — Prévia e finalização

_(inserir print da etapa 4 aqui)_

O sistema mostra uma **prévia** com todas as linhas da planilha e as colunas mapeadas, para conferência final. Confirme os dados e clique em **Finalizar** para iniciar a importação.

Ao finalizar, você é redirecionado de volta para a tela **Importações de negociações** (`/crm/importacoes`), onde o progresso da importação recém-criada aparece automaticamente.

---

## 4. Como o sistema trata cada linha da planilha

Cada linha da planilha vira **uma negociação**. Por trás dos panos, o sistema segue estas regras para não gerar cadastros duplicados nem sobrescrever dados existentes:

### 4.1. Como o cliente é localizado (ou criado)

O sistema decide na seguinte ordem:

1. **Identificador da negociação (`ref`)**: se esse código já existir em algum cliente cadastrado, reaproveita o cadastro.
2. **CNPJ ou CPF**: se a planilha trouxer um documento, ele decide sozinho — encontrou um cliente com esse documento → reaproveita; não encontrou → **cria um novo cliente** (o nome nem chega a ser comparado, pois o documento tem prioridade).
3. **Nome ou nome fantasia**: só é usado quando a planilha **não** tem documento. Se houver mais de um cliente com o mesmo nome, o cadastro mais antigo é reaproveitado (para não gerar duplicidade).
4. Se nada for encontrado, um novo cliente é criado.

> **⚠️ IMPORTANTE**: sempre que possível, preencha a coluna de **Documento (CNPJ/CPF)** — é a forma mais confiável de evitar clientes duplicados.

### 4.2. Dados que nunca são sobrescritos

Se o cliente já existir no sistema, **nenhum dado do cadastro atual é alterado**. O processo apenas **adiciona o que estiver faltando**: endereço (só se o cliente ainda não tiver nenhum), contatos que ainda não existirem, e os comentários/histórico da planilha.

### 4.3. Reprocessamento sem duplicar

Se a mesma planilha (ou uma correção dela) for importada de novo, e a linha tiver um **Identificador da negociação (`ref`)** preenchido, a negociação existente é **atualizada**, não duplicada. Sem esse identificador, cada importação gera negociações novas.

### 4.4. Datas preservadas

Diferente de uma negociação criada manualmente no CRM (que usa a data de hoje), a importação histórica preserva as datas exatamente como vieram da planilha: criação, prospecção, lead, oportunidade, ganho e perda.

### 4.5. Múltiplas negociações para o mesmo cliente

Ao contrário do fluxo normal do CRM (que impede duas negociações ativas na mesma estratégia para o mesmo cliente), a importação histórica **permite múltiplas negociações** para a mesma empresa — afinal, cada linha da planilha representa um episódio diferente do histórico comercial daquele cliente.

---

## 5. Acompanhando o progresso da importação

Na tela **Importações de negociações** (`/crm/importacoes`), cada importação aparece com:

| Coluna | Descrição |
|---|---|
| Nome | Nome do arquivo importado |
| Tipo | "Histórico" (para este processo) ou "Negociações" (importação simples) |
| Iniciado | Data/hora em que a importação começou |
| Status | Situação atual do processamento |
| Importados | Quantidade de linhas já processadas com sucesso |
| Não importados | Quantidade de linhas que falharam |
| Progresso | Barra de progresso (linhas processadas / total de linhas) |

> **💡 DICA**: o progresso é atualizado **automaticamente na tela**, sem precisar atualizar a página — a importação roda em segundo plano e pode levar alguns minutos dependendo do tamanho da planilha.

---

## 6. Dicas importantes

### 📋 Antes de importar
- Preencha a coluna de **Documento (CNPJ/CPF)** sempre que possível, para evitar clientes duplicados.
- Use uma coluna de **Identificador da negociação (`ref`)** se pretende reprocessar/corrigir a planilha depois — isso evita duplicar negociações.
- Revise os **padrões do lote** (Etapa 1): eles cobrem qualquer linha com dado faltando.

### 🔄 De-Para
- Confira com atenção o de-para de **Status** — é ele que define em qual etapa da pipeline e em qual situação (Prospect/Lead/Oportunidade/Negócio/Perdido) cada negociação entra.
- Nomes de cidade e de responsável precisam ser associados manualmente ao registro correto do sistema; valores não reconhecidos ficam sem associação.

### 🕒 Sobre as datas
- As datas de cada etapa (prospecção, lead, oportunidade, ganho, perda) são as da planilha, não a data da importação.
- Aceita datas em formato `dd/mm/aaaa` e datas de planilha Excel.

---

**Teorema Sistemas © 2026**