Vai al contenuto principale

Documentation Index

Fetch the complete documentation index at: https://docs.twenty.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Panoramica

Questa guida ti accompagna nella preparazione del tuo file CSV per un’importazione riuscita. Segui questi passaggi per evitare errori.

​
Passaggio 1: Controlla i requisiti del file

Prima di iniziare, assicurati che il tuo file soddisfi questi requisiti:
RequisitoDettagli
FormatoCSV, XLSX o XLS
Limite di dimensione10.000 record per file
CodificaSi consiglia UTF-8
StrutturaUn tipo di oggetto per file
Per set di dati superiori a 10.000 record, suddividi in più file oppure usa l’importazione tramite API.

​
Passaggio 2: Scarica il file di esempio

Questo è il passaggio più importante. Il file di esempio ti mostra i nomi delle colonne e il formato esatti che Twenty si aspetta.
  1. Vai alla vista dell’oggetto (Persone, Aziende, ecc.)
  2. Fai clic su ⋮ → Importa record
  3. Fai clic su Scarica file di esempio
  4. Usa questo file come modello
Suggerimento avanzato: Esporta invece alcuni record esistenti. Questo ti fornisce esempi reali di come i dati devono essere formattati e i nomi delle colonne verranno mappati automaticamente durante l’importazione.

​
Passaggio 3: Rimuovi i valori duplicati

Twenty impone l’unicità su alcuni campi. I duplicati causeranno errori di importazione.
OggettoCampi unici
Personeid, email
Aziendeid, domain
Oggetti personalizzatiid, più qualsiasi campo che hai contrassegnato come univoco
Prima dell’importazione:
  1. Ordina il tuo foglio di calcolo in base al campo univoco (email o dominio)
  2. Rimuovi o unisci le righe duplicate
  3. Verifica la presenza di duplicati già esistenti in Twenty
I record eliminati in modo non definitivo contano ai fini dell’unicità. I record in Menu Comandi → Vedi record eliminati causeranno errori di duplicato. Eliminali definitivamente oppure ripristinali e aggiornali.

​
Passaggio 4: Formattta correttamente ogni tipo di campo

Tipi di campo diversi richiedono formati specifici. Ecco il riferimento completo:

​
Campi di testo

  • Non è richiesta una formattazione speciale
  • Gli spazi iniziali/finali vengono rimossi automaticamente

​
Campi email

  • Deve avere un formato email valido: name@domain.com
  • Deve essere univoco (nessun duplicato nel file o in Twenty)
  • Per email aggiuntive, usa questo formato nella colonna Email / Email aggiuntive:
["jane@twenty.com","jane.doe@twenty.com"]

​
Campi del dominio

  • Formato consigliato: https://domain.com
  • Questo corrisponde al formato usato dalla sincronizzazione della casella di posta/calendario (evita duplicati)
  • Compila entrambe le colonne:
    • Dominio / Etichetta dominio: domain.com
    • Dominio / URL dominio: https://domain.com
  • Deve essere univoco all’interno del tuo file e in Twenty

​
Campi telefono

Il telefono è un campo annidato che richiede più colonne:
ColonnaEsempio
Telefoni / Numero di telefono principale4159095555
Telefoni / Codice paese del telefono principaleUS
Telefoni / Prefisso internazionale del telefono principale+1

​
Campi indirizzo

Indirizzo è un campo annidato con più colonne (alcune possono essere lasciate vuote):
  • Indirizzo / Indirizzo 1: Riga indirizzo 1
  • Indirizzo / Indirizzo 2: Riga indirizzo 2 (facoltativa)
  • Indirizzo / Città: Nome città
  • Indirizzo / Stato: Stato o provincia
  • Indirizzo / Paese: Nome paese
  • Indirizzo / Codice postale: Codice postale/CAP

​
Campi data

Usa un formato coerente in tutto il file:
  • YYYY-MM-DD (consigliato): 2024-03-15
  • ISO 8601: 2024-03-15T10:30:00Z

​
Campi numerici

  • Solo numeri (nessun testo)
  • Usa il punto per i decimali: 1234.56
  • Nessun separatore delle migliaia (non 1,234.56)

​
Campi valuta

Valuta è un campo annidato che richiede due colonne che devono essere entrambe compilate:
ColonnaEsempio
Importo / Importo1234.56
Importo / ValutaUSD

​
Campi booleani

Usa il maiuscolo: TRUE o FALSE
Le minuscole true o false non funzioneranno.

