Saltar para o conteúdo principal

​
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:
RequisitoDetalhes
FormatoCSV, XLSX ou XLS
Limite de tamanho10.000 registros por arquivo
CodificaçãoUTF-8 recomendado
EstruturaUm tipo de objeto por arquivo
Para conjuntos de dados maiores que 10.000 registros, divida em vários arquivos ou use a importação via API.

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

​
Etapa 3: Remova valores duplicados

O Twenty impõe unicidade em determinados campos. Duplicados causarão erros de importação.
ObjetoCampos exclusivos
Pessoasid, email
Empresasid, domain
Objetos personalizadosid, 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
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.

​
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:
ColunaExemplo
Phones / Primary Phone Number4159095555
Phones / Primary Phone Country CodeUS
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
  • MM/DD/YYYY: 03/15/2024
  • DD/MM/YYYY: 15/03/2024
  • 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:
ColunaExemplo
Valor / Valor1234.56
Valor / MoedaUSD

​
Campos Booleanos

Use maiúsculas: TRUE ou FALSE
true ou false em minúsculas não funcionam.

​
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”)
Novas opções de seleção não são criadas automaticamente. Adicione-as em Configurações → Modelo de Dados antes de importar.

​
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)
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.
Veja Como importar relações 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:
O arquivo está no formato CSV, XLSX ou XLS
O arquivo tem menos de 10.000 registros
A codificação é UTF-8
Sem emails duplicados (para Pessoas) ou domínios (para Empresas)
As datas usam formato consistente em todo o arquivo
Os domínios usam o formato https://domain.com
Os campos booleanos usam TRUE ou FALSE (maiúsculas)
Os campos de Seleção usam nomes da API, não rótulos de exibição
Todos os campos personalizados existem em Configurações → Modelo de Dados
Registros pai importados antes dos registros filho
As colunas de relação referenciam registros existentes

​
Erros Comuns a Evitar

ErroSolução
Usar true em vez de TRUEValores booleanos devem estar em maiúsculas
Usar rótulos de exibição para campos de SeleçãoEncontre e use os nomes da API em Configurações
Importar Pessoas antes de EmpresasSempre importe os objetos pai primeiro
Falta o código de moeda nos campos de MoedaPreencha as colunas Valor e Moeda
Formato de domínio incorretoUse https://domain.com de forma consistente
Mapeando vários campos exclusivos para relaçõesMapeie apenas UM (domínio OU ID, não ambos)

​
Próximos Passos

Seu arquivo está pronto! Agora: