982f0c4a4d
Created by Github action --------- Co-authored-by: github-actions <github-actions@twenty.com> Co-authored-by: Charles Bochet <charles@twenty.com>
148 lines
5.4 KiB
Plaintext
148 lines
5.4 KiB
Plaintext
---
|
|
title: API
|
|
description: Interroga e modifica i dati del tuo CRM in modo programmatico usando REST o GraphQL.
|
|
---
|
|
|
|
import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
|
|
|
|
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
|
|
|
|
<Note>
|
|
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.
|
|
</Note>
|
|
|
|
## 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
|
|
* Gestisci le relazioni tra i record
|
|
|
|
### Metadata API
|
|
|
|
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 |
|
|
|
|
Scegli in base alle tue esigenze — entrambi i formati accedono agli stessi dati.
|
|
|
|
## 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
|
|
|
|
1. Vai a **Impostazioni → APIs & Webhooks**
|
|
2. Fai clic su **+ Crea chiave**
|
|
3. Configura:
|
|
* **Nome**: Nome descrittivo per la chiave
|
|
* **Data di scadenza**: Quando la chiave scade
|
|
4. Fai clic su **Salva**
|
|
5. **Copia subito** — la chiave viene mostrata una sola volta
|
|
|
|
<VimeoEmbed videoId="928786722" title="Creazione della chiave API" />
|
|
|
|
<Warning>
|
|
La tua chiave API concede l'accesso a dati sensibili. Non condividerla con servizi non affidabili. Se compromessa, disabilitala immediatamente e generane una nuova.
|
|
</Warning>
|
|
|
|
### Assegna un ruolo a una chiave API
|
|
|
|
Per una maggiore sicurezza, assegna un ruolo specifico per limitare l'accesso:
|
|
|
|
1. Vai a **Impostazioni → Ruoli**
|
|
2. Fai clic sul ruolo da assegnare
|
|
3. Apri la scheda **Assegnazione**
|
|
4. In **Chiavi API**, fai clic su **+ Assegna alla chiave API**
|
|
5. Seleziona la chiave API
|
|
|
|
La chiave erediterà le autorizzazioni di quel ruolo. Vedi [Autorizzazioni](/l/it/user-guide/permissions-access/capabilities/permissions) 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
|
|
|
|
1. Vai a **Impostazioni → APIs & Webhooks**
|
|
2. Crea una chiave API (obbligatorio)
|
|
3. 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 |
|
|
|
|
<Tip>
|
|
Usa le operazioni batch per massimizzare il throughput — elabora fino a 60 record in una singola chiamata API invece di effettuare richieste individuali.
|
|
</Tip>
|