Vai al contenuto principale

​
API con schema per tenant

Non esiste un riferimento API statico per Twenty. Ogni spazio di lavoro ha il proprio schema — quando aggiungi un oggetto personalizzato (ad esempio Invoice), ottiene immediatamente endpoint REST e GraphQL identici a quelli degli oggetti integrati come Company o Person. L’API è generata dallo schema, quindi gli endpoint usano direttamente i nomi dei tuoi oggetti e campi — niente ID opachi. La documentazione delle API specifica del tuo spazio di lavoro è disponibile in Impostazioni → Sviluppatori → API dopo aver creato una chiave API. Include un playground interattivo in cui puoi eseguire chiamate reali sui tuoi dati.

​
Due API

API principale — /rest/ e /graphql/ CRUD sui record: Persone, Aziende, Opportunità, i tuoi oggetti personalizzati. Esegui query, filtra, attraversa le relazioni. API dei metadati — /rest/metadata/ e /metadata/ Gestione dello schema: crea/modifica/elimina oggetti, campi e relazioni. Questo è il modo per modificare in modo programmatico il tuo modello di dati. Entrambe sono disponibili in REST e GraphQL. GraphQL aggiunge upsert in batch e la possibilità di attraversare le relazioni in un’unica query. I dati sottostanti sono gli stessi in entrambi i casi.

​
URL di base

​
Autenticazione

Crea una chiave API in Impostazioni → Sviluppatori → API → + Crea chiave. Copiala immediatamente — viene mostrata una sola volta. Le chiavi possono essere limitate a un ruolo specifico in Impostazioni → Membri → Ruoli → scheda Assegnazione per limitare ciò a cui possono accedere. Per l’accesso basato su OAuth (app esterne che agiscono per conto degli utenti), vedi OAuth.

​
Operazioni batch

Sia REST che GraphQL supportano il batching fino a 60 record per richiesta — creazione, aggiornamento o eliminazione. GraphQL supporta anche l’upsert in batch (crea o aggiorna in una sola chiamata) usando nomi plurali come CreateCompanies.

​
Selezione dei campi (REST)

Gli endpoint dei record REST accettano un parametro di query fields per restituire solo i campi necessari:
  • id viene sempre restituito.
  • I campi compositi (come emails o name) vengono selezionati interamente in base al nome del campo.
  • Un campo di relazione molti-a-uno restituisce la relativa colonna di join (ad es. companyId) con depth=0. I campi di relazione uno-a-molti vengono restituiti solo con depth=1. Con depth=1, vengono espansi solo i campi di relazione elencati in fields.
  • I campi sconosciuti o i campi che il tuo ruolo non può leggere restituiscono un errore 400.
Quando fields viene omesso su un oggetto con più di 200 campi leggibili, ogni record restituisce un set predefinito di 200 campi: id, i campi dell’etichetta e dell’identificatore dell’immagine, createdAt, updatedAt, deletedAt, position, quindi i campi standard prima dei campi personalizzati, ordinati per nome. Passa esplicitamente fields per leggere qualsiasi campo oltre quel set predefinito.

​
Limiti di frequenza delle API