snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/l/it/developers/extend/capabilities/apis.mdx

@@ -0,0 +1,147 @@
+---
+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
+* Gestire le relazioni dei 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. Clicca 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 → Membri → 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>

packages/twenty-docs/l/it/developers/extend/capabilities/webhooks.mdx

@@ -0,0 +1,112 @@
+---
+title: Webhooks
+description: Ricevi notifiche in tempo reale quando si verificano eventi nel tuo CRM.
+---
+
+import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
+
+I webhook inviano dati ai tuoi sistemi in tempo reale quando si verificano eventi in Twenty — senza necessità di polling. Usali per mantenere sincronizzati i sistemi esterni, attivare automazioni o inviare avvisi.
+
+## Crea un Webhook
+
+1. Vai a **Impostazioni → API e Webhook → Webhook**
+2. Clicca su **+ Crea webhook**
+3. Inserisci l'URL del tuo webhook (deve essere pubblicamente accessibile)
+4. Clicca su **Salva**
+
+Il webhook si attiva immediatamente e inizia a inviare notifiche.
+
+<VimeoEmbed videoId="928786708" title="Creazione di un webhook" />
+
+### Gestisci Webhook
+
+**Modifica**: Fai clic sul webhook → Aggiorna URL → **Salva**
+
+**Elimina**: Fai clic sul webhook → **Elimina** → Conferma
+
+## Eventi
+
+Twenty invia webhook per questi tipi di eventi:
+
+| Evento                | Esempio                                                    |
+| --------------------- | ---------------------------------------------------------- |
+| **Record creato**     | `person.created`, `company.created`, `note.created`        |
+| **Record aggiornato** | `person.updated`, `company.updated`, `opportunity.updated` |
+| **Record eliminato**  | `person.deleted`, `company.deleted`                        |
+
+Tutti i tipi di eventi vengono inviati all'URL del tuo webhook. Il filtraggio degli eventi potrebbe essere aggiunto nelle versioni future.
+
+## Formato del payload
+
+Ogni webhook invia una richiesta HTTP POST con un corpo JSON:
+
+```json
+{
+  "event": "person.created",
+  "data": {
+    "id": "abc12345",
+    "firstName": "Alice",
+    "lastName": "Doe",
+    "email": "alice@example.com",
+    "createdAt": "2025-02-10T15:30:45Z",
+    "createdBy": "user_123"
+  },
+  "timestamp": "2025-02-10T15:30:50Z"
+}
+```
+
+| Campo       | Descrizione                                                |
+| ----------- | ---------------------------------------------------------- |
+| `evento`    | Cosa è successo (ad es., `person.created`)                 |
+| `dati`      | Il record completo che è stato creato/aggiornato/eliminato |
+| `timestamp` | Quando si è verificato l'evento (UTC)                      |
+
+<Note>
+Rispondi con uno **status HTTP 2xx** (200-299) per confermare la ricezione. Le risposte non 2xx vengono registrate come errori di consegna.
+</Note>
+
+## Convalida del Webhook
+
+Twenty firma ogni richiesta webhook per motivi di sicurezza. Convalida le firme per assicurarti che le richieste siano autentiche.
+
+### Intestazioni
+
+| Intestazione                 | Descrizione               |
+| ---------------------------- | ------------------------- |
+| `X-Twenty-Webhook-Signature` | Firma HMAC SHA256         |
+| `X-Twenty-Webhook-Timestamp` | Timestamp della richiesta |
+
+### Passaggi di convalida
+
+1. Ottieni il timestamp da `X-Twenty-Webhook-Timestamp`
+2. Crea la stringa: `{timestamp}:{JSON payload}`
+3. Calcola HMAC SHA256 usando il segreto del tuo webhook
+4. Confronta con `X-Twenty-Webhook-Signature`
+
+### Esempio (Node.js)
+
+```javascript
+const crypto = require("crypto");
+
+const timestamp = req.headers["x-twenty-webhook-timestamp"];
+const payload = JSON.stringify(req.body);
+const secret = "your-webhook-secret";
+
+const stringToSign = `${timestamp}:${payload}`;
+const expectedSignature = crypto
+  .createHmac("sha256", secret)
+  .update(stringToSign)
+  .digest("hex");
+
+const isValid = expectedSignature === req.headers["x-twenty-webhook-signature"];
+```
+
+## Webhooks vs Workflows
+
+| Metodo                           | Direzione | Caso d'uso                                                               |
+| -------------------------------- | --------- | ------------------------------------------------------------------------ |
+| **Webhooks**                     | OUT       | Notifica automaticamente ai sistemi esterni qualsiasi modifica ai record |
+| **Workflow + HTTP Request**      | OUT       | Invia dati in uscita con logica personalizzata (filtri, trasformazioni)  |
+| **Trigger webhook del Workflow** | IN        | Ricevi dati in Twenty da sistemi esterni                                 |
+
+Per la ricezione di dati esterni, vedi [Configura un trigger webhook](/l/it/user-guide/workflows/how-tos/connect-to-other-tools/set-up-a-webhook-trigger).