# Collegare la propria applicazione a un'automazione

Invia un evento dall'applicazione quando succede qualcosa nel tuo sistema, ad esempio la creazione di un ordine o l'arrivo di un pagamento. Un evento può avviare un'esecuzione, proseguire un'esecuzione in attesa oppure annullare un'esecuzione con una regola di cancellazione corrispondente. Ogni automazione ha un unico URL evento per tutti e tre gli usi.

> Automations is in Early access. Your workspace permissions determine which actions you can perform.

Se non riesci ad aprire Automations o a creare una bozza, consulta [accesso allo spazio di lavoro e controlli di modifica](/docs/guides/automations/troubleshooting#automations-is-missing-from-the-dashboard).

## Configura l'evento che avvia un'esecuzione

1. Crea un'automazione con **Event from your application** come trigger.
2. Imposta **Event name**, ad esempio `order.created`. I nomi distinguono maiuscole e minuscole e possono contenere lettere, numeri, punti, underscore o trattini.
3. Definisci **Event fields** per i dati inviati dalla tua applicazione. Per un ordine, aggiungi un campo stringa denominato `order_id`. I passaggi successivi possono usare questi campi.
4. Pubblica l'automazione. La schermata di conferma mostra **How to start a run**, con l'URL dell'evento e un esempio di richiesta.

Per ritrovare i dettagli di connessione, seleziona il trigger e fai clic su **How to connect your application** nella modifica rapida. L'editor espanso mostra i controlli di connessione.

## Simula una bozza o esegui la versione pubblicata

Usa **Preview workflow** con dati di esempio per simulare la bozza senza inviare messaggi né modificare dati. Eseguire il comando cURL, fare clic su **Send event…** o usare **Start run** esegue l'automazione pubblicata e può compiere azioni reali. Le modifiche alla bozza, salvate o meno, non si applicano a quelle esecuzioni.

Pubblica l'automazione prima di inviare eventi. Se non esiste una versione pubblicata, la richiesta viene rifiutata immediatamente; l'evento non viene messo in coda né salvato per dopo. Gli esempi nell'editor possono riflettere le modifiche alla bozza, quindi pubblica tali modifiche prima di inviare dati che dipendono da esse.

## Copia l'URL e invia un evento

Usa **Copy request** per ottenere un comando cURL contenente URL, header e corpo di esempio. Sostituisci i valori di esempio con i dati della tua applicazione.

L'URL include gli ID dello spazio di lavoro e dell'automazione:

```text
POST https://<your-regional-api-host>/v1/hooks/automations/<workspace-id>/<automation-id>
```

Usa l'URL completo copiato dalla dashboard. Non è necessario un header `X-Workspace-Id`. L'opzione di autenticazione attuale è **No authentication**: chiunque abbia questo URL può inviare eventi. Conservalo nella configurazione del tuo server.

Per un'automazione configurata per `order.created`, imposta `AUTOMATION_EVENT_URL` sull'URL copiato e invia:

```bash
curl --request POST "$AUTOMATION_EVENT_URL" \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "order.created",
    "data": { "order_id": "order_123" }
  }'
```

Imposta `type` sul nome evento configurato e `data` su un oggetto corrispondente ai campi dell'evento. Puoi anche fornire `occurred_at` come timestamp RFC 3339; il valore predefinito è l'ora di arrivo dell'evento.

Una risposta `202 Accepted` con `status: "queued"` conferma che l'evento è in coda. Bird genera l'identificatore dell'evento e lo restituisce come `event_id`. Apri la scheda **Runs** dell'automazione per ispezionare l'esecuzione. L'accettazione in coda non conferma che l'evento abbia corrisposto a un trigger né che sia stata avviata un'esecuzione.

Puoi anche usare **Send event…** nella dashboard per inviare l'esempio senza un terminale. Questo invia un evento reale.

## Prosegui un'esecuzione in attesa di un evento

Uno step di attesa usa lo stesso URL dell'automazione del trigger. Il nome evento e `subject_key` identificano cosa è successo e quale esecuzione deve riceverlo.

1. In **Automation settings**, abilita **Skip overlapping runs** e **Use a business key**. Imposta **Business key** su un valore che identifica l'ordine, la fattura o un altro oggetto. Per l'esempio dell'ordine, usa l'espressione `trigger.data.data.order_id`.
2. Aggiungi **Wait for application event** e configura il nome evento, i campi evento e il timeout. Ad esempio, attendi `order.paid` con un campo stringa `payment_id`.
3. Pubblica, invia l'evento iniziale e attendi che la relativa esecuzione compaia in **Runs**.
4. Invia l'evento successivo allo stesso URL, con `subject_key` uguale alla business key dell'esecuzione:

```json
{
  "type": "order.paid",
  "subject_key": "order_123",
  "data": { "payment_id": "payment_456" }
}
```

`subject_key` è il valore della business key, ad esempio `order_123`; non è l'ID dell'evento né l'ID dell'esecuzione. La vista di connessione espansa dello step di attesa mostra indicazioni per la chiave configurata.

Un evento corrispondente può essere catturato dopo l'avvio dell'esecuzione, anche prima che raggiunga lo step di attesa. Gli eventi elaborati prima che esista un'esecuzione corrispondente non vengono salvati per un'esecuzione futura. Un'attesa con filtro prosegue solo quando sia i campi evento sia il filtro corrispondono. L'esecuzione segue il percorso di timeout se nessun evento idoneo viene elaborato prima della scadenza.

Anche le regole di cancellazione in **Automation settings** usano questo URL. Una regola può interessare tutte le esecuzioni attive dell'automazione oppure l'esecuzione corrispondente a `subject_key`. Configura un filtro per restringere le esecuzioni da cancellare. La cancellazione non può annullare un'azione già avvenuta.

## Versioni pubblicate e automazioni in pausa

Le nuove esecuzioni usano la versione attiva al momento dell'elaborazione dell'evento. Le esecuzioni esistenti mantengono la versione originale, inclusi i campi evento e le condizioni di attesa. Pubblicare un formato evento modificato non aggiorna le esecuzioni già avviate.

Mettere in pausa un'automazione pubblicata blocca le nuove esecuzioni. Gli eventi possono comunque proseguire o cancellare esecuzioni esistenti mentre l'automazione è in pausa.

## Gestisci consegna e ripetizioni

Gli eventi vengono elaborati in modo asincrono e possono essere ripetuti o elaborati fuori ordine. Attendi che l'esecuzione iniziale esista prima di inviare un evento successivo. Il `occurred_at` di un evento non controlla l'ordine di elaborazione, non estende un'attesa e non previene un timeout.

La protezione contro le ripetizioni è limitata. Se i record delle ripetizioni scadono o vengono persi, un evento può essere elaborato di nuovo, potenzialmente rispetto a una versione più recente o a un'esecuzione attiva diversa. Progetta la tua applicazione per tollerare eventi duplicati.

Per attivare la protezione dai tentativi ripetuti, fornisci un `Idempotency-Key` al primo tentativo, poi riutilizzalo con lo stesso URL e corpo invariato per i successivi. Usa una nuova chiave per ogni nuova richiesta. Un reinvio restituisce lo stesso `event_id`. La [guida all'idempotenza](/docs/guides/idempotency) spiega la finestra limitata di reinvio e le risposte di conflitto.

## Risolvere problemi con un evento

- **La richiesta restituisce 4xx:** Controlla i dettagli dell'errore nella risposta, l'URL e i campi obbligatori `type` e l'oggetto `data`. Invia `Content-Type: application/json`. L'intero corpo della richiesta deve rientrare in 25 KB (25.000 byte); corpi più grandi restituiscono `413`.
- **L'automazione non è stata pubblicata:** Pubblicala prima di inviare un evento. L'evento rifiutato non viene conservato; invia una nuova richiesta dopo la pubblicazione.
- **La richiesta restituisce 202 ma nessuna esecuzione parte:** Verifica che l'automazione sia attiva, che il nome dell'evento corrisponda al trigger e che i dati corrispondano ai campi evento pubblicati. La protezione dalla sovrapposizione può impedire una nuova esecuzione mentre un'altra è attiva. Controlla anche il [limite mensile di esecuzioni](/docs/guides/automations/runs#early-access-run-allowance): le esecuzioni saltate al raggiungimento del limite non vengono accodate per il mese successivo.
- **L'esecuzione resta ferma a uno step di attesa:** Controlla il nome evento, la business key esatta, i campi dati, il filtro e il timeout. Usa il formato evento della versione pubblicata originale dell'esecuzione.
- **Una ripetizione restituisce un conflitto:** Riprova con la chiave originale e la richiesta invariata. Se intendi inviare un evento diverso, usa una nuova chiave.

La risposta di errore della richiesta viene controllata prima dell'accodamento. I dati dell'evento vengono verificati rispetto al trigger, all'attesa e alle regole di cancellazione durante l'elaborazione, quindi un evento accodato può non corrispondere a nessuna di esse.

## Prossimi passaggi

- [Apri **Automations**](https://bird.com/dashboard/w/automations) per configurare e pubblicare il tuo flusso.
- [Gestisci le ripetizioni idempotenti](/docs/guides/idempotency) nella tua applicazione.
- [Attendi un evento](/docs/guides/automations/waits) in un flusso in esecuzione.
- [Esplora le guide di Automations](/docs/guides/automations).

## Related resources

- [Preview your first automation](/docs/get-started/automations) (docs)