snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/l/pt/user-guide/data-migration/capabilities/error-handling.mdx

@@ -0,0 +1,76 @@
+---
+title: Tratamento de erros e validação
+description: Revise e corrija os erros de importação diretamente na IU antes de confirmar.
+---
+
+import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
+
+## Validação pré-importação
+
+Depois de carregar o seu ficheiro e mapear os campos, o Twenty valida os seus dados **antes** de os importar. Isto permite detetar e corrigir erros sem afetar os seus dados existentes.
+
+## Como Funciona
+
+1. **Carregue** o seu ficheiro CSV
+2. **Mapeie** as suas colunas para os campos do Twenty
+3. **Revise** os potenciais erros destacados em amarelo
+4. **Corrija os erros** diretamente na IU
+5. **Confirme** a importação
+
+<VimeoEmbed videoId="1145273857" title="Demonstração em vídeo" />
+
+## Apresentação de erros
+
+As linhas com erros são destacadas em **amarelo**. Pode:
+
+* **Edite a célula diretamente** para corrigir o erro
+* **Remova a linha** para a ignorar por completo
+
+Esta edição em linha poupa tempo — não é necessário voltar à sua folha de cálculo, corrigir os erros e voltar a carregar.
+
+## Tipos de erro comuns
+
+### Valores duplicados
+
+**Causa**: Um campo único (email, domínio) já existe no Twenty ou aparece duas vezes no seu ficheiro.
+
+**Correção**:
+
+* Edite o valor duplicado na IU de importação
+* Remova uma das linhas duplicadas
+
+Consulte [Restrições de unicidade](/l/pt/user-guide/data-migration/capabilities/uniqueness-constraints) para mais detalhes sobre como a unicidade é aplicada.
+
+### Formato inválido
+
+**Causa**: Os dados não correspondem ao formato esperado (por exemplo, email inválido, formato de data incorreto).
+
+**Correção**: Edite a célula para usar o formato correto.
+
+Consulte [Mapeamento de Campos](/l/pt/user-guide/data-migration/capabilities/field-mapping) para o formato esperado de cada tipo de campo.
+
+### Campos obrigatórios ausentes
+
+**Causa**: Um campo obrigatório está vazio.
+
+**Correção**: Introduza um valor no campo obrigatório ou remova a linha.
+
+### Relação não encontrada
+
+**Causa**: O registo referenciado não existe (por exemplo, um domínio de Empresa que não foi importado).
+
+**Correção**:
+
+* Importe primeiro os registos pai
+* Ou corrija o valor de referência
+
+Consulte [Importar relações](/l/pt/user-guide/data-migration/capabilities/import-relations) para conhecer a ordem correta de importação e como ligar registos.
+
+## Dicas para reduzir erros
+
+1. **Baixe o modelo** para ver o formato esperado antes de importar o seu arquivo
+2. **Limpe os seus dados** primeiro na folha de cálculo
+3. **Importe os ficheiros na ordem correta** para importar relações (Empresas → Pessoas → Oportunidades)
+4. **Teste com pequenos lotes** antes da importação completa
+5. **Verifique se existem duplicados** antes de carregar
+6. **Limite de cada arquivo a 10.000 registros**

packages/twenty-docs/l/pt/user-guide/data-migration/capabilities/field-mapping.mdx

