Operaciones de automatizaciones

Gabriel Gómez Pérez · Equipo Bukyapp· 5 min de lectura·Actualizado 17 sept 2026

Consulta, crea y edita las automatizaciones de mensajes a clientes por API v1 o MCP.

Una «automatización» es una regla de mensajería: cuando ocurre un evento de la reserva (se confirma, está a punto de empezar, acaba de terminar) o de una sesión, Buky envía un email a partir de una plantilla, sin que nadie tenga que hacer nada a mano. Para crearlas desde el panel, consulta Crear automatizaciones de email; para lo que puede llevar cada plantilla (variables de reserva, idiomas, canal), consulta Personalizar plantillas de mensajes.

Las bases comunes (autenticación, GET frente a POST, prueba en seco, errores HTTP, límites) están en API v1 — Introducción y primeros pasos. En todas las operaciones, customer_id es opcional: se toma de tu token salvo que uses un token multicuenta.

list-automations: lista las automatizaciones de mensajería

Es una operación de solo lectura: vale con cualquier token. Devuelve las automatizaciones de la cuenta en vista compacta (identificar y enumerar) o, con detail:"descriptive", con el desfase, a qué productos aplica y las plantillas de cada acción ya resueltas a su título. Es la forma de ENUMERAR qué automatizaciones existen sin tener que provocar a propósito un error en get-automation. Las borradas (borrado lógico) nunca aparecen en la lista.

Cómo llamarla

curl "https://api.bukyapp.com/v1/ops/list-automations?detail=descriptive&lang=es" \
  -H "Authorization: Bearer bk_TU_TOKEN"

Por MCP: «Enséñame las automatizaciones de mensajería que tengo configuradas».

Parámetros

Qué devuelve

Ejemplo real: la cuenta demo usada para esta guía no tiene ninguna automatización creada, así que tanto la vista compacta como la descriptiva devuelven la lista vacía:

{
  "success": true,
  "detail": "compact",
  "count": 0,
  "total": 0,
  "items": []
}

Consejos

• Antes de crear una automatización con create-automation o de editar una con update-automation, usa list-automations para ver los títulos exactos que ya existen y evitar duplicados.
• Un filtro sin coincidencias devuelve count: 0 e items: [], no un error — igual que cuando la cuenta todavía no tiene ninguna automatización.

get-automation: consulta una automatización existente

Es una operación de solo lectura. Resuelve una automatización por título o _id y devuelve el documento completo y fresco del servidor: es la forma de comprobar cómo quedó tras crearla o editarla.

Cómo llamarla

curl "https://api.bukyapp.com/v1/ops/get-automation?automation=Recordatorio%2024h" \
  -H "Authorization: Bearer bk_TU_TOKEN"

Por MCP: «Enséñame la automatización Recordatorio 24h».

Parámetros

Qué devuelve

Cuando la automatización existe, la respuesta trae _id, resolved (qué automatización se eligió y por qué) e item, el documento completo: título, trigger, actions con las plantillas vinculadas y trigger_products. La cuenta demo usada para esta guía no tiene ninguna automatización creada todavía, así que toda llamada real cayó en automation_unresolved (ver «Errores propios»); no hay un ejemplo de éxito real que enseñar aquí.

Errores propios

create-automation: crea una automatización de mensajería

Es una operación de escritura. Crea una automatización replicando el alta del panel: valida el evento disparador, resuelve la plantilla de cada acción contra el catálogo real de tu cuenta y, si filtras por producto, también los productos. Siempre envía al menos un email: actions no puede ir vacío. El script de esta guía fuerza siempre dry_run:true: no hay forma de crear una automatización de verdad con él.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/create-automation \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Recordatorio 24h",
    "trigger": "session:start:before",
    "offset_mode": "custom", "offset_quantity": 24, "offset_unit": "hours",
    "actions": [{"template": "Recordatorio de sesión", "to_mode": "pax"}],
    "trigger_products": {"mode": "someProducts", "products": ["Surf Principiante"]},
    "dry_run": true
  }'

Por MCP: «Crea una automatización que mande un recordatorio 24 horas antes de cada sesión de Surf Principiante, a cada participante».

