# API Automazioni

Un'automazione è un flusso di lavoro composto da passaggi: uno o più trigger che lo avviano, seguiti da azioni, condizioni, ritardi, passaggi IA e altro ancora, collegati in un grafo. È la stessa automazione che vedi e modifichi nella pagina [Automazioni](../automations/automations.md). Questa guida illustra come leggerle e crearle tramite l'API.

- **URL base**: `https://api.dmchamp.com/v1`
- **Autenticazione**: la tua chiave API (vedi [Autenticazione](authentication.md))
- **Campi e corpi**: ogni parametro e campo di risposta si trova nel [Riferimento API](reference.md#tag/automations)
- **Errori**: vedi [Errori e impaginazione](errors-and-pagination.md) e [Errori](#errors) qui sotto

> **Agenzie:** ogni endpoint in questa pagina accetta `sub_account_id` come parametro di query, così puoi leggere e creare le automazioni di un cliente con la tua chiave di agenzia. Un `sub_account_id` che non appartiene a uno dei tuoi account cliente restituisce `404`. Vedi [API per le agenzie](../agency/api-for-agencies.md).

---

## Come funziona: prima la bozza

L'API è strutturata in modo che nulla venga avviato accidentalmente.

1. **Leggi il catalogo.** `GET /automations/steps` elenca ogni trigger, azione e tipo di passaggio che puoi utilizzare, oltre alla grammatica per scrivere un grafo (`graph_rules`).
2. **Crea una bozza.** `POST /automations` memorizza l'automazione **disattivata**. Non viene eseguito ancora nulla.
3. **Controllala.** Leggila, aprila nel builder (la risposta ti fornisce il suo `open_path`) e assicurati che il proprietario dell'account abbia visto cosa fa e a chi si rivolge.
4. **Attivala.** `POST /automations/{automationId}/enable` è una chiamata a sé stante. Questo è il passaggio che rende operative le azioni: messaggi inviati, record modificati, strumenti forniti a un agente IA.

La modifica non cambia mai lo stato di attivazione di un'automazione. Ciò significa anche che una modifica a un'automazione **attiva** ha effetto immediato sull'automazione in esecuzione. Per modificare un'automazione in esecuzione in modo sicuro, disabilitala, modificala, controllala e riabilitala.

Ogni grafo inviato viene sottoposto agli stessi controlli applicati dal canvas del builder. Un grafo che non può essere aperto o eseguito viene rifiutato con un `400` che elenca esattamente cosa correggere.

### Accesso

- L'account deve disporre di Automazioni. Senza di esse, ogni chiamata in questa pagina restituisce `403`.
- L'accesso di un membro del team segue la sua area **Automazioni** in [Gestione Team](../settings/team-management.md): la lettura (elenco, recupero, passaggi, esecuzioni, cartelle) richiede **Visualizzazione**, tutto ciò che comporta una modifica richiede **Modifica**.
- Su un account cliente il cui piano non prevede la creazione e la modifica di automazioni, le chiamate di scrittura restituiscono `403`, esattamente come fa il builder nell'app.

---

## Endpoint

| Attività | Metodo + percorso | Explorer |
|---|---|---|
| Elenca automazioni | `GET /automations` | [Apri nel Riferimento API](reference.md#tag/automations/GET/automations) |
| Ottieni un'automazione con il suo grafo | `GET /automations/{automationId}` | [Apri nel Riferimento API](reference.md#tag/automations/GET/automations/{automationId}) |
| Leggi il catalogo dei passaggi | `GET /automations/steps` | [Apri nel Riferimento API](reference.md#tag/automations/GET/automations/steps) |
| Crea un'automazione (bozza) | `POST /automations` | [Apri nel Riferimento API](reference.md#tag/automations/POST/automations) |
| Aggiorna un'automazione | `PUT /automations/{automationId}` | [Apri nel Riferimento API](reference.md#tag/automations/PUT/automations/{automationId}) |
| Attivala | `POST /automations/{automationId}/enable` | [Apri nel Riferimento API](reference.md#tag/automations/POST/automations/{automationId}/enable) |
| Disattivala | `POST /automations/{automationId}/disable` | [Apri nel Riferimento API](reference.md#tag/automations/POST/automations/{automationId}/disable) |
| Leggi la cronologia delle esecuzioni | `GET /automations/{automationId}/runs` | [Apri nel Riferimento API](reference.md#tag/automations/GET/automations/{automationId}/runs) |
| Elenca cartelle | `GET /automations/folders` | [Apri nel Riferimento API](reference.md#tag/automations/GET/automations/folders) |
| Crea una cartella | `POST /automations/folders` | [Apri nel Riferimento API](reference.md#tag/automations/POST/automations/folders) |
| Rinomina una cartella | `PUT /automations/folders/{folderId}` | [Apri nel Riferimento API](reference.md#tag/automations/PUT/automations/folders/{folderId}) |
| Elimina una cartella | `DELETE /automations/folders/{folderId}` | [Apri nel Riferimento API](reference.md#tag/automations/DELETE/automations/folders/{folderId}) |
| Sposta un'automazione in una cartella | `PUT /automations/{automationId}/folder` | [Apri nel Riferimento API](reference.md#tag/automations/PUT/automations/{automationId}/folder) |

---

## Lettura delle automazioni

`GET /automations` restituisce riepiloghi (senza passaggi), con i più recenti per primi; `folder_id=none` elenca quelle non inserite in alcuna cartella. `GET /automations/{automationId}` aggiunge il `graph` completo: ogni passaggio (`nodes[]`) con il suo `kind`, `label`, `alias`, `action`, `params` e `config`, e le connessioni (`edges[]`) con `from`, `to` e, dopo una condizione o simile, `branch`.

```bash
curl "https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f?apiKey=YOUR_API_KEY"
```

**Buono a sapersi**

- **`alias` è il modo in cui i passaggi successivi leggono l'output di un passaggio**, come `${nodes.<alias>.<field>}`. Un passaggio che ne è privo viene referenziato tramite il suo id.
- `params` è mantenuto per i lettori meno recenti; `config` trasporta gli stessi valori e altro ancora (le regole di una condizione, il prompt di un passaggio AI, la durata di un ritardo, lo slug e i parametri di un'azione).
- **I segreti sono nascosti.** I valori che sembrano credenziali (segreti webhook, token, chiavi API, password, valori di intestazione) vengono restituiti come `"[redacted]"`. Invia `"[redacted]"` senza modifiche e il valore memorizzato verrà mantenuto.
- **I testi lunghi vengono abbreviati.** Un singolo testo più lungo di circa 4.000 caratteri viene troncato e termina con un'ellissi. Se invii nuovamente quel passaggio, inserisci prima il testo completo.
- Se il servizio di automazione non è raggiungibile, riceverai un `503`, mai un elenco vuoto al suo posto. Un elenco vuoto significa sempre che non ci sono automazioni.

### Il catalogo dei passaggi

`GET /automations/steps` restituisce tutto ciò da cui può essere costruita un'automazione: gli 8 `node_kinds`, ogni trigger con le sue impostazioni `fields` e `output_keys`, i `actions` integrati con i relativi parametri, le `api_actions` (operazioni di questa API che un passaggio di azione può chiamare), la grammatica `graph_rules` e `counts`. Questo è ciò che il builder **offre**, non ciò che l'account ha costruito: controlla prima di concludere che un trigger o un'azione non esistano.

- Senza `q`, le diverse centinaia di azioni API vengono restituite come etichette raggruppate per area in `api_actions_by_tag` e l'elenco piatto è vuoto.
- Con `q` (una parola che non distingue tra maiuscole e minuscole), `api_actions` è l'elenco piatto delle corrispondenze, limitato a 60 (`api_actions_truncated` indica quando). Vengono cercate anche le azioni per le app di terze parti connesse e restituite in `app_actions`: cerca per nome dell'app, ad esempio `q=hubspot`. Ognuna indica se l'account ha quell'app `connected`, e `connected_apps` elenca quelle connesse. `app_actions_unavailable` è `true` quando le azioni dell'app non sono state cercate questa volta; gli altri elenchi sono comunque completi.

---

## Creazione e modifica

### Creare una bozza

```bash
curl -X POST "https://api.dmchamp.com/v1/automations?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Price question auto-reply",
    "description": "Replies with the price list when someone asks about prices.",
    "graph": {
      "nodes": [
        { "id": "trigger_1", "type": "trigger", "label": "Incoming message",
          "data": { "trigger": { "kind": "incoming_message", "message_filter_contains": "price" } } },
        { "id": "send_prices", "type": "action", "label": "Send message",
          "data": { "action": { "provider": "native", "slug": "SEND_MESSAGE",
            "params": { "contact_id": "${trigger.contact.id}", "body": "Hi ${trigger.contact.first_name}, here is our price list: https://example.com/prices" } } } }
      ],
      "edges": [{ "source": "trigger_1", "target": "send_prices" }]
    }
  }'
```

```json
{ "success": true, "automation": { "id": "8d2c7f1e-…", "enabled": false, "…": "…" }, "draft": true, "open_path": "/automations/8d2c7f1e-…", "warnings": [] }
```

`draft: true` e `enabled: false` sono normali, non un errore: una nuova automazione è sempre una bozza finché non la abiliti. `warnings` elenca ciò che il builder non è riuscito a completare, come brevi etichette (ad esempio `agent_function:not_linked`).

**Scrittura del grafo.** `graph_rules` dal catalogo è la grammatica completa. In breve:

- Ogni nodo ha un `id` (univoco nel grafo), un `type` (uno degli 8 [tipi di passaggio](#step-kinds)), un `label` opzionale e le sue impostazioni in `data` sotto una chiave che prende il nome dal suo tipo (`data.trigger`, `data.action`, `data.condition`, `data.delay`, `data.ai`, `data.loop`, `data.transform`, `data.respond`).
- Un'automazione necessita di almeno un trigger. La grammatica live ne consente fino a 10 e l'automazione si avvia quando uno qualsiasi di essi viene attivato.
- Ogni altro passaggio deve essere raggiungibile da un trigger e nessuna connessione può riportare a un passaggio precedente.
- I bordi che escono da una condizione trasportano `sourceHandle` `true` o `false`; un ciclo `body` o `done`; un ritardo di attesa di risposta `replied` o `timed_out`. Gli altri bordi non ne hanno nessuno.
- Gli slug e i parametri delle azioni provengono dal catalogo. **Non indovinare mai un id** (un agente, un tag, un elenco, una fase): cercalo prima con l'API o lascia il campo come `""` affinché la persona possa sceglierlo nel builder.
- Le posizioni sono facoltative; i passaggi che ne sono privi vengono disposti automaticamente.
- I valori dei passaggi precedenti sono scritti come `${trigger.<field>}` e `${nodes.<step>.<field>}`. Vedi [Utilizzo di quanto restituito da un passaggio precedente](../automations/automations.md#using-what-an-earlier-step-returned) e [Espressioni](../automations/automations.md#expressions).
- Il grafo è accettato in due grafie: quella del builder (sopra) e quella con cui risponde una lettura (`kind`, `config`, `from`, `to`, `branch`). Quindi puoi leggere un'automazione, modificare un passaggio e rispedirlo.
- **Non è sicuro ripetere ciecamente una creazione.** Se una richiesta va in timeout, elenca le tue automazioni prima di inviarla di nuovo, altrimenti potresti ritrovarti con due bozze.

### Aggiornamento

`PUT /automations/{automationId}` modifica `name`, `description` e/o `graph` (almeno uno, o `400`). Un `graph` sostituisce l'**intero** grafo, quindi lavora sempre partendo da ciò che è memorizzato: leggilo, modifica ciò che ti serve e invia nuovamente l'intero grafo.

```bash
curl -X PUT "https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Price question auto-reply (EN)" }'
```

- **Mantieni ogni `alias` del passaggio esattamente come l'hai ricevuto.** Se lo modifichi o lo elimini, ogni riferimento a quel passaggio risulterà vuoto. Vedi [Dare un nome ai passaggi](../automations/automations.md#naming-your-steps).
- **Lascia i valori `"[redacted]"` così come sono** e **ripristina i testi abbreviati** (un testo che termina con un'ellissi era stato troncato durante la lettura).
- Lo stato di attivazione dell'automazione non viene mai modificato qui. Se è attiva, la tua modifica sarà operativa non appena salvata. Quando è attiva, una modifica che potrebbe causare l'auto-attivazione dell'automazione viene rifiutata: disabilitala prima.

### Abilita e disabilita

`POST /automations/{automationId}/enable` attiva un'automazione, in modo che venga eseguita al suo trigger da questo momento in poi. Richiamalo solo dopo che il titolare dell'account ha visto cosa fa l'automazione, verso chi, e ha dato il suo consenso. Il builder rifiuta di attivare un grafo che non può essere eseguito (nessun trigger, un ciclo, un passaggio che attiva se stesso) con un `400` che ne spiega il motivo.

```bash
curl -X POST "https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f/enable?apiKey=YOUR_API_KEY"
```

`POST /automations/{automationId}/disable` la mette in pausa: le esecuzioni già in corso vengono completate, non ne iniziano di nuove. La disabilitazione è sempre consentita. Nessuna delle due chiamate richiede un corpo.

---

## Cronologia delle esecuzioni

`GET /automations/{automationId}/runs` restituisce le esecuzioni di un'automazione, dalla più recente alla meno recente (`limit` da 1 a 50, predefinito 10): quando ognuna è iniziata e terminata, cosa l'ha innescata, se ha avuto successo e l'errore in caso di fallimento. Leggere l'automazione ti dice cosa **farebbe**; la cronologia delle esecuzioni ti dice cosa **ha fatto**, ed è l'unico modo per distinguere un'automazione che non è mai stata eseguita da una che viene eseguita e fallisce ogni volta.

```bash
curl "https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f/runs?apiKey=YOUR_API_KEY&limit=20"
```

- `mode` è `live` per un'esecuzione reale, o `safe` per un'**esecuzione sicura** dall'editor. Un'esecuzione sicura non invia nulla, quindi non è una prova che l'automazione funzioni nell'uso reale.
- Un elenco `runs` vuoto è una risposta, non una lacuna. La risposta contiene quindi un `note`: il trigger non è mai scattato oppure l'automazione è disattivata.

---

## Cartelle

Le cartelle raggruppano solo le automazioni nell'elenco. Non cambiano mai ciò che fa un'automazione o se è attiva. Vedi [Organizzare le automazioni nelle cartelle](../automations/automations.md#organizing-automations-in-folders).

```bash
curl -X PUT "https://api.dmchamp.com/v1/automations/8d2c7f1e-2a3b-4c5d-9e8f-0a1b2c3d4e5f/folder?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "folder_id": "f1a2b3c4-5d6e-7f80-91a2-b3c4d5e6f708" }'
```

- L'elenco delle cartelle restituisce anche `unfiled_count`, ovvero quante automazioni non sono in alcuna cartella.
- Il nome di una cartella è obbligatorio, può contenere fino a 100 caratteri e deve essere univoco nell'account (`409`, `code: "folder_name_taken"`). Puoi anche archiviare un'automazione passando `folder_id` al momento della creazione.
- La ridenominazione lascia le automazioni dove si trovano.
- **L'eliminazione di una cartella elimina solo la cartella.** Le sue automazioni vengono spostate fuori da qualsiasi cartella e continuano a funzionare esattamente come prima; la risposta indica quante sono state spostate (`moved_to_no_folder`).
- Durante uno spostamento, `folder_id` è obbligatorio; invia `null` per rimuovere l'automazione dalla sua cartella.

---

## Catalogo

### Tipi di passaggio

| Tipo | Cosa fa |
|---|---|
| `trigger` | Avvia l'automazione quando succede qualcosa. |
| `action` | Esegue un passaggio: un'azione integrata, un'azione API, l'azione di un'app connessa, una richiesta HTTP o un'email. |
| `condition` | Divide il flusso in base a una regola, in un ramo `true` e uno `false`. |
| `transform` | Esegue una breve porzione di codice per riformattare i dati tra i passaggi. |
| `ai` | Interroga l'IA con un prompt scritto da te. Può restituire testo, campi separati o scegliere tra diversi rami. |
| `delay` | Attende per un tempo prestabilito o attende che il contatto risponda (con un timeout). |
| `loop` | Ripete i passaggi al suo interno per ogni elemento in un elenco. |
| `respond` | Restituisce una risposta alla chiamata webhook o alla chiamata di funzione dell'agente IA che ha avviato l'esecuzione. |

### Trigger

Questi sono i 40 trigger elencati oggi nel catalogo, raggruppati come nel builder. La colonna **Impostazioni** contiene le chiavi di impostazione specifiche del trigger (`fields`), che ne restringono le condizioni di attivazione. Ogni trigger accetta anche `respect_quiet_hours`, `run_hours`, `reentry` e `stop_on_response`; vedi [Impostazioni automazione](../automations/automations.md#automation-settings).

**Messaggistica**

| Trigger (`kind`) | Si attiva quando | Impostazioni |
|---|---|---|
| Messaggio in arrivo (`incoming_message`) | Un contatto invia un messaggio su qualsiasi canale. | `campaign` (lo limita a un solo agente IA), `channel`, `message_filter_contains` (parola chiave), `message_filter_regex` (pattern) |
| Chiamata persa (`missed_call`) | Qualcuno chiama uno dei tuoi numeri WhatsApp Web o il tuo numero SMS e nessuno risponde. | `to_number` |
| Messaggio consegnato (`message_delivered`) | Un messaggio che hai inviato viene confermato come consegnato dal canale. | `channel`, `agent` |
| Messaggio fallito (`message_failed`) | Un messaggio che hai inviato non è stato consegnato, con l'errore riscontrato. | `channel`, `agent` |
| Messaggio inviato (`message_sent`) | Qualsiasi messaggio lascia il tuo account: dell'IA, tuo, un broadcast, un follow-up. Filtralo, altrimenti verrà eseguito su tutti. | `channel`, `sent_by` |
| Follow-up inviato (`follow_up_sent`) | Viene inviato un follow-up automatico. | nessuno |
| Follow-up saltato (`follow_up_skipped`) | Un follow-up è stato bloccato perché la sua condizione di invio non è stata soddisfatta. | nessuno |
| Follow-up terminati (`follow_up_exhausted`) | Un contatto ha ricevuto l'ultimo follow-up della sequenza e non c'è altro in coda. | nessuno |
| Conversazione chiusa (`conversation_closed`) | Una chat viene chiusa, con il motivo della chiusura e un riepilogo. | `channel`, `agent` |
| Broadcast terminato (`broadcast_completed`) | Un broadcast ha terminato l'invio, con il numero di messaggi inviati e falliti. | nessuno |
| Risposta lead ordinata (`outreach_reply_labelled`) | La risposta di un lead da email a freddo viene ordinata, ad esempio come Interessato. | `label` |
| Commento Skool ricevuto (`skool_comment_received`) | Un membro commenta sotto un post Skool monitorato da una delle tue regole di commento. | nessuno |

**Contatti**

| Trigger (`kind`) | Si attiva quando | Impostazioni |
|---|---|---|
| Nuovo contatto (`contact_created`) | Una nuova persona ti contatta per la prima volta su qualsiasi canale, e anche per importazioni, API e contatti creati manualmente. | nessuno |
| Contatto aggiornato (`contact_updated`) | Un campo del contatto cambia. | `field` |
| Contatti aggiunti qui (`contact_added`) | Solo per i contatti che inserisci tu stesso in questa automazione dalla pagina Contatti. Un'esecuzione per contatto. | nessuno |
| Tag applicato (`tag_applied`) | Un tag viene aggiunto a un contatto, dal tuo agente IA, da una persona, da un'automazione o da un'importazione. | `tag_name`, `channel`, `applied_by` |
| Tag rimosso (`tag_removed`) | Un tag viene rimosso da un contatto. | `tag_name`, `channel` |
| Membro Skool aggiunto (`skool_member_joined`) | Qualcuno si unisce a una community Skool che possiedi o gestisci, con il suo profilo, le risposte e il punteggio di idoneità. | `group_id`, `create_contact` |
| Membro Skool qualificato (`skool_member_qualified`) | Le risposte di un nuovo membro Skool raggiungono o superano la tua soglia. | `min_score` |

**Trattative**

| Trigger (`kind`) | Si attiva quando | Impostazioni |
|---|---|---|
| Trattativa creata (`deal_created`) | Una nuova trattativa viene aggiunta a una delle tue pipeline. | `pipeline_id`, `stage_id` |
| Fase trattativa cambiata (`deal_stage_changed`) | Una trattativa si sposta in una fase diversa, indicando la fase di partenza e quella di arrivo. | `pipeline_id`, `to_stage_id`, `from_stage_id` |
| Trattativa aggiornata (`deal_updated`) | Un campo della trattativa cambia. | `field` |

**Appuntamenti**

| Trigger (`kind`) | Si attiva quando | Impostazioni |
|---|---|---|
| Appuntamento prenotato (`appointment_booked`) | Viene prenotato un nuovo appuntamento. | nessuno |
| Appuntamento annullato (`appointment_cancelled`) | Un appuntamento prenotato viene annullato. | nessuno |
| Appuntamento riprogrammato (`appointment_rescheduled`) | Un appuntamento prenotato viene spostato a un altro orario, con l'orario precedente indicato accanto a quello nuovo. | `event_id` |
| Prima di un appuntamento (`appointment_upcoming`) | Un tempo prestabilito prima di ogni appuntamento confermato, per i promemoria. Fino a cinque promemoria per automazione. | `offsets_minutes` |

**Attività**

| Trigger (`kind`) | Si attiva quando | Impostazioni |
|---|---|---|
| Attività creata (`task_created`) | Viene creata un'attività. | `task_type` |
| Attività completata (`task_completed`) | Un'attività viene spostata in una fase di completamento. | nessuno |

**Account**

| Trigger (`kind`) | Si attiva quando | Impostazioni |
|---|---|---|
| Saldo crediti basso (`low_credit_balance`) | Il tuo saldo crediti scende sotto la soglia di avviso. | nessuno |
| Canale connesso (`channel_connected`) | Uno dei tuoi canali termina la connessione. | `channel` |
| Canale disconnesso (`channel_disconnected`) | Uno dei tuoi canali si interrompe: disconnesso, scollegato o interrotto. Un numero WhatsApp Web che si riconnette da solo conta solo se rimane inattivo per più di 30 minuti. | `channel` |

**Agenzia**

| Trigger (`kind`) | Si attiva quando | Impostazioni |
|---|---|---|
| Sotto-account creato (`sub_account_created`) | Viene creato un nuovo account cliente, dalla tua dashboard, dall'API o dalla tua pagina di registrazione. | nessuno |
| Attività sotto-account (`sub_account_event`) | Succede qualcosa su uno dei tuoi account cliente: crediti in esaurimento, connessione di un canale, cambio di piano. | `event`, `threshold` |

**Generale e app**

| Trigger (`kind`) | Si attiva quando | Impostazioni |
|---|---|---|
| Pianificato (`schedule`) | Secondo una pianificazione cron. | `cron`, `timezone` |
| Webhook (`webhook`) | Un sistema esterno chiama l'indirizzo webhook dell'automazione. | `webhook_secret` |
| Funzione Agente IA (`agent_function`) | Il tuo agente IA chiama questa automazione come funzione durante una conversazione. | `function_name`, `function_description`, `parameters`, `agent_ids`, `campaign_ids` |
| Nuovo elemento feed (`rss`) | Un nuovo elemento appare in un feed RSS o Atom. | `feed_url` |
| Email ricevuta (`email_received`) | Un'email arriva nella tua casella di posta collegata. | `from_contains`, `subject_contains` |
| Evento app (`app_event`) | Succede qualcosa in un'app collegata: cambia la fase di una trattativa, arriva un pagamento, viene inviato un modulo. | `toolkit`, `trigger_slug`, `connected_account_id`, `config` |
| Esecuzione manuale (`manual`) | Solo quando viene avviata manualmente. | nessuno |

Un'automazione può contenere al massimo un trigger per ciascuno di `webhook`, `app_event`, `agent_function`, `rss`, `schedule`, `email_received`, `appointment_upcoming` e `contact_added`. Un trigger che si attiva quando viene creato un record non può essere abbinato all'azione che crea lo stesso record, perché l'automazione innescherebbe se stessa.

Per sapere cosa trasmette ogni trigger ai passaggi successivi (`output_keys`) e per l'elenco completo delle azioni con i relativi parametri, leggi `GET /automations/steps`. La [Guida alle automazioni](../automations/automations.md#triggers) spiega ogni trigger con le parole del builder.

---

## Errori

Ogni errore ha la solita forma `{ "success": false, "error_code": <status>, "error": "..." }`. Un grafo rifiutato aggiunge `code` e `errors`: `errors` elenca ogni problema, con una frase correggibile ciascuno, e `error` è il primo. Correggi esattamente ciò che è elencato e invia nuovamente l'intero grafo. `code` è uno tra `invalid_graph`, `automation_graph_has_a_cycle`, `self_triggering_automation`, `no_trigger` o un altro codice proveniente dal builder.

| Stato | Quando |
|---|---|
| `400` | Il grafo è stato rifiutato, manca un campo obbligatorio (`name` o `graph` durante una creazione, `folder_id` durante uno spostamento), un aggiornamento non ha inviato nulla da modificare, un id non è valido, o il nome di una cartella manca, è vuoto o troppo lungo (`code: "invalid_name"`). |
| `403` | L'account non dispone di Automazioni; il piano di un account cliente non include la creazione e la modifica di automazioni (solo scrittura); oppure l'accesso alle **Automazioni** del membro del team è troppo limitato. |
| `404` | Nessuna automazione con quell'id su questo account, nessuna cartella con quell'id (`code: "folder_not_found"`), o un `sub_account_id` che non è uno dei tuoi account cliente. |
| `409` | Una cartella con quel nome esiste già (`code: "folder_name_taken"`). |
| `413` | L'automazione è più grande di 1 MB, il limite accettato dal builder. Sposta codice o dati di grandi dimensioni fuori dai passaggi. |
| `422` | Il builder ha rifiutato la richiesta per un altro motivo. Controlla il grafo rispetto a `GET /automations/steps`; inviare nuovamente la stessa richiesta non sarà d'aiuto. |
| `503` | Il servizio di automazione non è raggiungibile. Riprova tra un momento. Per una creazione, elenca prima le tue automazioni in modo da non creare una seconda bozza. |

::: master-only
## Utilizzo di questi endpoint tramite MCP

Ogni endpoint in questa pagina è anche uno strumento per un assistente IA che [colleghi tramite MCP](../integrations/connect-ai-clients.md), con le stesse regole: una nuova automazione è una bozza finché non viene abilitata, e una modifica a un'automazione in esecuzione è immediata.

| Strumento | Endpoint |
|---|---|
| `list_automations` | `GET /automations` |
| `get_automation` | `GET /automations/{automationId}` |
| `list_automation_steps` | `GET /automations/steps` |
| `create_automation` | `POST /automations` |
| `update_automation` | `PUT /automations/{automationId}` |
| `enable_automation` | `POST /automations/{automationId}/enable` |
| `disable_automation` | `POST /automations/{automationId}/disable` |
| `list_automation_runs` | `GET /automations/{automationId}/runs` |
| `list_automation_folders` | `GET /automations/folders` |
| `create_automation_folder` | `POST /automations/folders` |
| `rename_automation_folder` | `PUT /automations/folders/{folderId}` |
| `delete_automation_folder` | `DELETE /automations/folders/{folderId}` |
| `move_automation_to_folder` | `PUT /automations/{automationId}/folder` |
:::

---

## Passaggi successivi

- [Automazioni](../automations/automations.md): come funzionano trigger, passaggi, variabili e cronologia delle esecuzioni nel builder.
- [API per Agenzie](../agency/api-for-agencies.md): crea automazioni su un account cliente con `sub_account_id`.
- [Riferimento API](reference.md): l'esploratore interattivo completo degli endpoint.