# Atualizar contatos em massa por planilha (exportar, editar e importar)

Este guia explica como atualizar vários contatos de uma vez usando uma planilha: você exporta a base, edita no Excel ou Google Planilhas e importa de volta. Vale para dados básicos (nome, e-mail, telefone) e também para os **campos personalizados** que você criou em Configurações.

Antes de começar, entenda a regra mais importante: **a importação reconhece o contato pelo telefone ou pelo e-mail**. Se a linha da planilha tiver o mesmo telefone (ou o mesmo e-mail) de um contato que já existe, esse contato é **atualizado**. Se não tiver nenhum dos dois, a plataforma **cria um contato novo**.

## O que a importação faz com cada campo

| Situação | O que acontece |
| --- | --- |
| Telefone ou e-mail igual ao de um contato existente | O contato é atualizado, não é duplicado |
| Linha sem telefone e sem e-mail | Cria um contato novo (é a causa mais comum de duplicados) |
| Nome, e-mail ou telefone preenchidos | Substituem o valor atual |
| Nome, e-mail ou telefone em branco | Não mexem no valor atual |
| Coluna de campo personalizado preenchida | Substitui o valor atual daquele campo |
| Coluna de campo personalizado **em branco** | **Apaga** o valor atual daquele campo |
| Campo personalizado que não está na planilha | Fica como está |
| Mesmo telefone em duas linhas da planilha | A segunda linha é rejeitada |
| Telefone inválido | A linha é rejeitada e aparece no relatório de erros |

Guarde esta regra: **coluna presente e célula vazia apaga; coluna ausente preserva.**

## Passo 1: exportar a base

1. Vá em **Contatos** no menu lateral.
2. Clique nos três pontinhos no canto superior direito e escolha **Exportar contatos**.
3. O arquivo CSV chega no seu e-mail em alguns minutos.

O arquivo exportado traz apenas os dados básicos: id, nome, e-mail, telefone e CNPJ/CPF. **Os campos personalizados não vêm na exportação.** Você vai acrescentar as colunas deles na mão, no passo seguinte.

Se precisar de uma planilha já com os valores atuais dos campos personalizados de todos os contatos, fale com o suporte: a equipe gera esse arquivo para você.

## Passo 2: montar a planilha

Abra o CSV no Excel ou no Google Planilhas e siga estas regras:

**Telefone**
- Mantenha a coluna de telefone exatamente como veio, com o código do país (por exemplo, +5527999999999). É por ela que a plataforma reconhece o contato.
- Se o Excel transformar o número em algo como 5,5279E+12, não se preocupe: a plataforma entende esse formato.

**Campos personalizados**
- Crie uma coluna para cada campo que você quer atualizar.
- No cabeçalho, use a **chave** do campo, e não o nome de exibição. Exemplo: `ticket_medio`, e não "Ticket Médio". A chave aparece em **Configurações > Campos Personalizados**, ao lado de cada atributo.
- Se preferir usar o nome de exibição no cabeçalho, pode. Nesse caso, aponte a coluna para o campo certo na tela de mapeamento (passo 3).
- Preencha a célula de **todos** os contatos nessa coluna. Célula em branco apaga o valor que já estava salvo.
- Não crie coluna para campos que você não vai mexer.

**Formato dos valores**
- Número e moeda: pode usar vírgula ou ponto (1.250,50 ou 1250.50).
- Caixa de seleção: sim ou não, true ou false, 1 ou 0.
- Data: 08/09/2026 ou 2026-09-08.
- Lista: escreva o valor exatamente como está cadastrado no campo.

**Limpeza antes de importar**
- Apague as linhas que estão sem telefone e sem e-mail. Elas não têm como ser reconhecidas e viram contatos novos.
- Confira se não há o mesmo telefone em duas linhas.
- A coluna `id` pode ficar. Ela é ignorada na importação.
- Salve como CSV. O separador pode ser vírgula ou ponto e vírgula (padrão do Excel em português); a plataforma detecta os dois.
- Limite: 15.000 linhas por arquivo. Se a base for maior, divida em mais de um arquivo.

## Passo 3: importar

1. Em **Contatos**, clique nos três pontinhos e escolha **Importar contatos**.
2. Selecione o arquivo CSV.
3. Na tela de **mapeamento de colunas**, confira cada coluna da sua planilha:
   - Telefone apontando para **Telefone**, e-mail para **E-mail**, nome para **Nome**.
   - Cada coluna de campo personalizado apontando para o campo correspondente. Os campos personalizados aparecem na lista pelo nome de exibição.
   - Colunas que não interessam (como `id`) marcadas como **Ignorar**.
4. Não marque etiqueta, agente padrão ou time padrão no formulário, a não ser que queira aplicar isso a todos os contatos do arquivo.
5. Clique em **Importar**.

Ao terminar, a plataforma avisa quantos contatos foram processados. Se alguma linha foi rejeitada, é possível baixar um arquivo com as linhas e o motivo de cada erro.

## Passo 4: teste antes de rodar tudo

Antes de importar a base inteira, faça um teste:

1. Salve uma cópia da planilha com apenas 2 ou 3 contatos.
2. Importe esse arquivo pequeno.
3. Abra esses contatos e confira se os campos foram atualizados do jeito esperado e se nenhum contato foi duplicado.
4. Só então importe o arquivo completo.

Se quiser uma segurança extra, peça ao suporte uma cópia dos seus contatos antes de rodar a importação completa.

## Perguntas frequentes

**Importei e criou contatos duplicados. Por quê?**
Quase sempre porque a linha estava sem telefone e sem e-mail, ou porque o telefone estava em outro formato (sem o código do país, com o nono dígito diferente). Sem um desses dados igual ao do cadastro, a plataforma não tem como saber que é o mesmo contato. Use a opção **Mesclar** na tela do contato para juntar os duplicados: selecione primeiro o contato original e depois o duplicado.

**Perdi valores de campos personalizados depois de importar. O que aconteceu?**
A planilha tinha a coluna daquele campo com células em branco. Célula vazia apaga o valor. Na próxima vez, preencha todas as células ou remova a coluna.

**Posso atualizar só os campos personalizados, sem mexer em nome e e-mail?**
Sim. Deixe na planilha só a coluna de telefone (ou e-mail) e as colunas dos campos personalizados. Os demais dados ficam como estão.

**Etiquetas entram na planilha?**
Sim. Crie uma coluna `etiquetas` e escreva as etiquetas separadas por vírgula. Etiquetas que ainda não existem são criadas automaticamente. A importação adiciona etiquetas; ela não remove as que o contato já tem.