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

# Importa dati via API

> Quando e come usare le API di Twenty per importazioni di dati su larga scala.

## Panoramica

Twenty offre sia **GraphQL** che **API REST** per l'importazione programmatica dei dati. Usa l'API quando l'importazione CSV non è pratica per il tuo volume di dati o quando hai bisogno di importazioni automatizzate e ricorrenti.

## Quando usare l'importazione via API

| Scenario                            | Metodo consigliato                       |
| ----------------------------------- | ---------------------------------------- |
| Meno di 10.000 record               | Importazione CSV                         |
| 10.000 - 50.000 record              | Importazione CSV (suddivisa in più file) |
| **Oltre 50.000 record**             | **Importazione via API**                 |
| Migrazione una tantum               | Entrambi (in base al volume)             |
| **Importazioni ricorrenti**         | **Importazione via API**                 |
| **Sincronizzazione in tempo reale** | **Importazione via API**                 |
| **Integrazione con altri sistemi**  | **Importazione via API**                 |

<Note>Per set di dati dell'ordine delle centinaia di migliaia, l'API è significativamente più veloce e più affidabile rispetto a importazioni CSV multiple.</Note>

## Limiti di frequenza delle API

Twenty applica limiti di frequenza per garantire la stabilità del sistema:

| Limite                        | Valore                |
| ----------------------------- | --------------------- |
| **Richieste al minuto**       | 100                   |
| **Record per chiamata batch** | 60                    |
| **Throughput massimo**        | \~6.000 record/minuto |

<Warning>
  **Pianifica la tua importazione tenendo conto di questi limiti.**

  Per 100.000 record al throughput massimo, prevedi circa 17 minuti di tempo di importazione. Aggiungi un margine di tempo per la gestione degli errori e i nuovi tentativi.
</Warning>

## Per iniziare

### Passaggio 1: Ottieni la tua chiave API

1. Vai a **Impostazioni → Sviluppatori**
2. Fai clic su **+ Crea chiave API**
3. Assegna alla tua chiave un nome descrittivo
4. Copia immediatamente la chiave API (non verrà più mostrata)
5. Conservala in modo sicuro

<Warning>
  **Mantieni segreta la tua chiave API.**

  Chiunque abbia la tua chiave API può accedere ai dati del tuo spazio di lavoro e modificarli. Non inserirla mai nei repository di codice né condividerla pubblicamente.
</Warning>

### Passaggio 2: Scegli la tua API

Twenty supporta due tipi di API:

| API         | Ideale per                                                         | Documentazione                                    |
| ----------- | ------------------------------------------------------------------ | ------------------------------------------------- |
| **GraphQL** | Query flessibili, recupero di dati correlati, operazioni complesse | [Documentazione API](/l/it/developers/extend/api) |
| **REST**    | Operazioni CRUD semplici, pattern REST familiari                   | [Documentazione API](/l/it/developers/extend/api) |

Entrambe le API supportano:

* Creazione, lettura, aggiornamento ed eliminazione dei record
* **Operazioni batch** — crea o aggiorna fino a 60 record per chiamata

**Per le importazioni, usa le operazioni batch** per massimizzare il throughput entro i limiti di frequenza.

### Passaggio 3: Pianifica l'ordine di importazione

Proprio come per le importazioni CSV, **l'ordine è importante** per le relazioni:

1. **Aziende** per prime (nessuna dipendenza)
2. **Persone** al secondo posto (possono collegarsi alle Aziende)
3. **Opportunità** al terzo posto (possono collegarsi ad Aziende e Persone)
4. **Attività/Note** (possono collegarsi a uno qualsiasi dei precedenti)
5. **Oggetti personalizzati** (seguendo le loro dipendenze)

## Migliori Pratiche

### Raggruppa le richieste in batch

* Non inviare i record uno alla volta
* Raggruppa fino a **60 record per chiamata API**
* Questo massimizza il throughput entro i limiti di frequenza

### Gestisci i limiti di frequenza

* Implementa dei ritardi tra le richieste (minimo 600 ms per importazioni prolungate)
* Usa un backoff esponenziale quando raggiungi i limiti
* Monitora le risposte 429 (Too Many Requests)

### Convalida i dati prima

* Pulisci e convalida i tuoi dati prima di importare
* Verifica che i campi obbligatori siano compilati
* Verifica che i formati soddisfino i requisiti di Twenty (vedi [Mappatura dei campi](/l/it/user-guide/data-migration/capabilities/field-mapping))

### Registra tutto

* Registra ogni record importato (inclusi gli ID)
* Registra gli errori con tutto il contesto
* Questo aiuta a eseguire il debug dei problemi e a verificare il completamento

### Testa prima

* Esegui un test con un piccolo batch (10-20 record)
* Verifica che i dati compaiano correttamente in Twenty
* Poi esegui l'importazione completa

### Usa l'upsert per evitare duplicati

L'API GraphQL supporta **l'upsert in batch** — aggiorna se il record esiste, crea se non esiste. Questo evita duplicati quando riesegui le importazioni.

## Trovare i nomi di oggetti e campi

Per vedere oggetti e campi disponibili:

1. Vai a **Impostazioni → API e Webhooks**
2. Esplora la **Metadata API**
3. Visualizza tutti gli oggetti standard e personalizzati con i relativi campi

La documentazione mostra tutti gli oggetti standard e personalizzati, i loro campi e i tipi di dati previsti.

## Servizi Professionali

Per migrazioni API complesse, i nostri partner possono aiutarti:

| Servizio                           | Cosa è incluso                                  |
| ---------------------------------- | ----------------------------------------------- |
| **Progettazione del modello dati** | progettare la tua struttura dati ottimale       |
| **Script di migrazione**           | scrivere ed eseguire gli script di importazione |
| **Trasformazione dei dati**        | gestire mappature complesse e pulizia           |
| **Validazione & QA**               | verificare che la migrazione sia completa       |

**Ideale per:**

* Migrazioni di oltre 100.000 record
* Trasformazioni dei dati complesse
* Tempistiche ristrette
* Team senza risorse di sviluppo

Contattaci a [contact@twenty.com](mailto:contact@twenty.com) oppure scopri i nostri [Servizi di implementazione](/l/it/user-guide/getting-started/capabilities/implementation-services).

## FAQ

<AccordionGroup>
  <Accordion title="Qual è la differenza tra GraphQL e REST?">
    GraphQL ti consente di richiedere esattamente i dati di cui hai bisogno con una singola query ed è migliore per operazioni complesse. REST utilizza i metodi HTTP standard (GET, POST, PUT, DELETE) e può risultare più familiare se hai già lavorato con API tradizionali.
  </Accordion>

  <Accordion title="Posso aggiornare i record esistenti tramite API?">
    Sì! Usa mutation di aggiornamento (GraphQL) o richieste PUT/PATCH (REST) con l'`id` del record.
  </Accordion>

  <Accordion title="Come gestisco i duplicati?">
    Esegui prima una query per i record esistenti usando identificatori univoci (email, dominio). Aggiorna se esiste, crea se non esiste.
  </Accordion>

  <Accordion title="Posso eliminare i record tramite API?">
    Sì, usa mutation di delete (GraphQL) o richieste DELETE (REST).
  </Accordion>

  <Accordion title="Esiste un SDK per Python o Node.js?">
    Al momento no, ma entrambe le API funzionano con qualsiasi client HTTP in qualsiasi linguaggio.
  </Accordion>
</AccordionGroup>

## Documentazione API

Per i dettagli completi di implementazione, esempi di codice e riferimento allo schema:

* [Documentazione API](/l/it/developers/extend/api)