Skip to main content

​
Importação de contatos via CSV

Importe contatos em massa para um workspace a partir de um arquivo CSV. A importação é executada em segundo plano: o arquivo é enviado para o armazenamento de objetos, um worker faz o parsing e a ingestão em blocos, e a interface consulta o progresso em tempo real.

​
Visão geral

  1. Na página Contatos, clique em Importar CSV.
  2. Escolha um ou mais arquivos .csv no disco (selecione múltiplos arquivos para enfileirá-los sequencialmente).
  3. Cada arquivo é enviado, colocado na fila de processamento, e você verá Uploading → Queued → Processing → Complete ✓ com uma barra de progresso por arquivo e contadores em tempo real.
  4. Linhas que falharem são resumidas com um botão Ver erros — revise-as, corrija na sua planilha e reenvie o arquivo corrigido.

​
Colunas obrigatórias

​
Colunas opcionais

Os cabeçalhos das colunas são comparados sem diferenciar maiúsculas/minúsculas. Colunas que você não informar são ignoradas — colunas extras são simplesmente descartadas com segurança.

​
Formato do telefone

Todos os números de telefone devem ser normalizados para E.164 — um formato internacional que começa com +, o código do país e apenas dígitos (sem espaços, hífens ou parênteses). Dica: se a sua planilha remover o + inicial ou adicionar notação científica, formate a coluna de telefone como Texto antes de exportar.

​
Exemplo de CSV

Faça o download deste exemplo como ponto de partida e substitua as linhas pelos seus próprios contatos.

​
Limites

  • Tamanho do arquivo: 10 MB por arquivo.
  • Número de linhas: máximo recomendado de 50.000 linhas por arquivo. Divida listas maiores em vários arquivos e envie-os de uma só vez — eles serão processados sequencialmente.
  • Codificação: UTF-8. Exporte do Excel como “CSV UTF-8 (separado por vírgulas)” no macOS, ou “CSV (separado por vírgulas) (*.csv)” com codificação UTF-8 no Windows.
  • Quebras de linha: \n ou \r\n — ambos são suportados.
  • Uso de aspas: aspas padrão de CSV — envolva um campo em "…" para incluir vírgulas ou quebras de linha, e escape uma aspa dentro do campo como "".

​
Solução de problemas

“missing name” / “missing phone” Falta um valor obrigatório na linha. Verifique se a linha de cabeçalho usa name e phone (ou um dos aliases listados) e se todas as linhas de dados têm ambos os campos preenchidos. “invalid phone format” O número de telefone não pôde ser normalizado para E.164. Adicione um código de país com + na frente (ex.: +39…, +1…) ou remova caracteres que não são dígitos e que quebram o parsing. “duplicate phone number (contact already exists)” Outro contato no workspace já possui esse número de telefone. As importações não sobrescrevem contatos existentes — exclua ou atualize o registro existente primeiro, se precisar substituí-lo. Importação parada em “Queued” O worker em segundo plano está temporariamente atrasado com os jobs. A interface se atualizará automaticamente quando o worker assumir o job — deixe a página aberta, ou verifique novamente mais tarde; o estado do job é persistido no servidor. “upload failed: 413” Seu arquivo excede o limite de 10 MB. Divida-o em arquivos menores e envie-os juntos.

​
Como funciona

Por baixo dos panos:
  1. POST /api/contacts/import aceita dados de formulário multipart, valida o arquivo e o envia para o bucket de armazenamento de objetos contact-imports em {workspaceId}/{importId}/{filename}.
  2. Uma linha é inserida em public.contact_import_jobs com status pending, e um job de outbox contacts.import.process é enfileirado.
  3. O worker assume o job, baixa o arquivo, faz o parsing das linhas, normaliza os telefones e insere os contatos em blocos de 100 — atualizando processed_rows, successful_rows, failed_rows e error_report depois de cada bloco.
  4. GET /api/contacts/import/:id retorna o estado atual para a interface consultar.
Números de telefone duplicados são reportados como linhas com falha (o contato existente não é modificado) — isso mantém os reenvios seguros e idempotentes.