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 |
Per set di dati dell’ordine delle centinaia di migliaia, l’API è significativamente più veloce e più affidabile rispetto a importazioni CSV multiple.
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 |
Per iniziare
Passaggio 1: Ottieni la tua chiave API
- Vai a Impostazioni → Sviluppatori
- Fai clic su + Crea chiave API
- Assegna alla tua chiave un nome descrittivo
- Copia immediatamente la chiave API (non verrà più mostrata)
- Conservala in modo sicuro
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 |
| REST | Operazioni CRUD semplici, pattern REST familiari | Documentazione API |
- Creazione, lettura, aggiornamento ed eliminazione dei record
- Operazioni batch — crea o aggiorna fino a 60 record per chiamata
Passaggio 3: Pianifica l’ordine di importazione
Proprio come per le importazioni CSV, l’ordine è importante per le relazioni:- Aziende per prime (nessuna dipendenza)
- Persone al secondo posto (possono collegarsi alle Aziende)
- Opportunità al terzo posto (possono collegarsi ad Aziende e Persone)
- Attività/Note (possono collegarsi a uno qualsiasi dei precedenti)
- 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)
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:- Vai a Impostazioni → API e Webhooks
- Esplora la Metadata API
- Visualizza tutti gli oggetti standard e personalizzati con i relativi campi
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 |
- Migrazioni di oltre 100.000 record
- Trasformazioni dei dati complesse
- Tempistiche ristrette
- Team senza risorse di sviluppo
FAQ
Qual è la differenza tra GraphQL e REST?
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.
Posso aggiornare i record esistenti tramite API?
Posso aggiornare i record esistenti tramite API?
Sì! Usa mutation di aggiornamento (GraphQL) o richieste PUT/PATCH (REST) con l’
id del record.Come gestisco i duplicati?
Come gestisco i duplicati?
Esegui prima una query per i record esistenti usando identificatori univoci (email, dominio). Aggiorna se esiste, crea se non esiste.
Posso eliminare i record tramite API?
Posso eliminare i record tramite API?
Sì, usa mutation di delete (GraphQL) o richieste DELETE (REST).
Esiste un SDK per Python o Node.js?
Esiste un SDK per Python o Node.js?
Al momento no, ma entrambe le API funzionano con qualsiasi client HTTP in qualsiasi linguaggio.