> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suasofia.online/llms.txt
> Use this file to discover all available pages before exploring further.

# Importando Leads

> Importe leads de arquivos CSV e Excel com validação e tratamento de erros

Importe grandes volumes de leads de arquivos CSV ou Excel com validação automática, processamento em segundo plano e relatório abrangente de erros.

## Visão Geral do Processo de Importação

O sistema de importação de leads suporta:

* **Arquivos CSV e Excel** (.csv, .xlsx, .xls)
* **Processamento em segundo plano** para arquivos grandes
* **Validação automática** com relatório de erros
* **Contatos secundários** na mesma importação
* **Mapeamento de variáveis** da configuração do assistente

## Preparando Seu Arquivo de Importação

### Colunas Obrigatórias

Seu arquivo de importação deve incluir:

* **phone\_number:** Número de telefone do contato principal (obrigatório)
* **Variáveis:** Colunas correspondentes às [variáveis configuradas do seu assistente](/ai-assistants/settings/prompt-and-tools#call-variables)

### Colunas Opcionais

* **Colunas de contatos secundários:** Números de telefone adicionais
* **Personalização de variáveis:** Valores customizados para leads específicos

### Exemplo de Formato de Arquivo

```csv theme={null}
phone_number,customer_name,company,budget_range,secondary_phone_1,secondary_phone_2
+14155551234,John Smith,ABC Corp,10k-50k,+14155551235,+14155551236
+14155557890,Jane Doe,XYZ Inc,50k-100k,+14155557891,
+14155554567,Bob Johnson,Tech Start,5k-10k,,
```

## Configuração de Importação

### 1. Selecionar Campanha

Escolha a campanha de destino no menu suspenso. As variáveis do assistente determinarão quais colunas são esperadas durante o mapeamento.

### 2. Contatos Secundários

Selecione quantos números de telefone secundários por lead (0-10). Se seu arquivo contém números de telefone adicionais além do contato principal, especifique a quantidade aqui.

### 3. Formato do Número de Telefone

Escolha o formato dos seus números de telefone:

**Formato Internacional (Recomendado)**

* Números já incluem código do país com prefixo +
* Exemplo: `+40741234567`, `+14155551234`
* Não é necessária seleção de país
* Pode misturar vários países no mesmo arquivo

**Formato Nacional**

* Números sem prefixo de código do país
* Exemplo: `0741234567`, `7775551234`
* **Deve selecionar código do país** durante a importação
* **Importante:** Separe seu arquivo por país - todos os números devem ser do mesmo país por arquivo
* O sistema adiciona o código do país selecionado a todos os números

<Warning>
  Ao usar formato nacional, você deve importar um arquivo por país. Não misture números de países diferentes no mesmo arquivo.
</Warning>

### 4. Seleção de Código do País

Aparece apenas quando "Formato Nacional" é selecionado. Escolha o país que corresponde a todos os números de telefone em seu arquivo. O sistema automaticamente adicionará o código do país a todos os números.

## Etapas de Importação

### 1. Iniciar Processo de Importação

1. **Navegue para a seção Leads** ou aba de leads da Campanha
2. **Clique no botão "Importar Leads"**
3. **Selecione a campanha** para atribuição do lead
4. **Baixe o arquivo de exemplo** para ver o formato esperado

### 2. Upload e Mapeamento de Colunas

1. **Escolha o arquivo:** Selecione seu arquivo CSV ou Excel
2. **Mapeamento de colunas:** Mapeie as colunas do seu arquivo para os campos do sistema:
   * **Número de Telefone (obrigatório):** Selecione a coluna contendo os números de telefone
   * **Variáveis do assistente:** Mapeie cada variável para sua coluna correspondente
   * **Contatos secundários:** Se configurado, mapeie números de telefone secundários e variáveis
3. **Detecção automática:** Sistema detecta automaticamente mapeamentos baseado em nomes de cabeçalho comuns
4. **Revisar e importar:** Confirme os mapeamentos e clique em "Importar" para começar

### 3. Processamento em Segundo Plano

* **Processamento de fila:** Arquivos grandes processados em segundo plano
* **Acompanhamento de progresso:** Status de importação atualiza automaticamente
* **Notificação:** Notificação por email quando a importação termina
* **Relatório de erros:** Baixe relatório de qualquer linha que falhou

## Regras de Validação

### Validação de Número de Telefone

* **Verificação de formato:** Formato internacional preferido (+1234567890)
* **Detecção de duplicatas:** Previne números de telefone duplicados
* **Números inválidos:** Automaticamente sinalizados e ignorados

### Validação de Variáveis

* **Campos obrigatórios:** Variáveis marcadas como obrigatórias devem ter valores
* **Tipos de dados:** Validação de texto, número, booleano onde aplicável
* **Limites de comprimento:** Limites máximos de caracteres aplicados

### Validação de Contatos Secundários

* **Formato de telefone:** Mesma validação dos números primários
* **Números únicos:** Contatos secundários devem diferir do primário
* **Consistência de variáveis:** Variáveis de contatos secundários validadas independentemente

## Tratamento de Erros

### Tratamento Automático de Erros

O sistema de importação automaticamente trata erros de validação:

* **Linhas válidas importadas:** Leads validados com sucesso são adicionados à campanha
* **Linhas inválidas ignoradas:** Linhas que falharam na validação são automaticamente excluídas
* **Relatório de erros gerado:** Relatório detalhado de todas as linhas que falharam é criado
* **Sucesso parcial:** Importação completa com sucesso com todos os leads válidos, linhas que falharam são registradas

### Erros Comuns de Validação

* **Números de telefone inválidos:** Formato incorreto ou números impossíveis
* **Campos obrigatórios ausentes:** Valores vazios para variáveis obrigatórias
* **Números de telefone duplicados:** Número de telefone já existe no sistema
* **Problemas de formato de arquivo:** Arquivo corrompido ou formato não suportado

### Download do Relatório de Erros

Após completar a importação:

* **Link de download** fornecido na notificação
* **Descrições detalhadas de erros** para cada linha que falhou
* **Orientação para correção** para corrigir problemas
* **Capacidade de re-importação** com dados corrigidos

## Importação de Contatos Secundários

### Múltiplos Números de Telefone por Lead

Inclua colunas adicionais para contatos secundários:

```csv theme={null}
phone_number,customer_name,secondary_phone_1,secondary_phone_2,secondary_phone_3
+14155551234,John Smith,+14155551235,+14155551236,+14155551237
```

### Variáveis de Contatos Secundários

Adicione variáveis específicas para contatos secundários:

```csv theme={null}
phone_number,customer_name,secondary_phone_1,secondary_1_name,secondary_1_role
+14155551234,John Smith,+14155551235,Jane Smith,Decision Maker
```

### Ordenação de Contatos

* **Contato principal:** Sempre chamado primeiro
* **Ordem secundária:** Chamados em ordem de coluna (secondary\_phone\_1, depois secondary\_phone\_2, etc.)
* **Coordenação de campanha:** Respeita configurações de nova tentativa da campanha entre contatos

## Tratamento de Arquivos Grandes

### Processamento em Segundo Plano

* **Fila automática:** Arquivos com mais de 1000 linhas processados em segundo plano
* **Eficiência de memória:** Processamento em streaming previne timeouts
* **Acompanhamento de progresso:** Atualizações de status em tempo real
* **Performance do sistema:** Nenhum impacto na performance da plataforma durante a importação

### Sistema de Notificação

* **Notificações por email:** Enviadas quando a importação termina
* **Resumo de sucesso:** Número de leads importados com sucesso
* **Resumo de erros:** Contagem e detalhes de linhas que falharam
* **Links de download:** Acesso aos relatórios de erros e dados importados

### Tempo de Processamento

* **Arquivos pequenos (\< 100 linhas):** Geralmente completados em 1 minuto
* **Arquivos médios (100-1000 linhas):** 2-5 minutos típicos
* **Arquivos grandes (1000+ linhas):** 10-30 minutos dependendo da complexidade
* **Arquivos muito grandes (10k+ linhas):** Podem levar várias horas

## Melhores Práticas

* **Use arquivo de exemplo:** Baixe o modelo fornecido para formato correto
* **Formato de telefone:** Formato internacional sem separadores (+1234567890)
* **Dados limpos:** Remova linhas vazias e valide conteúdo
* **Teste primeiro:** Comece com um lote pequeno para verificar formato
* **Combine variáveis:** Garanta que as colunas se alinhem com a configuração do assistente

<Note>
  Para solução detalhada de problemas e problemas comuns de importação, veja [Solução de Problemas de Leads](/troubleshooting/leads).
</Note>

<Note>
  Para informações sobre gerenciar leads importados, veja [Gerenciando Leads](/leads/managing-leads).
</Note>