github-actions[bot]
37dbd94596
Created by Github action Co-authored-by: github-actions <github-actions@twenty.com>
268 lines
9.8 KiB
Plaintext
268 lines
9.8 KiB
Plaintext
---
|
|
title: Prepare seus arquivos CSV
|
|
description: Guia completo passo a passo para formatar seus dados para importação no Twenty.
|
|
---
|
|
|
|
## Visão Geral
|
|
|
|
Este guia orienta você na preparação do seu arquivo CSV para uma importação bem-sucedida. Siga estas etapas para evitar erros.
|
|
|
|
## Etapa 1: Verifique os requisitos do arquivo
|
|
|
|
Antes de começar, verifique se o seu arquivo atende a estes requisitos:
|
|
|
|
| Requisito | Detalhes |
|
|
| --------------------- | ----------------------------- |
|
|
| **Formato** | CSV, XLSX ou XLS |
|
|
| **Limite de tamanho** | 10.000 registros por arquivo |
|
|
| **Codificação** | UTF-8 recomendado |
|
|
| **Estrutura** | Um tipo de objeto por arquivo |
|
|
|
|
<Note>Para conjuntos de dados maiores que 10.000 registros, divida em vários arquivos ou use a [importação via API](/l/pt/user-guide/data-migration/how-tos/import-data-via-api).</Note>
|
|
|
|
## Etapa 2: Baixe o arquivo de exemplo
|
|
|
|
**Esta é a etapa mais importante.** O arquivo de exemplo mostra os nomes exatos das colunas e o formato que o Twenty espera.
|
|
|
|
1. Navegue até qualquer objeto (Pessoas, Empresas, etc.)
|
|
2. Clique em **⋮** → **Importar registros**
|
|
3. Clique em **Baixar arquivo de exemplo**
|
|
4. Use este arquivo como seu modelo
|
|
|
|
<Note>**Dica de especialista:** Em vez disso, exporte alguns registros existentes. Isso fornece exemplos reais de como os dados devem ser formatados, e os nomes das colunas serão mapeados automaticamente durante a importação.</Note>
|
|
|
|
## Etapa 3: Remova valores duplicados
|
|
|
|
O Twenty impõe unicidade em determinados campos. Duplicados causarão erros de importação.
|
|
|
|
| Objeto | Campos exclusivos |
|
|
| -------------------------- | ------------------------------------------------------------------ |
|
|
| **Pessoas** | `id`, `email` |
|
|
| **Empresas** | `id`, `domain` |
|
|
| **Objetos personalizados** | `id`, além de qualquer campo que você tenha marcado como exclusivo |
|
|
|
|
**Antes de importar:**
|
|
|
|
1. Ordene sua planilha pelo campo exclusivo (email ou domínio)
|
|
2. Remova ou mescle linhas duplicadas
|
|
3. Verifique se há duplicados que já existem no Twenty
|
|
|
|
<Warning>**Registros excluídos logicamente contam para a unicidade.** Registros em Menu de Comando → Ver registros excluídos causarão erros de duplicação. Exclua-os permanentemente ou restaure e atualize-os.</Warning>
|
|
|
|
## Etapa 4: Formate corretamente cada tipo de campo
|
|
|
|
Tipos de campo diferentes exigem formatos específicos. Aqui está a referência completa:
|
|
|
|
### Campos de texto
|
|
|
|
* Nenhuma formatação especial é necessária
|
|
* Espaços no início/fim são automaticamente removidos
|
|
|
|
### Campos de email
|
|
|
|
* Deve estar em um formato de email válido: `name@domain.com`
|
|
* Deve ser exclusivo (sem duplicados no arquivo ou no Twenty)
|
|
* Para emails adicionais, use este formato na coluna **Emails / Additional Emails**:
|
|
|
|
```
|
|
["jane@twenty.com","jane.doe@twenty.com"]
|
|
```
|
|
|
|
### Campos de domínio
|
|
|
|
* **Formato recomendado**: `https://domain.com`
|
|
* Isso corresponde ao formato usado pela sincronização de caixa de correio/calendário (evita duplicados)
|
|
* Preencha ambas as colunas:
|
|
* **Domain / Domain Label**: `domain.com`
|
|
* **Domain / Domain URL**: `https://domain.com`
|
|
* Deve ser exclusivo dentro do seu arquivo e no Twenty
|
|
|
|
### Campos de telefone
|
|
|
|
Telefone é um **campo aninhado** que requer várias colunas:
|
|
|
|
| Coluna | Exemplo |
|
|
| --------------------------------------- | ------------ |
|
|
| **Phones / Primary Phone Number** | `4159095555` |
|
|
| **Phones / Primary Phone Country Code** | `US` |
|
|
| **Phones / Primary Phone Calling Code** | `+1` |
|
|
|
|
### Campos de Endereço
|
|
|
|
Endereço é um **campo aninhado** com várias colunas (algumas podem ficar em branco):
|
|
|
|
* **Endereço / Endereço 1**: Linha 1 do endereço
|
|
* **Endereço / Endereço 2**: Linha 2 do endereço (opcional)
|
|
* **Endereço / Cidade**: Nome da cidade
|
|
* **Endereço / Estado**: Estado ou província
|
|
* **Endereço / País**: Nome do país
|
|
* **Endereço / Código Postal**: Código Postal/CEP
|
|
|
|
### Campos de Data
|
|
|
|
Use formatação consistente em todo o seu arquivo:
|
|
|
|
* `YYYY-MM-DD` (recomendado): `2024-03-15`
|
|
* ISO 8601: `2024-03-15T10:30:00Z`
|
|
|
|
### Campos Numéricos
|
|
|
|
* Apenas números (sem texto)
|
|
* Use ponto para decimais: `1234.56`
|
|
* Sem separadores de milhares (não `1,234.56`)
|
|
|
|
### Campos de Moeda
|
|
|
|
Moeda é um **campo aninhado** que requer duas colunas que **ambas devem ser preenchidas**:
|
|
|
|
| Coluna | Exemplo |
|
|
| ----------------- | --------- |
|
|
| **Valor / Valor** | `1234.56` |
|
|
| **Valor / Moeda** | `USD` |
|
|
|
|
### Campos Booleanos
|
|
|
|
Use maiúsculas: `TRUE` ou `FALSE`
|
|
|
|
<Warning>`true` ou `false` em minúsculas não funcionam.</Warning>
|
|
|
|
### Campos de Seleção
|
|
|
|
Use o **nome da API** da opção, não o rótulo de exibição.
|
|
|
|
**Como encontrar nomes da API:**
|
|
|
|
1. Vá para **Configurações → Modelo de Dados**
|
|
2. Selecione o objeto e o campo
|
|
3. Ative o **Modo Avançado** (alternador no canto inferior direito)
|
|
4. Copie o nome da API (por exemplo, `OPTION_1`, não "Option 1")
|
|
|
|
<Note>Novas opções de seleção não são criadas automaticamente. Adicione-as em **Configurações → Modelo de Dados** antes de importar.</Note>
|
|
|
|
### Campos de Seleção Múltipla
|
|
|
|
Use os nomes da API no formato de array:
|
|
|
|
```
|
|
["VALUE1","VALUE2"]
|
|
```
|
|
|
|
### Campos de Array
|
|
|
|
Use o formato de array JSON:
|
|
|
|
```
|
|
["value1","value2"]
|
|
```
|
|
|
|
### Campos de Classificação
|
|
|
|
Use o formato: `RATING_1`, `RATING_2`, `RATING_3`, `RATING_4` ou `RATING_5`
|
|
|
|
### Campos de Links/URL
|
|
|
|
Preencha ambas as colunas:
|
|
|
|
* **Links / Rótulo do Link**: `Twenty`
|
|
* **Links / URL do Link**: `https://twenty.com`
|
|
|
|
Para links secundários, use a coluna **Links / Links Secundários**:
|
|
|
|
```
|
|
[{"url":"https://twenty.com","label":"Twenty"}]
|
|
```
|
|
|
|
### Campos JSON
|
|
|
|
Use um formato JSON válido:
|
|
|
|
```
|
|
{"key":"value","key2":"value2"}
|
|
```
|
|
|
|
### Campos de ID
|
|
|
|
* **Opcional**: a Twenty gera IDs automaticamente se não forem fornecidos
|
|
* **Formato**: UUID (por exemplo, `c776ee49-f608-4a77-8cc8-6fe96ae1e43f`)
|
|
* **Caso de uso**: Inclua o ID para atualizar registros existentes em vez de criar novos
|
|
|
|
## Etapa 5: Adicione Colunas de Relação (se estiver vinculando registros)
|
|
|
|
Para vincular registros a outros objetos (por exemplo, Pessoas a Empresas), adicione uma coluna com o identificador exclusivo do registro relacionado.
|
|
|
|
**Exemplo**: Vinculando Pessoas a Empresas
|
|
|
|
Adicione uma coluna ao seu CSV de Pessoas:
|
|
|
|
```
|
|
firstName,lastName,email,companyDomain
|
|
John,Smith,john@acme.com,https://acme.com
|
|
Jane,Doe,jane@widgets.co,https://widgets.co
|
|
```
|
|
|
|
**Regras importantes para relações:**
|
|
|
|
* O registro pai já deve existir na Twenty
|
|
* Use o formato **URL de domínio** (`https://domain.com`), não o rótulo
|
|
* Mapeie apenas UM identificador exclusivo (não inclua `companyId` E `companyDomain`)
|
|
* Para Membros do Workspace, use o **email** deles (não o nome)
|
|
|
|
<Warning>
|
|
**A ordem de importação é importante!**
|
|
|
|
Importe o lado "um" antes do lado "muitos":
|
|
1. **Empresas** primeiro
|
|
2. **Pessoas** em segundo (com referência à empresa)
|
|
3. **Oportunidades** em terceiro
|
|
|
|
O registro pai deve existir antes de você poder referenciá-lo.
|
|
</Warning>
|
|
|
|
Veja [Como importar relações](/l/pt/user-guide/data-migration/how-tos/import-relations-between-objects-via-csv) para instruções detalhadas.
|
|
|
|
## Etapa 6: Garanta que os campos existam na Twenty
|
|
|
|
A importação cria registros, não campos. Todos os campos que você deseja importar já devem existir no seu modelo de dados.
|
|
|
|
**Antes de importar:**
|
|
|
|
1. Vá para **Configurações → Modelo de Dados**
|
|
2. Selecione o seu objeto
|
|
3. Crie todos os campos personalizados necessários
|
|
4. Anote os nomes exatos dos campos (eles devem corresponder aos cabeçalhos das suas colunas)
|
|
|
|
## Etapa 7: Lista de Verificação Final
|
|
|
|
Antes de enviar seu arquivo, verifique:
|
|
|
|
<Check>O arquivo está no formato CSV, XLSX ou XLS</Check>
|
|
<Check>O arquivo tem menos de 10.000 registros</Check>
|
|
<Check>A codificação é UTF-8</Check>
|
|
<Check>Sem emails duplicados (para Pessoas) ou domínios (para Empresas)</Check>
|
|
<Check>As datas usam formato consistente em todo o arquivo</Check>
|
|
<Check>Os domínios usam o formato `https://domain.com`</Check>
|
|
<Check>Os campos booleanos usam `TRUE` ou `FALSE` (maiúsculas)</Check>
|
|
<Check>Os campos de Seleção usam nomes da API, não rótulos de exibição</Check>
|
|
<Check>Todos os campos personalizados existem em Configurações → Modelo de Dados</Check>
|
|
<Check>Registros pai importados antes dos registros filho</Check>
|
|
<Check>As colunas de relação referenciam registros existentes</Check>
|
|
|
|
## Erros Comuns a Evitar
|
|
|
|
| Erro | Solução |
|
|
| ----------------------------------------------- | ----------------------------------------------- |
|
|
| Usar `true` em vez de `TRUE` | Valores booleanos devem estar em maiúsculas |
|
|
| Usar rótulos de exibição para campos de Seleção | Encontre e use os nomes da API em Configurações |
|
|
| Importar Pessoas antes de Empresas | Sempre importe os objetos pai primeiro |
|
|
| Falta o código de moeda nos campos de Moeda | Preencha as colunas Valor e Moeda |
|
|
| Formato de domínio incorreto | Use `https://domain.com` de forma consistente |
|
|
| Mapeando vários campos exclusivos para relações | Mapeie apenas UM (domínio OU ID, não ambos) |
|
|
|
|
## Próximos Passos
|
|
|
|
Seu arquivo está pronto! Agora:
|
|
|
|
* [Importar Empresas](/l/pt/user-guide/data-migration/how-tos/import-companies-via-csv) (importe-as primeiro)
|
|
* [Importar Contatos](/l/pt/user-guide/data-migration/how-tos/import-contacts-via-csv)
|
|
* [Corrigir quaisquer erros de importação](/l/pt/user-guide/data-migration/how-tos/fix-import-errors)
|