Contact Leads

Resumo

Pipeline profissional de ingestão, normalização e deduplicação de contatos a partir de planilhas CSV. Detecta encoding automaticamente, normaliza e-mails, telefones no padrão E.164, estados brasileiros e categorias, aplica score de qualidade de 0 a 100 por contato e remove duplicatas por e-mail, telefone e similaridade fuzzy de nome. Processamento assíncrono em fila, soft delete com restauração e exportação filtrada.

Para quem é

• Equipes de marketing que recebem listas de eventos, feiras e capturas de landing pages e precisam higienizar antes de disparar campanhas.
• Equipes comerciais que importam leads de diferentes origens (CRM antigo, planilhas, parceiros) e querem uma fonte única limpa.
• Agências que consolidam bases de múltiplos clientes com qualidade garantida antes de entregar.
• Operações de SDR/Prospect que precisam de contatos normalizados (DDD correto, UF padronizada) para discagem e abordagem.

O que você pode fazer

Ingestão e Importação

• Upload de CSV: arquivos com até milhares de linhas, com detecção automática de encoding (UTF-8, ISO-8859-1, Windows-1252) e delimitador (vírgula, ponto-e-vírgula, tabulação).
• Mapeamento automático de colunas: identifica nome, e-mail, telefone, cidade, UF, categoria, site e Instagram a partir dos cabeçalhos.
• Processamento em fila: importações grandes são fatiadas em chunks (padrão 1.000 linhas) e processadas em background sem travar a interface.
• Log de erros linha a linha: cada falha é registrada com número da linha, motivo e dado original, sem interromper o restante da importação.

Normalização

• E-mail: lowercase e remoção de espaços; marcação de inválidos.
• Telefone: formato E.164 com extração de DDD para números brasileiros.
• Estado: conversão para UF de 2 letras (27 estados brasileiros reconhecidos).
• Nome: forma sem acentos para uso em deduplicação; nome original preservado para exibição.
• Categoria, site e Instagram: padronização e limpeza.

Score de Qualidade

• Pontuação 0-100 por contato com pesos configuráveis por campo:
• E-mail: 30 pontos
• Telefone: 25 pontos
• Nome: 20 pontos
• Cidade: 10 pontos
• Estado: 10 pontos
• Website: 5 pontos
• Pesos ajustáveis em Configurações para priorizar campos mais relevantes ao seu negócio.

Deduplicação

• Por e-mail normalizado: duplicata exata.
• Por telefone E.164: mesmo número em formatos diferentes é unificado.
• Fuzzy por nome + cidade: similaridade Levenshtein com threshold configurável (padrão 85%).
• Histórico de dedup: cada fusão registra quem foi mantido, quem foi descartado e por qual estratégia.

Gestão e Exportação

• Soft delete com restauração: contatos excluídos vão para lixeira e podem ser recuperados.
• Exportação filtrada: exporte por status, UF, categoria ou por importação específica, com BOM UTF-8 para abrir corretamente no Excel.
• Busca e filtros: localize contatos por qualquer campo normalizado.
• Edição individual: corrija campos específicos com auditoria de alterações.

Como começar

1. Acesse Dashboard → Contact Leads → Importações.
2. Clique em Nova Importação e arraste seu arquivo CSV.
3. Confirme o mapeamento sugerido de colunas (ou ajuste manualmente).
4. Configure pesos de score e threshold de dedup em Configurações (opcional, o padrão funciona para 90% dos casos).
5. Acompanhe o progresso em tempo real; ao terminar, revise os erros e contatos duplicados.
6. Use a aba Contatos para filtrar, editar e exportar sua base limpa.

Tutoriais

Tutorial 1: Primeira importação de CSV

Objetivo: importar sua primeira planilha de contatos e revisar o resultado. Passos:

1. Vá em Contact Leads → Importações → Nova Importação.
2. Selecione um arquivo CSV (qualquer encoding — detecta automaticamente).
3. Revise o preview com 5 linhas e confirme o mapeamento de colunas.
4. Clique em Importar. A fila processa em background.
5. Ao concluir, acesse o log da importação e revise: linhas processadas, duplicatas detectadas, erros.
6. Vá para a aba Contatos para ver sua base consolidada.

Tutorial 2: Ajustar pesos de score

Objetivo: adaptar o score 0-100 ao seu modelo de negócio. Passos:

1. Abra Configurações → Score de Qualidade.
2. Aumente o peso de Telefone se seu canal principal é WhatsApp, ou E-mail se é campanha por newsletter.
3. Os pesos totais não precisam somar 100 — o score é recalculado proporcionalmente.
4. Salve. Contatos novos recebem o novo cálculo; use o botão Recalcular Score para aplicar na base existente.

Tutorial 3: Deduplicação em base existente

Objetivo: limpar duplicatas que já estão no sistema. Passos:

1. Em Configurações → Deduplicação, defina o threshold fuzzy (85% é o padrão recomendado).
2. Vá em Contatos e clique em Deduplicar Agora.
3. O sistema analisa por e-mail, telefone e similaridade de nome+cidade.
4. Revise a prévia com pares sugeridos antes de confirmar.
5. Ao confirmar, os descartados vão para a lixeira (recuperáveis por 30 dias).

Tutorial 4: Exportar lista segmentada

Objetivo: gerar CSV filtrado para uma campanha específica. Passos:

1. Em Contatos, aplique filtros (ex.: UF = SP, categoria = Cliente, score ≥ 70).
2. Clique em Exportar.
3. O arquivo sai em UTF-8 com BOM (abre direto no Excel sem corromper acentos).
4. Use em campanhas de e-mail, SMM ou prospecção.

Tutorial 5: Restaurar contato excluído

Objetivo: recuperar um contato que foi para a lixeira. Passos:

1. Vá em Contatos → Filtrar por Status → Excluídos.
2. Localize o contato e clique em Restaurar.
3. O contato volta ativo; o score é mantido.

Integrações com outros plugins

• Eventos emitidos (consumíveis pelos plugins Automation, SMM, Prospect, Campaign):
• contact-leads.imported — nova importação concluída.
• contact-leads.record.created — contato criado.
• contact-leads.record.updated — contato atualizado.
• contact-leads.record.deleted — contato em soft delete.
• contact-leads.deduplicated — dedup executada.
• Campaign/SMM: consuma a base como origem de campanhas segmentadas.
• Automation: crie fluxos acionados por contact-leads.imported (ex.: iniciar sequência de e-mails após nova importação).
• Prospect: use os contatos normalizados como ponto de partida para enriquecimento com dados sociais.

Perguntas frequentes

1. Qual o tamanho máximo de CSV suportado? Não há limite rígido — arquivos grandes são processados em chunks de 1.000 linhas via fila. Importações com 100 mil+ linhas são suportadas.

2. Meu CSV está com acentos corrompidos, ainda funciona? Sim. O sistema detecta automaticamente UTF-8, ISO-8859-1 (latin1) e Windows-1252, convertendo para UTF-8 na ingestão.

3. O que acontece com erros de linha na importação? São registrados em log detalhado (linha, motivo, dado original) sem interromper o resto da importação. Você pode baixar o log de erros após a conclusão.

4. Como funciona a deduplicação fuzzy? Compara nome+cidade com similaridade Levenshtein. O threshold padrão é 85%, ajustável em Configurações. Entradas acima do limiar são consideradas duplicatas.

5. Posso recuperar um contato excluído? Sim. O soft delete mantém o contato na lixeira por 30 dias. Use a aba Contatos com filtro Excluídos e clique em Restaurar.

6. Dados são compartilhados entre tenants? Não. Isolamento multi-tenant total por tenant_id. Cada revendedor, empresa ou usuário vê apenas seus próprios leads.

7. Posso reimportar o mesmo arquivo? Sim. Os contatos duplicados são identificados no próprio pipeline e não geram registros repetidos.

8. Quais formatos de telefone são aceitos? Qualquer formato brasileiro — com ou sem DDI, com ou sem parênteses, com ou sem traços. O sistema normaliza tudo para E.164 (+55DDNÚMERO).

Glossário

• E.164: padrão internacional de telefone (ex.: +5511987654321).
• Fuzzy matching: comparação por similaridade, não exata.
• Levenshtein: algoritmo que mede distância entre strings.
• UF: Unidade Federativa (SP, RJ, MG…).
• Chunk: bloco de linhas processado por vez na fila assíncrona.
• Soft delete: exclusão reversível (lixeira), diferente do hard delete permanente.

Limitações e avisos

• Deduplicação fuzzy com threshold muito baixo (<70%) pode unificar contatos distintos — teste em base pequena antes.
• Importações com milhões de linhas podem levar minutos; acompanhe via log.
• O plugin não faz enriquecimento externo (CNPJ, SMTP, HLR) — é pipeline local de higienização. Enriquecimento está no roadmap.
• Exportação respeita o filtro aplicado no momento; revise antes de gerar arquivo para campanha.

Relacionados

• Campaign — disparo de campanhas para listas higienizadas.
• SMM — alcance em redes sociais para contatos com Instagram preenchido.
• Prospect — enriquecimento social dos contatos.
• Automation — fluxos acionados por eventos de importação.
• Files — armazenamento dos CSVs originais e exportações.