Parámetros

Qué devuelve

Respuesta real de la prueba en seco, para un alta mínima (confirmación de reserva a todos los productos):

{
  "success": true,
  "dry_run": true,
  "resolved_trigger": { "trigger": "order:confirmed", "contextType": "order", "supportsOffset": false, "reason": "default (order:confirmed — al confirmarse la reserva)" },
  "resolved_products_mode": { "mode": "always", "requiresProducts": false, "reason": "default (always — aplica a todos los productos)" },
  "resolved_actions": [
    { "template_id": "68062452db8ece2373ccbc12", "template_reason": "match por nombre 'Nueva plantilla'", "to_mode": "buyer", "to": "", "sessionScoped": false }
  ],
  "resolved_products": [],
  "warnings": [],
  "payload_preview": {
    "title": "Prueba Documentacion Confirmacion",
    "trigger": "order:confirmed",
    "actions": [{ "template": "68062452db8ece2373ccbc12", "to_mode": "buyer", "to": "" }],
    "trigger_products_mode": "always"
  }
}

En la prueba en seco no hay _id: como no se llega a crear nada, no existe todavía. En una creación real la respuesta trae el _id de la automatización creada en su lugar.

Ejemplos

Filtrando por producto y con offset personalizado, probado en seco de verdad:

{
  "title": "Recordatorio sesión",
  "trigger": "session:start:before",
  "offset_mode": "custom", "offset_quantity": 24, "offset_unit": "hours",
  "actions": [{ "template": "Nueva plantilla", "to_mode": "pax" }],
  "trigger_products": { "mode": "someProducts", "products": ["69dba4d4b227f96a4e3b21a8"] }
}

Aviso interno a un email fijo del negocio, también probado en seco:

{
  "title": "Aviso interno nueva reserva",
  "actions": [{ "template": "Nueva plantilla", "to_mode": "custom", "to": "reservas@mareasurf.example" }]
}

Errores propios

Consejos

• Antes de fijar la plantilla o los productos, deja que la operación falle una vez: template_candidates y product_candidates te dan los nombres exactos de tu cuenta, sin adivinar.
• Usa to_mode: "pax" o "staff" solo con trigger: "session:start:before"; con un disparador de reserva la automatización se crea pero el aviso lo indica: en ese evento no hay destinatarios de sesión.
• Con trigger_products.mode: "always" (el valor por defecto) no hace falta mandar products; se ignora si lo mandas.

update-automation: edita título o disparador

Es una operación de escritura. Cambia solo los campos que le pases: título y/o evento disparador (con su offset). No sirve para tocar las acciones de email ni el filtro de productos — para recomponerlos hay que volver a llamar a create-automation. El script de esta guía fuerza siempre dry_run:true.

Cómo llamarla

curl -X POST https://api.bukyapp.com/v1/ops/update-automation \
  -H "Authorization: Bearer bk_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"automation": "Recordatorio 24h", "trigger": "order:start:before", "dry_run": true}'

Por MCP: «Cambia el disparador de la automatización Recordatorio 24h a antes de que empiece la reserva».

Parámetros

Qué devuelve

La cuenta demo de esta guía no tiene ninguna automatización creada, así que toda prueba real cayó en automation_unresolved antes de llegar a aplicar cambios — la resolución de automation se valida primero, incluso antes que un trigger inválido:

{
  "success": false,
  "dry_run": true,
  "error": "automation_unresolved",
  "details": "el customer no tiene automatizaciones configuradas",
  "automation_intent": "Recordatorio 24h",
  "candidates": [],
  "hint": "Especifica la automatización (título plano o _id) entre candidates."
}

Según el manual, con una automatización real la respuesta trae _id (el de la automatización editada, que no cambia) y changes: exactamente los campos que se van a modificar, ya normalizados (igual que en update-client).

Errores propios

Consejos

• Si necesitas cambiar la plantilla, el destinatario o el filtro de productos, no hay atajo: recompón la automatización entera con create-automation.
• Antes de cambiar el trigger, comprueba con get-automation si la automatización ya tenía un offset: cambiar a un disparador que no admite offset (order:confirmed) lo deja sin efecto.