# API de Automações

Uma automação é um fluxo de trabalho composto por etapas: um ou mais gatilhos que o iniciam, seguidos por ações, condições, atrasos, etapas de IA e o restante, conectados em um grafo. É a mesma automação que você vê e edita na página de [Automações](../automations/automations.md). Este guia aborda como ler e criar automações por meio da API.

- **URL base**: `https://api.dmchamp.com/v1`
- **Autenticação**: sua chave de API (veja [Autenticação](authentication.md))
- **Campos e corpos**: cada parâmetro e campo de resposta está na [Referência da API](reference.md#tag/automations)
- **Erros**: veja [Erros e Paginação](errors-and-pagination.md) e [Erros](#errors) abaixo

> **Agências:** todos os endpoints nesta página aceitam `sub_account_id` como um parâmetro de consulta, para que você possa ler e criar as automações de um cliente com sua chave de agência. Um `sub_account_id` que não seja uma das contas de seus clientes retornará `404`. Consulte [API para Agências](../agency/api-for-agencies.md).

---

## Como funciona: primeiro o rascunho

A API foi criada para que nada comece a ser executado por acidente.

1. **Leia o catálogo.** `GET /automations/steps` lista todos os gatilhos, ações e tipos de etapas que você pode usar, além da gramática para escrever um grafo (`graph_rules`).
2. **Crie um rascunho.** `POST /automations` armazena a automação **desligada**. Nada é executado ainda.
3. **Verifique.** Leia-a novamente, abra-a no construtor (a resposta fornece seu `open_path`) e certifique-se de que o proprietário da conta tenha visto o que ela faz e para quem.
4. **Ligue-a.** `POST /automations/{automationId}/enable` é uma chamada própria. Esta é a etapa que faz as coisas acontecerem de verdade: mensagens enviadas, registros alterados, ferramentas fornecidas a um agente de IA.

Editar nunca altera se uma automação está ligada ou desligada. Isso também significa que uma edição em uma automação que está **ligada** entra em vigor imediatamente, na automação ativa. Para alterar uma automação em execução com segurança, desative-a, edite-a, verifique-a e ative-a novamente.

Todo grafo que você envia passa pelas mesmas verificações que a tela do construtor aplica. Um grafo que não pode ser aberto ou executado é recusado com um `400` que lista exatamente o que precisa ser corrigido.

### Acesso

- A conta precisa de Automações. Sem isso, todas as chamadas nesta página retornam `403`.
- O acesso de um membro da equipe segue sua área de **Automações** em [Gerenciamento de Equipe](../settings/team-management.md): ler (listar, obter, etapas, execuções, pastas) requer **Visualizar**, tudo o que altera algo requer **Editar**.
- Em uma conta de cliente cujo plano não permite criar e editar automações, as chamadas de escrita retornam `403`, exatamente como o construtor faz no aplicativo.

---

## Endpoints

| Tarefa | Método + caminho | Explorador |
|---|---|---|
| Listar automações | `GET /automations` | [Abrir na Referência da API](reference.md#tag/automations/GET/automations) |
| Obter uma automação com seu grafo | `GET /automations/{automationId}` | [Abrir na Referência da API](reference.md#tag/automations/GET/automations/{automationId}) |
| Ler o catálogo de etapas | `GET /automations/steps` | [Abrir na Referência da API](reference.md#tag/automations/GET/automations/steps) |
| Criar uma automação (rascunho) | `POST /automations` | [Abrir na Referência da API](reference.md#tag/automations/POST/automations) |
| Atualizar uma automação | `PUT /automations/{automationId}` | [Abrir na Referência da API](reference.md#tag/automations/PUT/automations/{automationId}) |
| Ativar | `POST /automations/{automationId}/enable` | [Abrir na Referência da API](reference.md#tag/automations/POST/automations/{automationId}/enable) |
| Desativar | `POST /automations/{automationId}/disable` | [Abrir na Referência da API](reference.md#tag/automations/POST/automations/{automationId}/disable) |
| Ler o histórico de execução | `GET /automations/{automationId}/runs` | [Abrir na Referência da API](reference.md#tag/automations/GET/automations/{automationId}/runs) |
| Listar pastas | `GET /automations/folders` | [Abrir na Referência da API](reference.md#tag/automations/GET/automations/folders) |
| Criar uma pasta | `POST /automations/folders` | [Abrir na Referência da API](reference.md#tag/automations/POST/automations/folders) |
| Renomear uma pasta | `PUT /automations/folders/{folderId}` | [Abrir na Referência da API](reference.md#tag/automations/PUT/automations/folders/{folderId}) |
| Excluir uma pasta | `DELETE /automations/folders/{folderId}` | [Abrir na Referência da API](reference.md#tag/automations/DELETE/automations/folders/{folderId}) |
| Mover uma automação para uma pasta | `PUT /automations/{automationId}/folder` | [Abrir na Referência da API](reference.md#tag/automations/PUT/automations/{automationId}/folder) |

---

## Lendo automações

`GET /automations` retorna resumos (sem etapas), com as alteradas mais recentemente primeiro; `folder_id=none` lista aquelas que não estão em nenhuma pasta. `GET /automations/{automationId}` adiciona o `graph` completo: cada etapa (`nodes[]`) com seu `kind`, `label`, `alias`, `action`, `params` e `config`, e as conexões (`edges[]`) com `from`, `to` e, após uma condição ou similar, `branch`.

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

**Bom saber**

- **`alias` é como etapas posteriores leem a saída de uma etapa**, como `${nodes.<alias>.<field>}`. Uma etapa sem isso é referenciada pelo seu id.
- `params` é mantido para leitores mais antigos; `config` carrega os mesmos valores e mais (regras de uma condição, prompt de uma etapa de IA, duração de um atraso, slug e parâmetros de uma ação).
- **Segredos são ocultados.** Valores que parecem credenciais (segredos de webhook, tokens, chaves de API, senhas, valores de cabeçalho) retornam como `"[redacted]"`. Envie `"[redacted]"` de volta inalterado e o valor armazenado será mantido.
- **Textos longos são encurtados.** Um único texto com mais de cerca de 4.000 caracteres é cortado e termina com reticências. Se você enviar essa etapa de volta, coloque o texto completo nela primeiro.
- Se o serviço de automação não puder ser alcançado, você recebe um `503`, nunca uma lista vazia em seu lugar. Uma lista vazia sempre significa que não há automações.

### O catálogo de etapas

`GET /automations/steps` retorna tudo a partir do qual uma automação pode ser construída: os 8 `node_kinds`, cada gatilho com suas configurações `fields` e `output_keys`, os `actions` integrados com seus parâmetros, as `api_actions` (operações desta API que uma etapa de ação pode chamar), a gramática `graph_rules` e `counts`. Isso é o que o construtor **oferece**, não o que a conta construiu: verifique antes de concluir que um gatilho ou ação não existe.

- Sem `q`, as centenas de ações da API retornam como rótulos agrupados por área em `api_actions_by_tag` e a lista simples fica vazia.
- Com `q` (uma palavra que não diferencia maiúsculas de minúsculas), `api_actions` é a lista simples de correspondências, limitada a 60 (`api_actions_truncated` diz quando). Ações para aplicativos de terceiros conectados também são pesquisadas e retornam em `app_actions`: pesquise pelo nome do aplicativo, por exemplo `q=hubspot`. Cada um diz se a conta tem esse aplicativo `connected`, e `connected_apps` lista os conectados. `app_actions_unavailable` é `true` quando as ações do aplicativo não puderam ser pesquisadas desta vez; as outras listas ainda estão completas.

---

## Criando e editando

### Criar um rascunho

```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` são normais, não uma falha: uma nova automação é sempre um rascunho até que você a ative. `warnings` lista o que o construtor não conseguiu concluir, como rótulos curtos (por exemplo, `agent_function:not_linked`).

**Escrevendo o grafo.** `graph_rules` do catálogo é a gramática completa. Em resumo:

- Cada nó tem um `id` (único no grafo), um `type` (um dos 8 [tipos de etapa](#step-kinds)), um `label` opcional e suas configurações em `data` sob uma chave nomeada de acordo com seu tipo (`data.trigger`, `data.action`, `data.condition`, `data.delay`, `data.ai`, `data.loop`, `data.transform`, `data.respond`).
- Uma automação precisa de pelo menos um gatilho. A gramática ativa permite até 10, e a automação começa quando qualquer um deles é disparado.
- Toda outra etapa deve ser alcançável a partir de um gatilho, e nenhuma conexão pode levar de volta a uma etapa anterior.
- Arestas que saem de uma condição carregam `sourceHandle` `true` ou `false`; um loop `body` ou `done`; um atraso de Aguardar resposta `replied` ou `timed_out`. Outras arestas não têm nada.
- Slugs e parâmetros de ação vêm do catálogo. **Nunca adivinhe um id** (um agente, uma etiqueta, uma lista, um estágio): procure-o com a API primeiro ou deixe o campo como `""` para a pessoa escolher no construtor.
- Posições são opcionais; etapas sem uma são organizadas automaticamente.
- Valores de etapas anteriores são escritos como `${trigger.<field>}` e `${nodes.<step>.<field>}`. Veja [Usando o que uma etapa anterior retornou](../automations/automations.md#using-what-an-earlier-step-returned) e [Expressões](../automations/automations.md#expressions).
- O grafo é aceito em duas grafias: a do próprio construtor (acima) e a que uma leitura responde (`kind`, `config`, `from`, `to`, `branch`). Assim, você pode ler uma automação, alterar uma etapa e enviá-la de volta.
- **Não é seguro repetir uma criação cegamente.** Se uma solicitação exceder o tempo limite, liste suas automações antes de enviá-la novamente, ou você pode acabar com dois rascunhos.

### Atualizar

`PUT /automations/{automationId}` altera `name`, `description` e/ou `graph` (pelo menos um, ou `400`). Um `graph` substitui o grafo **inteiro**, portanto, trabalhe sempre a partir do que está armazenado: leia-o, altere o que precisar e envie o grafo completo de volta.

```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)" }'
```

- **Mantenha o `alias` de cada etapa exatamente como você o recebeu.** Se alterá-lo ou removê-lo, todas as referências a essa etapa ficarão vazias. Veja [Nomeando suas etapas](../automations/automations.md#naming-your-steps).
- **Deixe os valores de `"[redacted]"` como estão** e **restaure textos encurtados** (um texto terminado em reticências foi cortado na leitura).
- O status de ativação da automação nunca é alterado aqui. Se ela estiver ativada, sua edição entra em vigor assim que for salva. Enquanto estiver ativada, uma alteração que a faria disparar sozinha será recusada: desative-a primeiro.

### Ativar e desativar

`POST /automations/{automationId}/enable` ativa uma automação para que ela seja executada a partir de seu gatilho daqui em diante. Chame-o apenas quando o proprietário da conta tiver visto o que a automação faz e para quem, e tiver concordado. O construtor recusa a ativação de um grafo que não pode ser executado (sem gatilho, com loop, ou uma etapa que dispara a si mesma) com um `400` que explica o 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` a pausa: as execuções já em andamento são concluídas, mas nenhuma nova execução é iniciada. A desativação é sempre permitida. Nenhuma das chamadas requer um corpo.

---

## Histórico de execuções

`GET /automations/{automationId}/runs` retorna as execuções de uma automação, da mais recente para a mais antiga (`limit` de 1 a 50, padrão 10): quando cada uma começou e terminou, o que a disparou, se foi bem-sucedida e o erro caso tenha falhado. Ler a automação informa o que ela **faria**; o histórico de execuções informa o que ela **fez**, sendo a única maneira de distinguir uma automação que nunca foi executada de uma que é executada e falha todas as vezes.

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

- `mode` é `live` para uma execução real, ou `safe` para uma **Execução segura** a partir do editor. Uma execução segura não envia nada, portanto, não é prova de que a automação funciona em uso real.
- Uma lista `runs` vazia é uma resposta, não uma falha. A resposta então contém um `note`: ou o gatilho nunca foi disparado, ou a automação está desativada.

---

## Pastas

As pastas apenas agrupam automações na lista. Elas nunca alteram o que uma automação faz ou se ela está ligada. Veja [Organizando automações em pastas](../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" }'
```

- Listar pastas também retorna `unfiled_count`, que indica quantas automações não estão em nenhuma pasta.
- Um nome de pasta é obrigatório, pode ter até 100 caracteres e deve ser único na conta (`409`, `code: "folder_name_taken"`). Você também pode organizar uma automação passando `folder_id` ao criá-la.
- Renomear não altera a localização das automações.
- **Excluir uma pasta exclui apenas a pasta.** Suas automações passam a não estar em nenhuma pasta e continuam sendo executadas exatamente como antes; a resposta informa quantas foram movidas (`moved_to_no_folder`).
- Ao mover, `folder_id` é obrigatório; envie `null` para remover a automação de sua pasta.

---

## Catálogo

### Tipos de etapa

| Tipo | O que faz |
|---|---|
| `trigger` | Inicia a automação quando algo acontece. |
| `action` | Executa uma etapa: uma ação integrada, uma ação de API, uma ação de aplicativo conectado, uma solicitação HTTP ou um e-mail. |
| `condition` | Divide o fluxo com base em uma regra, em um ramo `true` e um `false`. |
| `transform` | Executa um pequeno trecho de código para reformatar dados entre as etapas. |
| `ai` | Consulta a IA com um prompt que você escreve. Pode retornar texto, campos separados ou escolher um entre vários ramos. |
| `delay` | Aguarda por um tempo definido ou aguarda a resposta do contato (com um tempo limite). |
| `loop` | Repete as etapas dentro dele para cada item em uma lista. |
| `respond` | Retorna uma resposta para a chamada de webhook ou a chamada de função do agente de IA que iniciou a execução. |

### Gatilhos

Estes são os 40 gatilhos que o catálogo lista hoje, agrupados conforme o construtor os agrupa. A coluna **Configurações** contém as chaves de configuração do próprio gatilho (`fields`), que restringem quando ele é disparado. Todo gatilho também aceita `respect_quiet_hours`, `run_hours`, `reentry` e `stop_on_response`; veja [Configurações de automação](../automations/automations.md#automation-settings).

**Mensagens**

| Gatilho (`kind`) | Dispara quando | Configurações |
|---|---|---|
| Mensagem recebida (`incoming_message`) | Um contato envia uma mensagem em qualquer canal. | `campaign` (limita a um agente de IA), `channel`, `message_filter_contains` (palavra-chave), `message_filter_regex` (padrão) |
| Chamada perdida (`missed_call`) | Alguém liga para um de seus números do WhatsApp Web ou seu próprio número SMS e ninguém atende. | `to_number` |
| Mensagem entregue (`message_delivered`) | Uma mensagem que você enviou é confirmada como entregue pelo canal. | `channel`, `agent` |
| Falha na mensagem (`message_failed`) | Uma mensagem que você enviou não pôde ser entregue, com o erro. | `channel`, `agent` |
| Mensagem enviada (`message_sent`) | Qualquer mensagem sai da sua conta: da IA, sua, uma transmissão, um acompanhamento. Filtre-a, ou ela será executada em todas elas. | `channel`, `sent_by` |
| Acompanhamento enviado (`follow_up_sent`) | Um acompanhamento automático é enviado. | nenhum |
| Acompanhamento ignorado (`follow_up_skipped`) | Um acompanhamento foi retido porque sua condição de envio falhou. | nenhum |
| Acompanhamentos finalizados (`follow_up_exhausted`) | Um contato recebeu o último acompanhamento da sequência e nada mais está na fila. | nenhum |
| Conversa encerrada (`conversation_closed`) | Um chat é encerrado, com como terminou e um resumo. | `channel`, `agent` |
| Transmissão finalizada (`broadcast_completed`) | Uma transmissão terminou de ser enviada, com quantos foram enviados e quantos falharam. | nenhum |
| Resposta de lead classificada (`outreach_reply_labelled`) | A resposta de um lead de e-mail frio é classificada, por exemplo, como Interessado. | `label` |
| Comentário no Skool recebido (`skool_comment_received`) | Um membro comenta em uma postagem do Skool que uma de suas regras de comentário monitora. | nenhum |

**Contatos**

| Gatilho (`kind`) | Dispara quando | Configurações |
|---|---|---|
| Novo contato (`contact_created`) | Uma nova pessoa entra em contato com você pela primeira vez em qualquer canal, e também para importações, a API e contatos que você cria manualmente. | nenhum |
| Contato atualizado (`contact_updated`) | Um campo de contato é alterado. | `field` |
| Contatos que você adiciona aqui (`contact_added`) | Apenas para contatos que você mesmo coloca nesta automação a partir da página de Contatos. Uma execução por contato. | nenhum |
| Tag aplicada (`tag_applied`) | Uma tag é adicionada a um contato, pelo seu agente de IA, uma pessoa, uma automação ou uma importação. | `tag_name`, `channel`, `applied_by` |
| Tag removida (`tag_removed`) | Uma tag é removida de um contato. | `tag_name`, `channel` |
| Membro do Skool entrou (`skool_member_joined`) | Alguém entra em uma comunidade Skool que você possui ou gerencia, com seu perfil, respostas e pontuação de adequação. | `group_id`, `create_contact` |
| Membro do Skool qualificado (`skool_member_qualified`) | As respostas de um novo membro do Skool atingem ou superam seu limite. | `min_score` |

**Negócios**

| Gatilho (`kind`) | Dispara quando | Configurações |
|---|---|---|
| Negócio criado (`deal_created`) | Um novo negócio é adicionado a um de seus funis. | `pipeline_id`, `stage_id` |
| Estágio do negócio alterado (`deal_stage_changed`) | Um negócio é movido para um estágio diferente, nomeando o estágio que ele deixou e o que ele entrou. | `pipeline_id`, `to_stage_id`, `from_stage_id` |
| Negócio atualizado (`deal_updated`) | Um campo de negócio é alterado. | `field` |

**Compromissos**

| Gatilho (`kind`) | Dispara quando | Configurações |
|---|---|---|
| Agendamento marcado (`appointment_booked`) | Um novo agendamento é marcado. | nenhum |
| Agendamento cancelado (`appointment_cancelled`) | Um agendamento marcado é cancelado. | nenhum |
| Agendamento remarcado (`appointment_rescheduled`) | Um agendamento marcado é movido para outro horário, com o horário antigo ao lado do novo. | `event_id` |
| Antes de um agendamento (`appointment_upcoming`) | Um tempo definido antes de cada agendamento confirmado, para lembretes. Até cinco lembretes por automação. | `offsets_minutes` |

**Tarefas**

| Gatilho (`kind`) | Dispara quando | Configurações |
|---|---|---|
| Tarefa criada (`task_created`) | Uma tarefa é criada. | `task_type` |
| Tarefa concluída (`task_completed`) | Uma tarefa é movida para um estágio concluído. | nenhum |

**Conta**

| Gatilho (`kind`) | Dispara quando | Configurações |
|---|---|---|
| Saldo de crédito baixo (`low_credit_balance`) | Seu saldo de crédito cai abaixo do seu limite de alerta. | nenhum |
| Canal conectado (`channel_connected`) | Um de seus canais termina de conectar. | `channel` |
| Canal desconectado (`channel_disconnected`) | Um de seus canais cai: desconectado, desvinculado ou cortado. Um número do WhatsApp Web que reconecta sozinho só conta se ainda estiver fora do ar após 30 minutos. | `channel` |

**Agência**

| Gatilho (`kind`) | Dispara quando | Configurações |
|---|---|---|
| Subconta criada (`sub_account_created`) | Uma nova conta de cliente é criada, a partir do seu painel, da API ou da sua página de inscrição. | nenhum |
| Atividade da subconta (`sub_account_event`) | Algo acontece em uma de suas contas de cliente: créditos ficando baixos, um canal conectando, uma mudança de plano. | `event`, `threshold` |

**Geral e aplicativos**

| Gatilho (`kind`) | Dispara quando | Configurações |
|---|---|---|
| Agendado (`schedule`) | Em um cronograma cron. | `cron`, `timezone` |
| Webhook (`webhook`) | Um sistema externo chama o endereço de webhook da automação. | `webhook_secret` |
| Função de Agente de IA (`agent_function`) | Seu agente de IA chama esta automação como uma função durante uma conversa. | `function_name`, `function_description`, `parameters`, `agent_ids`, `campaign_ids` |
| Novo item de feed (`rss`) | Um novo item aparece em um feed RSS ou Atom. | `feed_url` |
| E-mail recebido (`email_received`) | Um e-mail chega na sua caixa de entrada conectada. | `from_contains`, `subject_contains` |
| Evento de aplicativo (`app_event`) | Algo acontece em um aplicativo conectado: uma etapa de negócio muda, um pagamento é recebido, um formulário é enviado. | `toolkit`, `trigger_slug`, `connected_account_id`, `config` |
| Execução manual (`manual`) | Apenas quando iniciada manualmente. | none |

Uma automação pode conter no máximo um gatilho de cada tipo: `webhook`, `app_event`, `agent_function`, `rss`, `schedule`, `email_received`, `appointment_upcoming` e `contact_added`. Um gatilho que dispara quando um registro é criado não pode ser pareado com a ação que cria o mesmo registro, pois a automação dispararia a si mesma.

Para saber o que cada gatilho fornece para as etapas seguintes (`output_keys`) e a lista completa de ações com seus parâmetros, leia `GET /automations/steps`. O [Guia de Automações](../automations/automations.md#triggers) explica cada gatilho nos termos do construtor.

---

## Erros

Todo erro tem o formato usual `{ "success": false, "error_code": <status>, "error": "..." }`. Um grafo recusado adiciona `code` e `errors`: `errors` lista todos os problemas, com uma frase corrigível para cada um, e `error` é o primeiro deles. Corrija exatamente o que está listado e envie o grafo completo novamente. `code` é um dos `invalid_graph`, `automation_graph_has_a_cycle`, `self_triggering_automation`, `no_trigger` ou outro código do construtor.

| Status | Quando |
|---|---|
| `400` | O grafo foi recusado, um campo obrigatório está faltando (`name` ou `graph` na criação, `folder_id` na movimentação), uma atualização não enviou nada para alterar, um id não é válido ou um nome de pasta está faltando, vazio ou é muito longo (`code: "invalid_name"`). |
| `403` | A conta não possui Automações; o plano de uma conta de cliente não inclui criar e editar automações (apenas leitura); ou o acesso a **Automações** do membro da equipe é insuficiente. |
| `404` | Nenhuma automação com esse id nesta conta, nenhuma pasta com esse id (`code: "folder_not_found"`), ou um `sub_account_id` que não é uma de suas contas de cliente. |
| `409` | Uma pasta com esse nome já existe (`code: "folder_name_taken"`). |
| `413` | A automação é maior do que o limite de 1 MB aceito pelo construtor. Mova códigos ou dados grandes para fora de suas etapas. |
| `422` | O construtor rejeitou a solicitação por outro motivo. Verifique o grafo em relação a `GET /automations/steps`; enviar a mesma solicitação novamente não ajudará. |
| `503` | O serviço de automação não pôde ser alcançado. Tente novamente em instantes. Para uma criação, liste suas automações primeiro para não criar um segundo rascunho. |

::: master-only
## Usando estes endpoints via MCP

Cada endpoint nesta página também é uma ferramenta para um assistente de IA que você [conecta via MCP](../integrations/connect-ai-clients.md), com as mesmas regras: uma nova automação é um rascunho até ser habilitada, e uma edição em uma automação em execução entra em vigor imediatamente.

| Ferramenta | 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` |
:::

---

## Próximos passos

- [Automações](../automations/automations.md): como gatilhos, etapas, variáveis e o histórico de execução funcionam no construtor.
- [API para Agências](../agency/api-for-agencies.md): crie automações em uma conta de cliente com `sub_account_id`.
- [Referência da API](reference.md): o explorador de endpoints interativo completo.