Twenty è stato progettato per essere adatto agli sviluppatori, offrendo potenti API che si adattano al tuo modello di dati personalizzato. Forniamo quattro tipi distinti di API per soddisfare diverse esigenze di integrazione.
Approccio incentrato sullo sviluppatore
Twenty genera API specifiche per il tuo modello di dati:
- Nessun ID lungo richiesto: Utilizza direttamente i nomi degli oggetti e dei campi negli endpoint
- Oggetti standard e personalizzati trattati allo stesso modo: I tuoi oggetti personalizzati ricevono lo stesso trattamento API di quelli predefiniti
- Endpoint dedicati: Ogni oggetto e campo ottiene il proprio endpoint API
- Documentazione personalizzata: Generata specificamente per il modello di dati del tuo workspace
La documentazione personalizzata delle tue API è disponibile in Impostazioni → API & Webhooks dopo aver creato una chiave API. Poiché Twenty genera API che corrispondono al tuo modello di dati personalizzato, la documentazione è unica per il tuo workspace.
I due tipi di API
Core API
Accessibile su /rest/ o /graphql/
Lavora con i tuoi record reali (i dati):
- Crea, leggi, aggiorna, elimina Persone, Aziende, Opportunità, ecc.
- Interroga e filtra i dati
- Gestire le relazioni dei record
Accessibile su /rest/metadata/ o /metadata/
Gestisci il tuo workspace e il modello di dati:
- Crea, modifica o elimina oggetti e campi
- Configura le impostazioni del workspace
- Definisci le relazioni tra oggetti
REST vs GraphQL
Sia le API Core che le API Metadata sono disponibili nei formati REST e GraphQL:
| Formato | Operazioni disponibili |
|---|
| REST | CRUD, operazioni batch, upsert |
| GraphQL | Stesse funzionalità + upsert in batch, query sulle relazioni in un’unica chiamata |
Endpoint API
| Ambiente | URL di base |
|---|
| Cloud | https://api.twenty.com/ |
| Auto-ospitato | https://{your-domain}/ |
Autenticazione
Ogni richiesta API richiede una chiave API nell’intestazione:
Authorization: Bearer YOUR_API_KEY
Crea una chiave API
- Vai a Impostazioni → APIs & Webhooks
- Fai clic su + Crea chiave
- Configura:
- Nome: Nome descrittivo per la chiave
- Data di scadenza: Quando la chiave scade
- Clicca su Salva
- Copia subito — la chiave viene mostrata una sola volta
La tua chiave API concede l’accesso a dati sensibili. Non condividerla con servizi non affidabili. Se compromessa, disabilitala immediatamente e generane una nuova.
Assegna un ruolo a una chiave API
Per una maggiore sicurezza, assegna un ruolo specifico per limitare l’accesso:
- Vai a Impostazioni → Ruoli
- Fai clic sul ruolo da assegnare
- Apri la scheda Assegnazione
- In Chiavi API, fai clic su + Assegna alla chiave API
- Seleziona la chiave API
La chiave erediterà le autorizzazioni di quel ruolo. Vedi Autorizzazioni per i dettagli.
Gestisci chiavi API
Rigenera: Impostazioni → APIs & Webhooks → Fai clic sulla chiave → Rigenera
Elimina: Impostazioni → APIs & Webhooks → Fai clic sulla chiave → Elimina
Playground API
Testa le tue API direttamente nel browser con il nostro playground integrato — disponibile sia per REST sia per GraphQL.
Accedi al Playground
- Vai a Impostazioni → APIs & Webhooks
- Crea una chiave API (obbligatorio)
- Fai clic su REST API o GraphQL API per aprire il playground
Cosa ottieni
- Documentazione interattiva: Generata per il tuo specifico modello di dati
- Test in tempo reale: Esegui chiamate API reali sul tuo workspace
- Esploratore dello schema: Sfoglia gli oggetti, i campi e le relazioni disponibili
- Generatore di richieste: Crea query con completamento automatico
Il playground riflette i tuoi oggetti e campi personalizzati, quindi la documentazione è sempre accurata per il tuo workspace.
Operazioni Batch
Sia REST che GraphQL supportano operazioni batch:
- Dimensione batch: Fino a 60 record per richiesta
- Operazioni: Creare, aggiornare, eliminare più record
Funzionalità esclusive di GraphQL:
- Upsert in batch: Crea o aggiorna in un’unica chiamata
- Usa nomi oggetto al plurale (ad es.
CreateCompanies invece di CreateCompany)
Limiti di frequenza delle API
Le richieste API sono limitate per garantire la stabilità della piattaforma:
| Limite | Valore |
|---|
| Richieste | 100 chiamate al minuto |
| Dimensione batch | 60 record per chiamata |
Usa le operazioni batch per massimizzare il throughput — elabora fino a 60 record in una singola chiamata API invece di effettuare richieste individuali.
