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

# Importação de contatos via CSV

> Importe contatos em massa a partir de um arquivo CSV — formato, limites e solução de problemas.

# 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

| Coluna  | Obrigatória | Observações                                                          |
| ------- | ----------- | -------------------------------------------------------------------- |
| `name`  | Sim         | Nome de exibição. Aliases: `display_name`, `full_name`.              |
| `phone` | Sim         | Número de telefone. Aliases: `phone_e164`, `phone_number`, `mobile`. |

## Colunas opcionais

| Coluna  | Observações                                                            |
| ------- | ---------------------------------------------------------------------- |
| `tags`  | Lista separada por ponto e vírgula, ex.: `vip;newsletter;2026-winter`. |
| `email` | E-mail do contato (armazenado no registro do contato).                 |

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).

| Entrada bruta       | Normalizado                          |
| ------------------- | ------------------------------------ |
| `+393289214993`     | `+393289214993`                      |
| `+1 (555) 123-4567` | `+15551234567`                       |
| `393289214993`      | `+393289214993`                      |
| `555-123-4567`      | ❌ código do país ausente — rejeitado |

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

```csv theme={null}
name,phone,tags,email
Alice Rossi,+393289214993,vip;newsletter,alice@example.com
Bob Meyer,+4915112345678,partners,bob@example.com
Carla Díaz,+34911234567,vip,
Derek Okafor,+2348011234567,,
```

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.