# Conecta tu aplicación a una automatización

Envía un evento de aplicación cuando algo ocurra en tu sistema, como la creación de un pedido o la llegada de un pago. Un evento puede iniciar una ejecución, continuar una ejecución que lo esté esperando o cancelar una ejecución con una regla de cancelación coincidente. Cada automatización tiene una URL de evento para los tres usos.

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

Si no puedes abrir Automations o crear un borrador, consulta [controles de acceso y edición del espacio de trabajo](/docs/guides/automations/troubleshooting#automations-is-missing-from-the-dashboard).

## Configura el evento que inicia una ejecución

1. Crea una automatización con **Event from your application** como disparador.
2. Establece **Event name**, por ejemplo `order.created`. Los nombres distinguen entre mayúsculas y minúsculas y pueden contener letras, números, puntos, guiones bajos o guiones.
3. Define **Event fields** con los datos que envía tu aplicación. Para un pedido, añade un campo de tipo string llamado `order_id`. Los pasos posteriores pueden usar estos campos.
4. Publica la automatización. La pantalla de confirmación muestra **How to start a run**, con la URL del evento y un ejemplo de solicitud.

Para volver a encontrar los detalles de conexión, selecciona el disparador y haz clic en **How to connect your application** en la edición rápida. El editor expandido muestra los controles de conexión.

## Simula un borrador o ejecuta la versión publicada

Usa **Preview workflow** con datos de ejemplo para simular tu borrador sin enviar mensajes ni modificar datos. Ejecutar el comando cURL, hacer clic en **Send event…** o usar **Start run** ejecuta la automatización publicada y puede realizar acciones reales. Los cambios del borrador, guardados o no, no se aplican a esas ejecuciones.

Publica la automatización antes de enviar eventos. Si no tiene una versión publicada, la solicitud se rechaza de inmediato; el evento no se encola ni se guarda para después. Los ejemplos del editor pueden reflejar cambios del borrador, así que publica esos cambios antes de enviar datos que dependan de ellos.

## Copia la URL y envía un evento

Usa **Copy request** para obtener un comando cURL con la URL, las cabeceras y el cuerpo de ejemplo. Reemplaza los valores de ejemplo con los datos de tu aplicación.

La URL incluye los IDs del espacio de trabajo y de la automatización:

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

Usa la URL completa copiada desde el panel. No necesitas una cabecera `X-Workspace-Id`. La opción de autenticación actual es **No authentication**: cualquier persona con esta URL puede enviar eventos. Guárdala en la configuración de tu servidor.

Para una automatización configurada para `order.created`, establece `AUTOMATION_EVENT_URL` con la URL copiada y envía:

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

Establece `type` con el nombre del evento configurado y `data` con un objeto que coincida con los campos del evento. También puedes proporcionar `occurred_at` como una marca de tiempo RFC 3339; por defecto toma la hora en que llega el evento.

Una respuesta `202 Accepted` con `status: "queued"` confirma que el evento está en cola. Bird genera el identificador del evento y lo devuelve como `event_id`. Abre la pestaña **Runs** de la automatización para inspeccionar la ejecución. La aceptación en la cola no confirma que el evento coincidió con un disparador ni que se inició una ejecución.

También puedes usar **Send event…** en el panel para enviar el ejemplo sin un terminal. Esto envía un evento real.

## Continúa una ejecución que espera un evento

Un paso en espera usa la misma URL de automatización que el disparador. Su nombre de evento y `subject_key` identifican qué ocurrió y qué ejecución debe recibirlo.

1. En **Automation settings**, activa **Skip overlapping runs** y **Use a business key**. Establece **Business key** con un valor que identifique el pedido, la factura u otro objeto. Para el ejemplo de pedido, usa la expresión `trigger.data.data.order_id`.
2. Añade **Wait for application event** y configura su nombre de evento, campos del evento y tiempo de espera. Por ejemplo, espera `order.paid` con un campo string `payment_id`.
3. Publica, envía el evento inicial y espera hasta que su ejecución aparezca en **Runs**.
4. Envía el evento de seguimiento a la misma URL, con `subject_key` igual a la clave de negocio de la ejecución:

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

`subject_key` es el valor de la clave de negocio, como `order_123`; no es el ID del evento ni el ID de la ejecución. La vista de conexión expandida del paso de espera muestra orientación para tu clave configurada.

Un evento coincidente se puede capturar después de que la ejecución comience, incluso antes de que llegue al paso en espera. Los eventos procesados antes de que exista una ejecución coincidente no se guardan para una ejecución futura. Una espera con filtro continúa solo cuando coinciden tanto los campos del evento como el filtro. La ejecución toma la ruta de tiempo de espera agotado si no se procesa ningún evento elegible antes de la fecha límite.

Las reglas de cancelación en **Automation settings** también usan esta URL. Una regla puede apuntar a todas las ejecuciones activas de la automatización o a la ejecución que coincida con `subject_key`. Configura un filtro para limitar qué ejecuciones cancela. La cancelación no puede deshacer una acción que ya ocurrió.

## Versiones publicadas y automatizaciones en pausa

Las nuevas ejecuciones usan la versión activa cuando se procesa el evento. Las ejecuciones existentes conservan su versión original, incluidos sus campos de evento y condiciones de espera. Publicar un formato de evento modificado no actualiza las ejecuciones que ya comenzaron.

Pausar una automatización publicada detiene las nuevas ejecuciones. Los eventos aún pueden continuar o cancelar ejecuciones existentes mientras está en pausa.

## Gestiona la entrega y los reintentos

Los eventos se procesan de forma asíncrona y pueden reintentarse o procesarse en un orden diferente. Espera a que la ejecución inicial exista antes de enviar un evento de seguimiento. El `occurred_at` de un evento no controla el orden de procesamiento, no extiende una espera ni previene un tiempo de espera agotado.

La protección contra reintentos es limitada. Si los registros de reintento expiran o se pierden, un evento puede procesarse de nuevo, potencialmente contra una versión más reciente o una ejecución activa diferente. Diseña tu aplicación para tolerar eventos duplicados.

Para activar la protección contra reintentos, envía un `Idempotency-Key` en el primer intento y reutilízalo con la misma URL y el mismo cuerpo sin cambios en los reintentos. Usa una clave nueva para cada solicitud nueva. Una repetición devuelve el mismo `event_id`. La [guía de idempotencia](/docs/guides/idempotency) explica la ventana limitada de repetición y las respuestas de conflicto.

## Soluciona problemas de un evento

- **La solicitud devuelve 4xx:** Revisa los detalles de error de la respuesta, la URL y los campos obligatorios `type` y el objeto `data`. Envía `Content-Type: application/json`. El cuerpo completo de la solicitud debe caber en 25 KB (25.000 bytes); los cuerpos más grandes devuelven `413`.
- **La automatización no se ha publicado:** Publícala antes de enviar un evento. El evento rechazado no se retiene; envía una nueva solicitud después de publicar.
- **La solicitud devuelve 202 pero no se inicia ninguna ejecución:** Comprueba que la automatización esté activa, que el nombre del evento coincida con su trigger y que los datos coincidan con los campos de evento publicados. La protección contra solapamiento puede omitir una nueva ejecución mientras otra esté activa. Comprueba también la [cuota mensual de ejecuciones](/docs/guides/automations/runs#early-access-run-allowance); las ejecuciones omitidas al alcanzar el límite no se encolan para el mes siguiente.
- **La ejecución se queda en un paso en espera:** Comprueba el nombre del evento, la clave de negocio exacta, los campos de datos, el filtro y el tiempo de espera. Usa el formato de evento de la versión publicada original de la ejecución.
- **Un reintento devuelve un conflicto:** Reintenta con la clave original y la solicitud sin cambios. Si pretendes enviar un evento diferente, usa una clave nueva.

La respuesta de error de la solicitud se verifica antes de encolar. Los datos del evento se verifican contra el disparador, la espera y las reglas de cancelación durante el procesamiento, por lo que un evento encolado puede no coincidir con ninguno de ellos.

## Próximos pasos

- [Abre **Automations**](https://bird.com/dashboard/w/automations) para configurar y publicar tu flujo de trabajo.
- [Gestiona reintentos idempotentes](/docs/guides/idempotency) en tu aplicación.
- [Espera un evento](/docs/guides/automations/waits) en un flujo de trabajo en ejecución.
- [Explora las guías de Automations](/docs/guides/automations).

## Related resources

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