# API de automatizaciones

Una automatización es un flujo de trabajo compuesto por pasos: uno o más activadores que lo inician, seguidos de acciones, condiciones, retrasos, pasos de IA y el resto, conectados en un gráfico. Es la misma automatización que ves y editas en la página de [Automatizaciones](../automations/automations.md). Esta guía cubre cómo leerlas y crearlas a través de la API.

- **URL base**: `https://api.dmchamp.com/v1`
- **Autenticación**: su clave de API (consulte [Autenticación](authentication.md))
- **Campos y cuerpos**: cada parámetro y campo de respuesta se encuentra en la [Referencia de la API](reference.md#tag/automations)
- **Errores**: consulte [Errores y paginación](errors-and-pagination.md) y [Errores](#errors) a continuación

> **Agencias:** cada endpoint en esta página acepta `sub_account_id` como parámetro de consulta, por lo que puedes leer y crear las automatizaciones de un cliente con tu clave de agencia. Un `sub_account_id` que no sea una de tus cuentas de cliente devolverá `404`. Consulta [API para agencias](../agency/api-for-agencies.md).

---

## Cómo funciona: primero el borrador

La API está diseñada para que nada comience a ejecutarse por accidente.

1. **Lee el catálogo.** `GET /automations/steps` enumera cada activador, acción y tipo de paso que puedes usar, además de la gramática para escribir un gráfico (`graph_rules`).
2. **Crea un borrador.** `POST /automations` almacena la automatización **desactivada**. Aún no se ejecuta nada.
3. **Compruébalo.** Léelo de nuevo, ábrelo en el generador (la respuesta te da su `open_path`) y asegúrate de que el propietario de la cuenta haya visto lo que hace y a quién afecta.
4. **Actívalo.** `POST /automations/{automationId}/enable` es su propia llamada. Este es el paso que hace que las cosas sucedan realmente: mensajes enviados, registros modificados, herramientas proporcionadas a un agente de IA.

La edición nunca cambia si una automatización está activada o desactivada. Eso también significa que una edición en una automatización que está **activada** surte efecto de inmediato, en la automatización en vivo. Para cambiar una automatización en ejecución de forma segura, desactívala, edítala, compruébala y vuelve a activarla.

Cada gráfico que envías pasa por las mismas comprobaciones que aplica el lienzo del generador. Un gráfico que no se puede abrir o ejecutar es rechazado con un `400` que enumera exactamente qué corregir.

### Acceso

- La cuenta necesita Automatizaciones. Sin esto, cada llamada en esta página devolverá `403`.
- El acceso de un miembro del equipo sigue su área de **Automatizaciones** en [Gestión de equipos](../settings/team-management.md): leer (listar, obtener, pasos, ejecuciones, carpetas) requiere **Ver**, todo lo que cambia algo requiere **Editar**.
- En una cuenta de cliente cuyo plan excluye la creación y edición de automatizaciones, las llamadas de escritura devuelven `403`, exactamente como lo hace el generador en la aplicación.

---

## Endpoints

| Tarea | Método + ruta | Explorador |
|---|---|---|
| Listar automatizaciones | `GET /automations` | [Abrir en la Referencia de la API](reference.md#tag/automations/GET/automations) |
| Obtener una automatización con su gráfico | `GET /automations/{automationId}` | [Abrir en la Referencia de la API](reference.md#tag/automations/GET/automations/{automationId}) |
| Leer el catálogo de pasos | `GET /automations/steps` | [Abrir en la Referencia de la API](reference.md#tag/automations/GET/automations/steps) |
| Crear una automatización (borrador) | `POST /automations` | [Abrir en la Referencia de la API](reference.md#tag/automations/POST/automations) |
| Actualizar una automatización | `PUT /automations/{automationId}` | [Abrir en la Referencia de la API](reference.md#tag/automations/PUT/automations/{automationId}) |
| Activarla | `POST /automations/{automationId}/enable` | [Abrir en la Referencia de la API](reference.md#tag/automations/POST/automations/{automationId}/enable) |
| Desactivarla | `POST /automations/{automationId}/disable` | [Abrir en la Referencia de la API](reference.md#tag/automations/POST/automations/{automationId}/disable) |
| Leer el historial de ejecuciones | `GET /automations/{automationId}/runs` | [Abrir en la Referencia de la API](reference.md#tag/automations/GET/automations/{automationId}/runs) |
| Listar carpetas | `GET /automations/folders` | [Abrir en la Referencia de la API](reference.md#tag/automations/GET/automations/folders) |
| Crear una carpeta | `POST /automations/folders` | [Abrir en la Referencia de la API](reference.md#tag/automations/POST/automations/folders) |
| Cambiar el nombre de una carpeta | `PUT /automations/folders/{folderId}` | [Abrir en la Referencia de la API](reference.md#tag/automations/PUT/automations/folders/{folderId}) |
| Eliminar una carpeta | `DELETE /automations/folders/{folderId}` | [Abrir en la Referencia de la API](reference.md#tag/automations/DELETE/automations/folders/{folderId}) |
| Mover una automatización a una carpeta | `PUT /automations/{automationId}/folder` | [Abrir en la Referencia de la API](reference.md#tag/automations/PUT/automations/{automationId}/folder) |

---

## Lectura de automatizaciones

`GET /automations` devuelve resúmenes (sin pasos), ordenados por los cambios más recientes primero; `folder_id=none` enumera las que no están en ninguna carpeta. `GET /automations/{automationId}` añade el `graph` completo: cada paso (`nodes[]`) con su `kind`, `label`, `alias`, `action`, `params` y `config`, y las conexiones (`edges[]`) con `from`, `to` y, después de una condición o similar, `branch`.

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

**Es bueno saberlo**

- **`alias` es la forma en que los pasos posteriores leen la salida de un paso**, como `${nodes.<alias>.<field>}`. Un paso sin uno se referencia por su id.
- `params` se mantiene para lectores antiguos; `config` lleva los mismos valores y más (las reglas de una condición, el prompt de un paso de IA, la duración de una espera, el slug y los parámetros de una acción).
- **Los secretos están ocultos.** Los valores que parecen credenciales (secretos de webhook, tokens, claves de API, contraseñas, valores de encabezado) se devuelven como `"[redacted]"`. Envíe `"[redacted]"` de vuelta sin cambios y se conservará el valor almacenado.
- **Los textos largos se acortan.** Un solo texto de más de 4000 caracteres aproximadamente se corta y termina con puntos suspensivos. Si vuelve a enviar ese paso, incluya primero el texto completo.
- Si no se puede contactar con el servicio de automatización, obtendrá un `503`, nunca una lista vacía en su lugar. Una lista vacía siempre significa que no hay automatizaciones.

### El catálogo de pasos

`GET /automations/steps` devuelve todo lo que se puede usar para construir una automatización: los 8 `node_kinds`, cada disparador con sus ajustes `fields` y `output_keys`, los `actions` integrados con sus parámetros, las `api_actions` (operaciones de esta API que un paso de acción puede llamar), la gramática `graph_rules` y `counts`. Esto es lo que el constructor **ofrece**, no lo que la cuenta ha construido: compruébelo antes de concluir que un disparador o acción no existe.

- Sin `q`, los cientos de acciones de API se devuelven como etiquetas agrupadas por área en `api_actions_by_tag` y la lista plana está vacía.
- Con `q` (una palabra que no distingue entre mayúsculas y minúsculas), `api_actions` es la lista plana de coincidencias, limitada a 60 (`api_actions_truncated` indica cuándo). También se buscan acciones para aplicaciones de terceros conectadas y se devuelven en `app_actions`: busque por el nombre de la aplicación, por ejemplo `q=hubspot`. Cada una indica si la cuenta tiene esa aplicación `connected`, y `connected_apps` enumera las conectadas. `app_actions_unavailable` es `true` cuando las acciones de la aplicación no se pudieron buscar esta vez; las otras listas siguen estando completas.

---

## Creación y edición

### Crear un borrador

```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` y `enabled: false` son normales, no un error: una nueva automatización es siempre un borrador hasta que la habilita. `warnings` enumera lo que el constructor no pudo terminar, como etiquetas cortas (por ejemplo `agent_function:not_linked`).

**Escribir el gráfico.** `graph_rules` del catálogo es la gramática completa. En resumen:

- Cada nodo tiene un `id` (único en el gráfico), un `type` (uno de los 8 [tipos de paso](#step-kinds)), un `label` opcional y sus ajustes en `data` bajo una clave nombrada según su tipo (`data.trigger`, `data.action`, `data.condition`, `data.delay`, `data.ai`, `data.loop`, `data.transform`, `data.respond`).
- Una automatización necesita al menos un disparador. La gramática activa permite hasta 10, y la automatización comienza cuando cualquiera de ellos se dispara.
- Todos los demás pasos deben ser alcanzables desde un disparador, y ninguna conexión puede conducir de vuelta a un paso anterior.
- Los bordes que salen de una condición llevan `sourceHandle` `true` o `false`; un bucle `body` o `done`; una espera de respuesta `replied` o `timed_out`. Otros bordes no tienen ninguno.
- Los slugs y parámetros de acción provienen del catálogo. **Nunca adivine un id** (un agente, una etiqueta, una lista, una etapa): búsquelo primero con la API o deje el campo como `""` para que la persona lo elija en el constructor.
- Las posiciones son opcionales; los pasos sin una se organizan automáticamente.
- Los valores de pasos anteriores se escriben como `${trigger.<field>}` y `${nodes.<step>.<field>}`. Consulte [Uso de lo que devolvió un paso anterior](../automations/automations.md#using-what-an-earlier-step-returned) y [Expresiones](../automations/automations.md#expressions).
- El gráfico se acepta en dos grafías: la propia del constructor (arriba) y la que responde una lectura (`kind`, `config`, `from`, `to`, `branch`). Por lo tanto, puede leer una automatización, cambiar un paso y enviarlo de vuelta.
- **No es seguro repetir una creación a ciegas.** Si una solicitud agota el tiempo de espera, enumere sus automatizaciones antes de enviarla de nuevo, o podría terminar con dos borradores.

### Actualizar

`PUT /automations/{automationId}` cambia `name`, `description` y/o `graph` (al menos uno, o `400`). Un `graph` reemplaza el grafo **completo**, así que trabaje siempre a partir de lo que está almacenado: léalo, cambie lo que necesite y envíe el grafo completo de vuelta.

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

- **Mantenga el `alias` de cada paso exactamente como lo recibió.** Si lo cambia o lo elimina, todas las referencias a ese paso quedarán vacías. Consulte [Cómo nombrar sus pasos](../automations/automations.md#naming-your-steps).
- **Deje los valores de `"[redacted]"` tal como están** y **restaure los textos acortados** (un texto que termina en puntos suspensivos se recortó durante la lectura).
- El estado de activación de la automatización nunca se cambia aquí. Si está activada, su edición entra en vigor tan pronto como se guarda. Mientras esté activada, se rechazará cualquier cambio que pueda provocar que se active a sí misma: desactívela primero.

### Activar y desactivar

`POST /automations/{automationId}/enable` enciende una automatización, por lo que se ejecutará según su activador a partir de ahora. Llámelo solo una vez que el propietario de la cuenta haya visto lo que hace la automatización, a quién afecta y haya dado su consentimiento. El generador se niega a activar un grafo que no puede ejecutarse (sin activador, con un bucle, o un paso que se activa a sí mismo) con un `400` que explica el 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` la pausa: las ejecuciones ya en curso finalizan, pero no se inician nuevas. La desactivación siempre está permitida. Ninguna de estas llamadas requiere un cuerpo.

---

## Historial de ejecuciones

`GET /automations/{automationId}/runs` devuelve las ejecuciones de una automatización, empezando por la más reciente (`limit` de 1 a 50, predeterminado 10): cuándo comenzó y terminó cada una, qué la inició, si tuvo éxito y el error en caso de fallo. Leer la automatización le indica lo que **haría**; el historial de ejecución le indica lo que **hizo**, y es la única forma de distinguir una automatización que nunca se ejecutó de una que se ejecuta y falla cada vez.

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

- `mode` es `live` para una ejecución real, o `safe` para una **Ejecución segura** desde el editor. Una ejecución segura no envía nada, por lo que no es prueba de que la automatización funcione en un uso real.
- Una lista `runs` vacía es una respuesta, no un vacío. La respuesta contiene entonces un `note`: o bien el activador nunca se ha disparado, o la automatización está desactivada.

---

## Carpetas

Las carpetas solo agrupan automatizaciones en la lista. Nunca cambian lo que hace una automatización ni si está activada. Consulte [Organizar automatizaciones en carpetas](../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 carpetas también devuelve `unfiled_count`, cuántas automatizaciones no están en ninguna carpeta.
- Se requiere un nombre de carpeta, de hasta 100 caracteres y único en la cuenta (`409`, `code: "folder_name_taken"`). También puede archivar una automatización pasando `folder_id` al crearla.
- Cambiar el nombre deja las automatizaciones donde están.
- **Eliminar una carpeta solo elimina la carpeta.** Sus automatizaciones se mueven a "sin carpeta" y siguen ejecutándose exactamente igual que antes; la respuesta indica cuántas se movieron (`moved_to_no_folder`).
- Al mover, se requiere `folder_id`; envíe `null` para sacar la automatización de su carpeta.

---

## Catálogo

### Tipos de pasos

| Tipo | Qué hace |
|---|---|
| `trigger` | Inicia la automatización cuando ocurre algo. |
| `action` | Ejecuta un paso: una acción integrada, una acción de API, la acción de una aplicación conectada, una solicitud HTTP o un correo electrónico. |
| `condition` | Divide el flujo según una regla, en una rama `true` y una `false`. |
| `transform` | Ejecuta un pequeño fragmento de código para transformar datos entre pasos. |
| `ai` | Consulta a la IA con un prompt que tú escribes. Puede devolver texto, campos separados o elegir entre varias ramas. |
| `delay` | Espera durante un tiempo determinado o espera a que el contacto responda (con un tiempo de espera). |
| `loop` | Repite los pasos que contiene para cada elemento de una lista. |
| `respond` | Devuelve una respuesta a la llamada de webhook o a la llamada de función del agente de IA que inició la ejecución. |

### Disparadores

Estos son los 40 disparadores que enumera el catálogo actualmente, agrupados tal como los organiza el constructor. La columna **Configuración** contiene las claves de configuración propias del disparador (`fields`), que limitan cuándo se activa. Cada disparador también acepta `respect_quiet_hours`, `run_hours`, `reentry` y `stop_on_response`; consulta [Configuración de automatización](../automations/automations.md#automation-settings).

**Mensajería**

| Disparador (`kind`) | Se activa cuando | Configuración |
|---|---|---|
| Mensaje entrante (`incoming_message`) | Un contacto envía un mensaje por cualquier canal. | `campaign` (lo limita a un agente de IA), `channel`, `message_filter_contains` (palabra clave), `message_filter_regex` (patrón) |
| Llamada perdida (`missed_call`) | Alguien llama a uno de tus números de WhatsApp Web o a tu propio número SMS y nadie contesta. | `to_number` |
| Mensaje entregado (`message_delivered`) | Un mensaje que enviaste es confirmado como entregado por el canal. | `channel`, `agent` |
| Error en mensaje (`message_failed`) | Un mensaje que enviaste no pudo ser entregado, junto con el error. | `channel`, `agent` |
| Mensaje enviado (`message_sent`) | Cualquier mensaje sale de tu cuenta: del agente de IA, tuyo, una difusión, un seguimiento. Filtra esto, o se ejecutará en todos ellos. | `channel`, `sent_by` |
| Seguimiento enviado (`follow_up_sent`) | Se envía un seguimiento automático. | ninguno |
| Seguimiento omitido (`follow_up_skipped`) | Un seguimiento se retuvo porque su condición de envío falló. | ninguno |
| Seguimientos finalizados (`follow_up_exhausted`) | Un contacto recibió el último seguimiento de la secuencia y no hay nada más en cola. | ninguno |
| Conversación cerrada (`conversation_closed`) | Se cierra un chat, indicando cómo terminó y un resumen. | `channel`, `agent` |
| Difusión finalizada (`broadcast_completed`) | Una difusión ha terminado de enviarse, indicando cuántos se enviaron y cuántos fallaron. | ninguno |
| Respuesta de lead clasificada (`outreach_reply_labelled`) | La respuesta de un lead de correo en frío es clasificada, por ejemplo como Interesado. | `label` |
| Comentario de Skool recibido (`skool_comment_received`) | Un miembro comenta en una publicación de Skool que una de tus reglas de comentarios supervisa. | ninguno |

**Contactos**

| Disparador (`kind`) | Se activa cuando | Configuración |
|---|---|---|
| Nuevo contacto (`contact_created`) | Una nueva persona te contacta por primera vez en cualquier canal, y también para importaciones, la API y contactos que creas manualmente. | ninguno |
| Contacto actualizado (`contact_updated`) | Un campo de contacto cambia. | `field` |
| Contactos que añades aquí (`contact_added`) | Solo para contactos que tú mismo añades a esta automatización desde la página de Contactos. Una ejecución por contacto. | ninguno |
| Etiqueta aplicada (`tag_applied`) | Se añade una etiqueta a un contacto, por tu agente de IA, una persona, una automatización o una importación. | `tag_name`, `channel`, `applied_by` |
| Etiqueta eliminada (`tag_removed`) | Se quita una etiqueta a un contacto. | `tag_name`, `channel` |
| Miembro de Skool unido (`skool_member_joined`) | Alguien se une a una comunidad de Skool que posees o administras, con su perfil, respuestas y puntuación de ajuste. | `group_id`, `create_contact` |
| Miembro de Skool calificado (`skool_member_qualified`) | Las respuestas de un nuevo miembro de Skool alcanzan o superan tu umbral. | `min_score` |

**Tratos**

| Disparador (`kind`) | Se activa cuando | Configuración |
|---|---|---|
| Negocio creado (`deal_created`) | Se añade un nuevo negocio a uno de tus embudos. | `pipeline_id`, `stage_id` |
| Etapa de negocio cambiada (`deal_stage_changed`) | Un negocio se mueve a una etapa diferente, indicando la etapa que dejó y a la que entró. | `pipeline_id`, `to_stage_id`, `from_stage_id` |
| Negocio actualizado (`deal_updated`) | Un campo de negocio cambia. | `field` |

**Citas**

| Disparador (`kind`) | Se activa cuando | Configuración |
|---|---|---|
| Cita reservada (`appointment_booked`) | Se reserva una nueva cita. | ninguno |
| Cita cancelada (`appointment_cancelled`) | Se cancela una cita reservada. | ninguno |
| Cita reprogramada (`appointment_rescheduled`) | Una cita reservada se mueve a otra hora, indicando la hora anterior junto a la nueva. | `event_id` |
| Antes de una cita (`appointment_upcoming`) | Un tiempo determinado antes de cada cita confirmada, para recordatorios. Hasta cinco recordatorios por automatización. | `offsets_minutes` |

**Tareas**

| Disparador (`kind`) | Se activa cuando | Configuración |
|---|---|---|
| Tarea creada (`task_created`) | Se crea una tarea. | `task_type` |
| Tarea completada (`task_completed`) | Una tarea se mueve a una etapa de completada. | ninguno |

**Cuenta**

| Disparador (`kind`) | Se activa cuando | Configuración |
|---|---|---|
| Saldo de créditos bajo (`low_credit_balance`) | Tu saldo de créditos cae por debajo de tu umbral de alerta. | ninguno |
| Canal conectado (`channel_connected`) | Uno de tus canales termina de conectarse. | `channel` |
| Canal desconectado (`channel_disconnected`) | Uno de tus canales se cae: cierre de sesión, desvinculación o corte. Un número de WhatsApp Web que se reconecta solo cuenta si sigue caído después de 30 minutos. | `channel` |

**Agencia**

| Disparador (`kind`) | Se activa cuando | Configuración |
|---|---|---|
| Subcuenta creada (`sub_account_created`) | Se crea una nueva cuenta de cliente, desde tu panel, la API o tu página de registro. | ninguno |
| Actividad de subcuenta (`sub_account_event`) | Ocurre algo en una de tus cuentas de cliente: créditos bajos, conexión de un canal, cambio de plan. | `event`, `threshold` |

**General y aplicaciones**

| Desencadenador (`kind`) | Se activa cuando | Ajustes |
|---|---|---|
| Programado (`schedule`) | Según una programación cron. | `cron`, `timezone` |
| Webhook (`webhook`) | Un sistema externo llama a la dirección de webhook de la automatización. | `webhook_secret` |
| Función de agente de IA (`agent_function`) | Su agente de IA llama a esta automatización como una función durante una conversación. | `function_name`, `function_description`, `parameters`, `agent_ids`, `campaign_ids` |
| Nuevo elemento de feed (`rss`) | Aparece un nuevo elemento en un feed RSS o Atom. | `feed_url` |
| Correo electrónico recibido (`email_received`) | Llega un correo electrónico a su propio buzón conectado. | `from_contains`, `subject_contains` |
| Evento de aplicación (`app_event`) | Ocurre algo en una aplicación conectada: cambia la etapa de un trato, se recibe un pago, se envía un formulario. | `toolkit`, `trigger_slug`, `connected_account_id`, `config` |
| Ejecución manual (`manual`) | Solo cuando se inicia manualmente. | none |

Una automatización puede contener como máximo un desencadenador de cada tipo: `webhook`, `app_event`, `agent_function`, `rss`, `schedule`, `email_received`, `appointment_upcoming` y `contact_added`. Un desencadenador que se activa cuando se crea un registro no puede combinarse con la acción que crea ese mismo registro, ya que la automatización se activaría a sí misma.

Para saber qué proporciona cada desencadenador a los pasos posteriores (`output_keys`) y ver la lista completa de acciones con sus parámetros, lea `GET /automations/steps`. La [guía de automatizaciones](../automations/automations.md#triggers) explica cada desencadenador con las palabras del constructor.

---

## Errores

Cada error tiene la forma habitual `{ "success": false, "error_code": <status>, "error": "..." }`. Un grafo rechazado añade `code` y `errors`: `errors` enumera cada problema, con una frase corregible cada uno, y `error` es el primero. Corrija exactamente lo que se enumera y envíe el grafo completo de nuevo. `code` es uno de `invalid_graph`, `automation_graph_has_a_cycle`, `self_triggering_automation`, `no_trigger`, u otro código del generador.

| Estado | Cuándo |
|---|---|
| `400` | El grafo fue rechazado, falta un campo obligatorio (`name` o `graph` en una creación, `folder_id` en un movimiento), una actualización no envió nada para cambiar, un id no es válido, o falta un nombre de carpeta, está vacío o es demasiado largo (`code: "invalid_name"`). |
| `403` | La cuenta no tiene Automatizaciones; el plan de una cuenta de cliente no incluye la creación y edición de automatizaciones (solo escritura); o el acceso a **Automatizaciones** del miembro del equipo es demasiado bajo. |
| `404` | No hay ninguna automatización con ese id en esta cuenta, no hay ninguna carpeta con ese id (`code: "folder_not_found"`), o un `sub_account_id` que no es una de sus cuentas de cliente. |
| `409` | Ya existe una carpeta con ese nombre (`code: "folder_name_taken"`). |
| `413` | La automatización es mayor que el 1 MB que acepta el generador. Mueva el código o los datos grandes fuera de sus pasos. |
| `422` | El generador rechazó la solicitud por otro motivo. Compruebe el grafo frente a `GET /automations/steps`; enviar la misma solicitud de nuevo no ayudará. |
| `503` | No se pudo contactar con el servicio de automatización. Inténtelo de nuevo en un momento. Para una creación, liste primero sus automatizaciones para no crear un segundo borrador. |

::: master-only
## Uso de estos endpoints a través de MCP

Cada endpoint en esta página es también una herramienta para un asistente de IA que [conecta a través de MCP](../integrations/connect-ai-clients.md), con las mismas reglas: una nueva automatización es un borrador hasta que se habilita, y una edición en una automatización en ejecución se aplica en tiempo real.

| Herramienta | 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 pasos

- [Automatizaciones](../automations/automations.md): cómo funcionan los desencadenadores, pasos, variables y el historial de ejecución en el constructor.
- [API para agencias](../agency/api-for-agencies.md): cree automatizaciones en una cuenta de cliente con `sub_account_id`.
- [Referencia de la API](reference.md): el explorador interactivo completo de endpoints.