# Gerenciar automações pela API

O grupo `/api/v1/automations` exige `API_ACCESS` e `ADVANCED_API`. Leituras exigem `automations.view`; escritas exigem `automations.edit`, além das regras de papel da API.

## Consultar antes de escrever

Use o catálogo de gatilhos em `GET /api/v1/automations/triggers`. Consulte uma automação existente para conhecer sua definição. Novos fluxos usam `graphDefinition`, com nós e conexões; o formato legado `actions` permanece para compatibilidade.

O identificador do canal de saída deve ser obtido no aplicativo ou na configuração da integração. Não existe uma rota pública de catálogo de canais neste contrato.

## Criar ou substituir

O corpo exige `name`, `triggerType` e `scope`. Escopo `pipeline` exige `pipelineId`; `stage` exige `stageId`. Gatilhos `manual` e `webhook` usam escopo `global`.

`respectBusinessHours` e uma `triggerWindow` não vazia são mutuamente exclusivos. O gatilho manual não aceita essas regras nem condições de disparo.

Na criação, omitir `enabled` ativa o fluxo. Envie `enabled: false` enquanto prepara a definição. A substituição exige revisar o fluxo completo; consulte a operação apropriada para mudar apenas o estado de ativação.

## Segredos e teste de webhook

As leituras ocultam segredos de webhook. Quando uma criação ou atualização gerar um segredo, guarde-o na resposta em que ele for exibido.

`POST /api/v1/automations/{id}/test` retorna o corpo assinado que a primeira ação de webhook enviaria. Não envia o webhook nem executa o fluxo. Exige permissão de edição porque calcula a assinatura com o segredo real.

## Execuções

A API permite consultar execuções, nós, logs e entregas. Use a paginação e os filtros documentados em cada rota. Os dados de uma execução representam sua definição na ocasião; editar o fluxo atual não reescreve o passado.

Não existe neste grupo uma rota para iniciar manualmente a execução. No aplicativo, use [Acionamento manual](/automacoes/nos/gatilho-manual/). Para avaliar caminhos sem efeitos reais, use o [Playground](/automacoes/simular/) quando habilitado.