@@ -0,0 +1,198 @@
+---
+title: Mapeamento de Campos
+description: Como o mapeamento de campos funciona durante a importação de dados.
+---
+
+import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
+
+## Como funciona o mapeamento de campos
+
+Ao fazer upload de um arquivo, a Twenty analisa as suas colunas e tenta associá-las aos campos existentes.
+
+### Mapeamento automático
+
+A Twenty tenta associar as colunas com base em:
+
+* Nomes dos cabeçalhos das colunas (correspondências exatas ou semelhantes)
+* Detecção de tipo de dados (datas, números, e-mails)
+* Padrões comuns de campos
+
+<Note>**Dica rápida:** Exporte algumas linhas do objeto que você deseja importar. O arquivo exportado terá exatamente os nomes de coluna que a Twenty espera, facilitando o mapeamento automático durante a importação.</Note>
+
+### Opções de mapeamento manual
+
+Para cada coluna, você pode:
+
+* **Mapear para um campo**: selecione o campo correspondente da Twenty em um menu suspenso
+* **Não mapear**: ignore a coluna completamente (os dados não serão importados)
+
+<Note>**Os campos devem existir antes da importação.** A importação cria registros, não campos. Crie campos personalizados em **Configurações → Modelo de Dados** antes de importar.</Note>
+
+## Compatibilidade de tipos de campo
+
+Todos os tipos de campos disponíveis no Modelo de Dados são compatíveis com a importação.
+
+Você também pode importar valores de `id` para atribuir um ID específico a novos registros ou atualizar os existentes.
+
+<img src="/images/user-guide/fields/all-field-types.png" style={{width:'100%'}} />
+
+## Requisitos de formato de dados
+
+<Note>**Alguns campos têm sintaxe especial.** Recomendamos baixar o arquivo de exemplo antes de preparar sua importação para ver a sintaxe esperada para cada tipo de campo.</Note>
+
+### 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
+* **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 Array
+
+Use o seguinte formato:
+
+```
+["value1","value2"]
+```
+
+### Campos Booleanos
+
+Use `TRUE` ou `FALSE` (em maiúsculas) - não `true` ou `false`
+
+### Campos de Moeda
+
+Moeda é um campo aninhado com duas colunas que **ambas devem ser preenchidas**:
+
+* **Valor / Valor**: O valor numérico (por exemplo, `1234.56`)
+* **Valor / Moeda**: O código da moeda (por exemplo, `USD`, `EUR`)
+
+### Campos de Data
+
+Formatos suportados:
+
+* `YYYY-MM-DD` (recomendado)
+* `MM/DD/YYYY`
+* `DD/MM/YYYY`
+* Formato ISO 8601
+
+### Campos de Domínio
+
+* Recomenda-se usar o formato `https://domain.com` para evitar a criação de duplicatas, pois esse é o formato usado para Empresas criadas pelas sincronizações da caixa de correio e do calendário
+* Um `Domain Label` e uma `Domain URL` podem ser preenchidos: a boa prática é preencher `domain.com` no rótulo e `https://domain.com` na URL
+* Domínios devem ser exclusivos no objeto Empresas
+* **Os domínios devem ser exclusivos dentro do arquivo a ser importado**
+
+### Campos de E-mail
+
+* Deve estar em um formato de e-mail válido
+* Os e-mails devem ser exclusivos dentro do objeto Pessoas
+* **Os e-mails devem ser exclusivos dentro do arquivo a ser importado**
+* Para e-mails adicionais: use **E-mails / E-mail principal** para o e-mail principal e **E-mails / E-mails adicionais** com este formato:
+
+```
+["jane@twenty.com","jane.doe@twenty.com"]
+```
+
+### Campos de ID
+
+Especificar um `id` durante a importação é opcional. A Twenty gera um automaticamente se não for fornecido.
+
+Casos de uso para mapear uma coluna `id`:
+
+* **Definir um ID específico**: escolha o UUID para registros recém-criados
+* **Atualizar registros existentes**: faça a correspondência com registros existentes para atualizá-los, em vez de criar duplicatas. Nesse caso, recomenda-se não mapear os outros campos exclusivos: mapear apenas um campo exclusivo garante uma importação mais tranquila.
+
+<Note>Se você fornecer um `id`, ele deve estar no formato UUID (por exemplo, `c776ee49-f608-4a77-8cc8-6fe96ae1e43f`).</Note>
+
+### Campos JSON
+
+Use um formato JSON válido:
+
+```
+{"key":"value","key2":"value2"}
+```
+
+### Campos de Links
+
+Semelhante aos campos de Domínio:
+
+* Preencha as colunas de rótulo e URL: **Links / URL do link** e **Links / Rótulo do link**
+* Use o formato completo de URL: `https://example.com`
+* Para links secundários, use a coluna **Links / Links Secundários** com este formato:
+
+```
+[{"url":"https://twenty.com","label":"Twenty"}]
+```
+
+### Campos de Seleção Múltipla
+
+Use os **nomes da API** (não os rótulos de exibição) no seguinte formato:
+
+```
+["VALUE1","VALUE2"]
+```
+
+Veja [aqui](#finding-api-names-for-select-fields) onde encontrar os nomes da API.
+
+<Note>Novas opções de seleção não serão criadas automaticamente pela importação. Elas devem ser adicionadas em **Configurações → Modelo de Dados** antes de importar.</Note>
+
+<Warning>
+**Importar sobrescritas; ele não adiciona.**
+
+Se um registro já tiver `VALUE2` e `VALUE3` selecionados e você importar `["VALUE1"]`, o registro terá apenas `VALUE1` após a importação. As seleções anteriores são substituídas, não mescladas.
+</Warning>
+
+### Campos Numéricos
+
+* Apenas números
+* Decimais usam ponto: `1234.56`
+* Sem separadores de milhares
+
+### Campos de Telefone
+
+Telefone é um campo aninhado com várias colunas que devem ser preenchidas
+
+* **Telefones / Número de telefone principal**: O número de telefone (por exemplo, `4159095555`)
+* **Telefones / Código do país do telefone principal**: Código do país (por exemplo, `US`)
+* **Telefones / Código de chamada do telefone principal**: Código de discagem (por exemplo, `+1`)
+
+### Campos de Classificação
+
+Use o formato de nome da API: `RATING_1`, `RATING_2`, `RATING_3`, `RATING_4`, `RATING_5`
+
+### Campos de Relação
+
+Consulte nosso artigo dedicado: [Importar relações entre objetos](/l/pt/user-guide/data-migration/capabilities/import-relations)
+
+### Campos de Seleção
+
+Use o **nome da API** da opção (não o rótulo de exibição):
+
+```
+VALUE1
+```
+
+Veja [aqui](#finding-api-names-for-select-fields) onde encontrar os nomes da API.
+<Note>Novas opções de seleção não serão criadas automaticamente pela importação. Elas devem ser adicionadas em **Configurações → Modelo de Dados** antes de importar.</Note>
+
+### Campos de Texto
+
+* Nenhuma formatação especial é necessária
+* Espaços no início e no fim são removidos
+
+## Encontrar Nomes da API
+
+Para campos Select, Multi-Select e Array com opções predefinidas, você deve usar os **nomes da API**, não os rótulos 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 da página de configurações)
+4. Visualize o nome da API de cada opção
+
+<VimeoEmbed videoId="1144910809" title="Demonstração em vídeo" />

packages/twenty-docs/l/pt/user-guide/data-migration/capabilities/file-formats.mdx

@@ -0,0 +1,48 @@
+---
+title: Formatos de Ficheiro Suportados
+description: Formatos de ficheiro suportados para importação de dados no Twenty.
+---
+
+## Formatos Suportados
+
+O Twenty suporta três formatos de ficheiro para importação:
+
+| Formato            | Extensão | Notas                        |
+| ------------------ | -------- | ---------------------------- |
+| **CSV**            | .csv     | Recomendado, mais compatível |
+| **Excel**          | .xlsx    | Formato moderno do Excel     |
+| **Excel (Legado)** | .xls     | Formato antigo do Excel      |
+
+## Requisitos do Ficheiro
+
+| Requisito              | Valor                                                  |
+| ---------------------- | ------------------------------------------------------ |
+| **Codificação**        | UTF-8 recomendado                                      |
+| **Limite de registos** | 10 000 registos por ficheiro                           |
+| **Estrutura**          | A primeira linha deve conter os cabeçalhos das colunas |
+| **Conteúdo**           | Um tipo de objeto por ficheiro                         |
+
+## Melhores Práticas para CSV
+
+* **Delimitador**: Utilize vírgula (`,`) ou ponto e vírgula (`;`)
+* **Qualificador de texto**: Utilize aspas duplas (`"`) para texto que contenha vírgulas
+* **Finais de linha**: Windows (CRLF) ou Unix (LF), ambos são suportados
+* **Valores vazios**: Deixe as células em branco, não utilize "NULL" ou "N/A"
+
+## Melhores Práticas para o Excel
+
+Ao exportar do Excel:
+
+* Remova as fórmulas (exporte apenas valores)
+* Elimine as linhas vazias no final
+* Garanta que não existam células combinadas
+* Utilize apenas a primeira folha
+
+## Grandes Conjuntos de Dados
+
+Para conjuntos de dados com mais de 10 000 registos:
+
+* Divida em vários ficheiros
+* Ou utilize a [importação via API](/l/pt/user-guide/data-migration/how-tos/import-data-via-api) para registos ilimitados
+
+<Note>Para migrações muito grandes (100 000+ registos), a API é significativamente mais rápida e fiável do que as importações em CSV.</Note>

packages/twenty-docs/l/pt/user-guide/data-migration/capabilities/import-relations.mdx

@@ -0,0 +1,148 @@
+---
+title: Importar Relações Entre Objetos
+description: Importar relações entre registos via CSV.
+---
+
+## Visão Geral
+
+O Twenty suporta a importação de relações entre objetos durante a importação por CSV. Isto permite-lhe ligar registos (por exemplo, associar Pessoas a Empresas) como parte da sua migração de dados.
+
+<Note>**Atualmente suportado para importação**: Relações um-para-muitos que apontam para um único tipo de objeto de cada lado (por exemplo, Pessoas → Empresas). Relações que apontam para vários tipos de objeto ainda não são suportadas na importação/exportação.</Note>
+
+## Como funcionam as relações no Twenty
+
+### Um para Muitos / Muitos para Um
+
+O Twenty suporta relações padrão em que um registo se liga a muitos outros:
+
+* **Uma Empresa → Muitas Pessoas**: Uma empresa pode ter vários colaboradores, mas cada pessoa pertence a uma empresa
+* **Uma Empresa → Muitas Oportunidades**: Uma empresa pode ter vários negócios, mas cada oportunidade pertence a uma empresa
+
+### Relações que podem apontar para vários tipos de objeto
+
+Algumas relações podem ligar-se a diferentes tipos de objetos. Isto funciona de duas formas:
+
+**Padrão 1: Muitos registos a ligar-se, cada um, a um registo de diferentes tipos de objeto**
+
+Várias Notas ou Tarefas podem ser anexadas a vários tipos de objeto de uma só vez:
+
+* **Notas** podem ser ligadas a uma Pessoa, uma Empresa e uma Oportunidade em simultâneo
+* **Tarefas** podem ser ligadas a uma Pessoa, uma Empresa e uma Oportunidade em simultâneo
+
+Aqui, as Notas/Tarefas estão do lado "muitos". Cada uma liga-se a um registo por tipo de objeto.
+
+<img src="/images/user-guide/fields/many-to-one-morph.png" style={{width:'100%'}} />
+
+**Padrão 2: Um registo a receber ligações de muitos registos de diferentes tipos de objeto**
+
+Um Projeto pode receber ligações de vários registos de diferentes tipos de objeto:
+
+* **Um Projeto** pode ter muitas Pessoas ligadas a ele, muitas Empresas ligadas a ele e muitas Notas anexadas a ele
+
+Aqui, o Projeto está do lado "um". Vários registos de diferentes objetos podem ligar-se todos ao mesmo Projeto.
+
+<img src="/images/user-guide/fields/one-to-many-morph.png" style={{width:'100%'}} />
+
+<Warning>
+**Limitação de Importação/Exportação**: Relações que apontam para vários tipos de objeto (como Notas → Pessoas/Empresas/Oportunidades) **ainda não são suportadas** na importação ou exportação por CSV.
+
+* **Importação**: Apenas podem ser importadas relações um-para-muitos que apontem para um único tipo de objeto de cada lado
+* **Exportação**: As colunas para relações que apontam para vários tipos de objeto são, atualmente, deixadas em branco
+
+Isto está no nosso roadmap.
+</Warning>
+
+### O que não é suportado hoje
+
+**Relações muitos-para-muitos** ainda não estão disponíveis. Por exemplo, atualmente não pode criar uma relação em que:
+
+* Muitas Pessoas estão ligadas a muitos Projetos
+
+<Note>Relações muitos-para-muitos estão planeadas para o 2.º semestre de 2026.</Note>
+
+## Ligar registos durante a importação
+
+<Note>**Lembrete**: Só podem ser importadas relações um-para-muitos que apontem para um único tipo de objeto (por exemplo, Pessoas → Empresas). Relações que apontem para vários tipos de objeto (por exemplo, Notas → Pessoas/Empresas/Oportunidades) ainda não são suportadas.</Note>
+
+### Passo 1: Identificar os lados "Um" e "Muitos"
+
+Primeiro, determine qual o objeto que está do lado "um" e qual está do lado "muitos" da relação.
+
+**Exemplo**:
+
+* **Empresa** é o lado "um" (uma empresa tem muitos colaboradores)
+* **Pessoas** é o lado "muitos" (cada pessoa pertence a uma empresa)
+
+### Passo 2: Garanta que existem os registos do lado "Um"
+
+Antes de importar o lado "muitos", os registos do lado "um" já devem existir no Twenty.
+
+* Importe ou crie primeiro os registos do lado "um" (por exemplo, Empresas)
+* Valide o seu identificador único. Isto pode ser:
+  * O `id` (UUID do Twenty)
+  * Um campo definido como único (por exemplo, `domain` para Empresas, ou um ID externo do seu sistema anterior)
+
+<Warning>A importação falhará se for feita referência a um registo que não existe.</Warning>
+
+### Passo 3: Prepare o seu ficheiro CSV
+
+Adicione uma coluna no seu ficheiro CSV do lado "muitos" que referencia o registo do lado "um".
+
+**Exemplo**: Para um ficheiro CSV de Pessoas ligado a Empresas:
+
+```
+firstName,lastName,email,companyDomain
+John,Smith,john@acme.com,https://acme.com
+Jane,Doe,jane@widgets.co,https://widgets.co
+```
+
+**Importante**:
+
+* O valor deve **corresponder exatamente** ao campo único no registo da Empresa
+* Para domínios, use o **URL de domínio** (por exemplo, `https://acme.com`), não o rótulo do domínio
+* Mapeie apenas **um** identificador único por relação: isto leva a uma importação mais fluida
+
+### Passo 4: Verifique se o campo de relação existe
+
+Antes de carregar o seu ficheiro, garanta que o campo de relação existe entre os seus objetos.
+
+Se não existir:
+
+1. Vá a **Definições → Modelo de Dados**
+2. Selecione o seu objeto (por exemplo, Pessoas)
+3. Crie um campo de relação que aponte para o objeto de destino (por exemplo, Empresa)
+
+### Passo 5: Carregue e mapeie a relação
+
+1. Carregue o seu ficheiro CSV através da interface de importação
+2. No passo de mapeamento de campos, encontre a sua coluna de relação (por exemplo, `companyDomain`)
+3. Mapeie-a para o campo de relação (por exemplo, Empresa)
+4. O Twenty ligará automaticamente cada registo ao pai correspondente
+
+### Campos únicos disponíveis para relações
+
+| Objeto                                     | Campos únicos disponíveis                          |
+| ------------------------------------------ | -------------------------------------------------- |
+| **Empresas**                               | `id`, `domain`, qualquer campo único personalizado |
+| **Pessoas**                                | `id`, `email`, qualquer campo único personalizado  |
+| **Membros do Espaço de Trabalho**          | `id`, `email` (não o nome)                         |
+| **Outros objetos padrão e personalizados** | `id`, qualquer campo marcado como único            |
+
+<Note>**Ligação a Membros do Espaço de Trabalho**: Quando a relação aponta para Membros do Espaço de Trabalho (a sua equipa que inicia sessão no Twenty), refira-os pelo seu **endereço de email**, não pelo nome.</Note>
+
+<Note>Recomendamos usar `domain` para Empresas e `email` para Pessoas, pois são legíveis para humanos e fáceis de manter em folhas de cálculo.</Note>
+
+<Note>**Lembrete**: Registos suavemente eliminados (visíveis em Menu de Comandos → Ver registos eliminados) contam para os critérios de unicidade. Se importar um registo com o mesmo valor único que um registo eliminado, o registo eliminado será restaurado. Veja [Restrições de unicidade](/l/pt/user-guide/data-migration/capabilities/uniqueness-constraints) para mais detalhes.</Note>
+
+## Regra da Ordem de Importação
+
+<Warning>
+**Importe sempre primeiro o lado "um"!**
+
+1. **Empresas** primeiro (sem dependências)
+2. **Pessoas** em segundo (ligadas a Empresas)
+3. **Oportunidades** em terceiro (ligadas a Empresas/Pessoas)
+4. **Objetos personalizados** seguindo as suas dependências
+
+O registo pai deve existir antes de o poder referenciar.
+</Warning>

packages/twenty-docs/l/pt/user-guide/data-migration/capabilities/uniqueness-constraints.mdx

@@ -0,0 +1,72 @@
+---
+title: Restrições de Unicidade
+description: Como o Twenty impõe a unicidade dos dados durante a importação.
+---
+
+import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
+
+## Visão geral
+
+O Twenty impõe unicidade em determinados campos para evitar registos duplicados e garantir a integridade dos dados. Compreender estas restrições é essencial para importações bem-sucedidas.
+
+## Campos Únicos por Predefinição
+
+| Objeto                     | Campos Únicos                  |
+| -------------------------- | ------------------------------ |
+| **Pessoas**                | `id`, `email`                  |
+| **Empresas**               | `id`, `domain`                 |
+| **Objetos personalizados** | `id` apenas (por predefinição) |
+
+<Note>O campo `id` é o identificador interno do Twenty, gerado automaticamente para cada registo. Utiliza o formato UUID (por exemplo, `c776ee49-f608-4a77-8cc8-6fe96ae1e43f`).</Note>
+
+## Campos Únicos Personalizados
+
+Pode definir campos únicos adicionais em **Definições → Modelo de Dados**:
+
+1. Vá a **Definições → Modelo de Dados**
+2. Selecione o objeto
+3. Clique num campo
+4. Ative **Único** nas definições do campo
+
+### Casos de Utilização para Campos Únicos Personalizados
+
+* **IDs externos**: Guardar IDs de outros sistemas (Salesforce ID, HubSpot ID)
+* **Identificadores empresariais**: Números de colaborador, códigos de cliente
+* **Informações de contacto alternativas**: Perfil do LinkedIn, número de telefone
+
+<Note>O nome do campo `id` é reservado para o ID interno do Twenty. Utilize um nome diferente, como `externalId` ou `legacyId`, para identificadores externos.</Note>
+
+## Comportamento da Importação
+
+### Criação de Novos Registos
+
+Se o valor de um campo único não existir, é criado um novo registo.
+
+### Atualização de Registos Existentes
+
+Se o valor de um campo único corresponder a um registo existente, esse registo é **atualizado** com os novos dados.
+<Warning>Para **atualizar registos existentes**, recomenda-se **corresponder apenas a um campo único**.</Warning>
+
+### Registos Eliminados Logicamente
+
+<Warning>
+**Os registos eliminados contam para a unicidade.**
+
+Registos eliminados logicamente (visíveis em Menu de Comandos → Ver registos eliminados) são incluídos nas verificações de unicidade. Se importar um registo com o mesmo valor único que um registo eliminado, o registo eliminado será **restaurado** com os novos dados.
+</Warning>
+
+## Deteção de Duplicados Durante a Importação
+
+Durante a fase de validação:
+
+* Os duplicados no seu ficheiro são realçados a amarelo
+* Pode editar ou remover linhas duplicadas na interface antes de iniciar a importação
+
+<VimeoEmbed videoId="1145246326" title="Demonstração em vídeo" />
+
+## Melhores Práticas
+
+1. **Remova os duplicados** do seu ficheiro antes de importar
+2. **Verifique se existem registos** no Twenty antes de importar
+3. **Utilize IDs externos** ao migrar de outros sistemas
+4. **Inclua campos únicos** se quiser atualizar registos existentes