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