​
Campi Selezione

Usa il nome API dell’opzione, non l’etichetta di visualizzazione. Come trovare i nomi API:
  1. Vai a Impostazioni → Modello dati
  2. Seleziona l’oggetto e il campo
  3. Abilita la Modalità avanzata (interruttore in basso a destra)
  4. Copia il nome API (ad es., OPTION_1, non “Option 1”)
Le nuove opzioni di selezione non vengono create automaticamente. Aggiungile in Impostazioni → Modello dati prima di importare.

​
Campi a selezione multipla

Usa i nomi API in formato array: 
["VALUE1","VALUE2"]

​
Campi array

Usa il formato array JSON: 
["value1","value2"]

​
Campi di valutazione

Usa il formato: RATING_1, RATING_2, RATING_3, RATING_4 o RATING_5

​
Campi Link/URL

Compila entrambe le colonne:
  • Link / Etichetta del link: Twenty
  • Link / URL del link: https://twenty.com
Per i link secondari, usa la colonna Link / Link secondari: 
[{"url":"https://twenty.com","label":"Twenty"}]

​
Campi JSON

Usa un formato JSON valido: 
{"key":"value","key2":"value2"}

​
Campi ID

  • Opzionale: Twenty genera automaticamente gli ID se non forniti
  • Formato: UUID (ad es., c776ee49-f608-4a77-8cc8-6fe96ae1e43f)
  • Caso d’uso: Includi l’ID per aggiornare i record esistenti invece di crearne di nuovi

​
Passaggio 5: Aggiungi colonne di relazione (se colleghi record)

Per collegare i record ad altri oggetti (ad es., Persone ad Aziende), aggiungi una colonna con l’identificatore univoco del record correlato. Esempio: collegare Persone ad Aziende Aggiungi una colonna al CSV Persone: 
firstName,lastName,email,companyDomain
John,Smith,john@acme.com,https://acme.com
Jane,Doe,jane@widgets.co,https://widgets.co
Regole importanti per le relazioni:
  • Il record padre deve già esistere in Twenty
  • Usa il formato URL del dominio (https://domain.com), non l’etichetta
  • Mappa un solo identificatore univoco (non includere sia companyId che companyDomain)
  • Per i membri dello spazio di lavoro, usa la loro email (non il nome)
L’ordine di importazione è importante!Importa il lato “uno” prima del lato “molti”:
  1. Aziende prima
  2. Persone poi (con riferimento all’azienda)
  3. Opportunità al terzo posto
Il record padre deve esistere prima di potervi fare riferimento.
Consulta Come importare le relazioni per istruzioni dettagliate.

​
Passaggio 6: Verifica che i campi esistano in Twenty

L’importazione crea record, non campi. Tutti i campi che vuoi importare devono già esistere nel tuo modello dati. Prima di importare:
  1. Vai a Impostazioni → Modello dati
  2. Seleziona il tuo oggetto
  3. Crea gli eventuali campi personalizzati necessari
  4. Annota i nomi esatti dei campi (devono corrispondere alle intestazioni delle colonne)

​
Passaggio 7: Lista di controllo finale

Prima di caricare il file, verifica:
Il file è in formato CSV, XLSX o XLS
Il file contiene meno di 10.000 record
La codifica è UTF-8
Nessuna email duplicata (per Persone) o domini (per Aziende)
Le date usano un formato coerente ovunque
I domini usano il formato https://domain.com
I campi booleani usano TRUE o FALSE (maiuscolo)
I campi di selezione usano i nomi API, non le etichette di visualizzazione
Tutti i campi personalizzati esistono in Impostazioni → Modello dati
I record padre sono importati prima dei record figlio
Le colonne di relazione fanno riferimento a record esistenti

​
Errori comuni da evitare

ErroreSoluzione
Uso di true invece di TRUEI valori booleani devono essere in maiuscolo
Uso delle etichette di visualizzazione per i campi di selezioneTrova e usa i nomi API in Impostazioni
Importare Persone prima delle AziendeImporta sempre prima gli oggetti padre
Codice valuta mancante per i campi di valutaCompila sia la colonna Importo sia la colonna Valuta
Formato di dominio erratoUsa https://domain.com in modo coerente
Mappatura di più campi univoci per le relazioniMappa solo UNO (dominio O id, non entrambi)

​
Prossimi Passi

Il tuo file è pronto! Ora: