FRASA-CAS/docs/AUTOMATIZACIONES-MONDAY.md

Automatizaciones nativas de Monday — checklist del admin

Recetas que se activan desde la UI de Monday (botón "Automatizar" en cada tablero). Tiempo estimado total: ~10 minutos. Ninguna requiere código.

No duplicar: el servidor (API Gateway) ya cubre la asignación round-robin de vendedores, el recordatorio de leads inactivos (10 días), el escalado de leads sin contactar (48 h), y la creación de items en Apartado / Ventas cuando una oportunidad entra a Aparto o Ganado. Las recetas de abajo son solo avisos y orden visual; no repitas esas reglas como recetas nativas.

0. Cómo llegan los eventos al servidor (webhooks + crons)

Desde que el stack tiene dominio público (Cloudflare Tunnel), Monday avisa al servidor en tiempo real vía webhooks registrados en https://frasa.consultoria-as.com/api/webhooks/monday:

Board	Evento registrado	Reacción del servidor
Leads	create_item	Round-robin: asigna Vendedor al lead nuevo
Oportunidades	change_column_value	Si la etapa es Aparto → crea item en Apartado; si es Ganado → crea item en Ventas

Los crons cada 5 min (POLL_CRON) siguen activos como red de seguridad: repiten los mismos escaneos (idempotentes, con dedup en la base) por si un evento se pierde. El escaneo de inactividad (9:00) y los recordatorios de cobranza (9:30) solo corren por cron.

Notas técnicas (quirks de Monday, ya contemplados en el código):

• El webhook se registra como create_item pero el payload real llega como create_pulse, y el id viene en pulseId (no itemId).
• Los cambios de columna llegan como update_column_value.
• El evento change_status_column_value no dispara en estos boards; por eso se registró change_column_value.
• Monday no firma sus webhooks: el servidor usa el evento solo como disparador y re-consulta el tablero por API antes de escribir nada.

Para re-registrar un webhook (p. ej. si cambia el dominio):

mutation {
  create_webhook(board_id: <BOARD_ID>,
    url: "https://frasa.consultoria-as.com/api/webhooks/monday",
    event: create_item) { id }
}

1. Tablero Leads — avisar al vendedor cuando se le asigna un lead

El round-robin del servidor asigna la columna Vendedor; esta receta solo envía la notificación.

• Board: Leads
• Receta: "When a person is assigned to someone, notify someone" (categoría People; en español: "Cuando se asigne una persona, notificar a alguien")
• Parámetros:
  • person column: Vendedor
  • notify: the person assigned (el vendedor asignado)
  • mensaje: Tienes un lead nuevo: {item.name}

2. Tablero Oportunidades — avisar cuando algo se gana

El servidor ya crea el item en Ventas; esto solo avisa al equipo.

• Board: Oportunidades
• Receta: "When status changes to something, notify someone" (categoría Status)
• Parámetros:
  • status column: Estado → valor: Ganado
  • notify: una persona o equipo de coordinación (elegir en la receta)
  • mensaje: Venta ganada: {item.name} — {item.text_mm6ezd0d} (unidad)

3. Tablero Apartado — recordatorio de fecha límite

• Board: Apartado
• Receta: "When a date arrives, notify someone" (categoría Date reminders)
• Parámetros:
  • date column: Fecha límite
  • when: 1 día antes, a las 9:00
  • notify: el responsable del expediente (o coordinación)
  • mensaje: El apartado de {item.name} vence mañana

4. Mover items entre grupos por estado (orden visual)

Si los tableros tienen grupos (p. ej. "Activos" / "Cerrados"), una receta por tablero mantiene el orden sin trabajo manual:

• Board: Oportunidades (repetir en Leads si usa grupos)
• Receta: "When status changes to something, move item to group" (categoría Status)
• Parámetros sugeridos:
  • Estado = Ganado → mover al grupo Cerrados
  • Estado = Perdido → mover al grupo Cerrados
  • Estado = Abandono → mover al grupo Cerrados

Si el tablero no tiene grupos, omite esta receta: no afecta nada del servidor.

Verificación rápida (2 min)

1. Crea un item de prueba en Leads, asígnate como Vendedor → debe llegarte la notificación de la receta 1. Bórralo después.
2. En Oportunidades, cambia un item de prueba a Ganado → notificación de la receta 2 y (en segundos, vía webhook; ≤ 5 min por el cron de respaldo) un item nuevo en Ventas. Borra ambos después.