# Conecte sua aplicação a uma automação

Envie um evento da aplicação quando algo acontecer no seu sistema, como a criação de um pedido ou a chegada de um pagamento. Um evento pode iniciar uma execução, continuar uma execução que está esperando por ele ou cancelar uma execução com uma regra de cancelamento correspondente. Cada automação tem uma única URL de evento para os três usos.

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

Se você não conseguir abrir o Automations ou criar um rascunho, consulte [controles de acesso e edição do espaço de trabalho](/docs/guides/automations/troubleshooting#automations-is-missing-from-the-dashboard).

## Configure o evento que inicia uma execução

1. Crie uma automação com **Event from your application** como gatilho.
2. Defina **Event name**, por exemplo `order.created`. Os nomes diferenciam maiúsculas de minúsculas e podem conter letras, números, pontos, underscores ou hifens.
3. Defina **Event fields** para os dados que sua aplicação envia. Para um pedido, adicione um campo string chamado `order_id`. Etapas posteriores podem usar esses campos.
4. Publique a automação. A tela de sucesso mostra **How to start a run**, incluindo a URL do evento e um exemplo de solicitação.

Para encontrar os detalhes de conexão novamente, selecione o gatilho e clique em **How to connect your application** na edição rápida. O editor expandido mostra os controles de conexão.

## Simule um rascunho ou execute a versão publicada

Use **Preview workflow** com dados de exemplo para simular seu rascunho sem enviar mensagens ou alterar dados. Executar o comando cURL, clicar em **Send event…** ou usar **Start run** executa a automação publicada e pode realizar ações reais. Alterações salvas e não salvas do rascunho não se aplicam a essas execuções.

Publique a automação antes de enviar eventos. Se ela não tiver uma versão publicada, a solicitação é rejeitada imediatamente; o evento não é enfileirado nem salvo para depois. Os exemplos do editor podem refletir alterações do rascunho, então publique essas alterações antes de enviar dados que dependam delas.

## Copie a URL e envie um evento

Use **Copy request** para obter um comando cURL contendo a URL, os cabeçalhos e o corpo de exemplo. Substitua os valores de exemplo pelos dados da sua aplicação.

A URL inclui os IDs do espaço de trabalho e da automação:

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

Use a URL completa copiada do painel. Você não precisa de um cabeçalho `X-Workspace-Id`. A opção de autenticação atual é **No authentication**: qualquer pessoa com essa URL pode enviar eventos. Mantenha-a na configuração do seu servidor.

Para uma automação configurada para `order.created`, defina `AUTOMATION_EVENT_URL` com a URL copiada e envie:

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

Defina `type` com o nome do evento configurado e `data` com um objeto correspondente aos campos do evento. Você também pode fornecer `occurred_at` como um timestamp RFC 3339; o padrão é o horário em que o evento chega.

Uma resposta `202 Accepted` com `status: "queued"` confirma que o evento está na fila. Bird gera o identificador do evento e o retorna como `event_id`. Abra a aba **Runs** da automação para inspecionar a execução. A aceitação na fila não confirma que o evento correspondeu a um gatilho ou que uma execução foi iniciada.

Você também pode usar **Send event…** no painel para enviar o exemplo sem um terminal. Isso envia um evento real.

## Continue uma execução que está aguardando um evento

Uma etapa de espera usa a mesma URL da automação que o gatilho. O nome do evento e `subject_key` identificam o que aconteceu e qual execução deve recebê-lo.

1. Em **Automation settings**, habilite **Skip overlapping runs** e **Use a business key**. Defina **Business key** com um valor que identifique o pedido, a fatura ou outro objeto. Para o exemplo de pedido, use a expressão `trigger.data.data.order_id`.
2. Adicione **Wait for application event** e configure o nome do evento, os campos do evento e o timeout. Por exemplo, aguarde `order.paid` com um campo string `payment_id`.
3. Publique, envie o evento inicial e aguarde até que a execução apareça em **Runs**.
4. Envie o evento de acompanhamento para a mesma URL, com `subject_key` igual à business key da execução:

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

`subject_key` é o valor da chave de negócio, como `order_123`; não é o ID do evento nem o ID da execução. A visualização expandida de conexão da etapa de espera mostra orientações para a chave configurada.

Um evento correspondente pode ser capturado após o início da execução, mesmo antes de ela chegar à etapa de espera. Eventos processados antes de existir uma execução correspondente não são salvos para uma execução futura. Uma espera com filtro continua apenas quando os campos do evento e o filtro correspondem. A execução segue o caminho de timeout se nenhum evento elegível for processado antes do prazo.

Regras de cancelamento em **Automation settings** também usam essa URL. Uma regra pode visar todas as execuções ativas da automação ou a execução correspondente a `subject_key`. Configure um filtro para restringir quais execuções ela cancela. O cancelamento não pode desfazer uma ação que já aconteceu.

## Versões publicadas e automações pausadas

Novas execuções usam a versão ativa quando o evento é processado. Execuções existentes mantêm sua versão original, incluindo campos do evento e condições de espera. Publicar um formato de evento alterado não atualiza execuções que já foram iniciadas.

Pausar uma automação publicada interrompe novas execuções. Eventos ainda podem continuar ou cancelar execuções existentes enquanto ela estiver pausada.

## Trate entrega e tentativas de reenvio

Eventos são processados de forma assíncrona e podem ser reenviados ou processados fora de ordem. Aguarde a execução inicial existir antes de enviar um evento de acompanhamento. O `occurred_at` de um evento não controla a ordem de processamento, não estende uma espera nem impede um timeout.

A proteção contra reenvio é limitada. Se os registros de reenvio expirarem ou forem perdidos, um evento pode ser processado novamente, potencialmente contra uma versão mais recente ou uma execução ativa diferente. Projete sua aplicação para tolerar eventos duplicados.

Para ativar a proteção contra repetição, envie um `Idempotency-Key` na primeira tentativa e reutilize-o com a mesma URL e corpo inalterado nas novas tentativas. Use uma chave nova para cada nova requisição. Uma repetição retorna o mesmo `event_id`. O [guia de idempotência](/docs/guides/idempotency) explica a janela limitada de repetição e as respostas de conflito.

## Solucione problemas de um evento

- **A solicitação retorna 4xx:** Verifique os detalhes de erro da resposta, a URL e os campos obrigatórios `type` e o objeto `data`. Envie `Content-Type: application/json`. O corpo inteiro da solicitação deve caber em 25 KB (25.000 bytes); corpos maiores retornam `413`.
- **A automação não foi publicada:** Publique-a antes de enviar um evento. O evento rejeitado não é retido; envie uma nova solicitação após publicar.
- **A requisição retorna 202, mas nenhuma execução é iniciada:** Verifique se a automação está ativa, se o nome do evento corresponde ao gatilho e se os dados correspondem aos campos de evento publicados. A proteção contra sobreposição pode ignorar uma nova execução enquanto outra estiver ativa. Verifique também a [cota mensal de execuções](/docs/guides/automations/runs#early-access-run-allowance); inícios ignorados no limite não são enfileirados para o mês seguinte.
- **A execução permanece em uma etapa de espera:** Verifique o nome do evento, a business key exata, os campos de dados, o filtro e o timeout. Use o formato de evento da versão publicada original da execução.
- **Uma tentativa de reenvio retorna conflito:** Tente novamente com a chave original e a solicitação inalterada. Se você pretende enviar um evento diferente, use uma nova chave.

A resposta de erro da solicitação é verificada antes do enfileiramento. Os dados do evento são verificados em relação ao gatilho, à espera e às regras de cancelamento durante o processamento, então um evento enfileirado pode não corresponder a nenhum deles.

## Próximos passos

- [Abra o **Automations**](https://bird.com/dashboard/w/automations) para configurar e publicar seu fluxo de trabalho.
- [Trate tentativas de reenvio idempotentes](/docs/guides/idempotency) na sua aplicação.
- [Aguarde um evento](/docs/guides/automations/waits) em um fluxo de trabalho em execução.
- [Explore os guias do Automations](/docs/guides/automations).

## Related resources

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