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.

0.1 La cadena del funnel: Leads → Oportunidades

Los leads no se cargan como clientes directo: cada lead capturado entra al tablero Oportunidades en etapa Afluencia y la oportunidad avanza sola conforme avanza el proceso. La vinculación lead ↔ oportunidad vive en la tabla LeadOportunidad de la base local (una oportunidad por lead; idempotente).

Transición	Evento que la dispara
→ Afluencia	POST /api/leads (captura) o webhook create_pulse en Leads (alta directa en la UI de Monday): crea la oportunidad con nombre, teléfono, email y Desarrollo del lead
→ Agendo Cita	POST /api/leads/:id/estado con estado AGENDA CITA
→ Cotizador	POST /api/cotizaciones con un teléfono que ya tiene lead mapeado: actualiza la misma oportunidad (Unidad, Tipo propuesta, precios, Fecha cotización) en vez de crear una segunda
→ Aparto	POST /api/clientes con leadMondayId en el payload (app alta-clientes). Se escribe el dedup apartado-creado:<opId> antes del cambio de etapa para que el webhook/cron no duplique el Apartado
→ Ganado	Manual en Monday (o flujo Enkontrol): el escaneo crea el item en Ventas
→ Perdido	POST /api/leads/:id/descartar: mueve la oportunidad y, si el motivo es label del dropdown Motivo No Compra, lo setea también

Reglas de resiliencia: un fallo de Monday en cualquiera de estas transiciones solo se loguea — la acción principal (crear el lead, la cotización o el alta) nunca se rompe por el funnel.

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.

5. Tablero Unidades — recordatorio de vencimiento de autorización de crédito

La columna Venc. autorización (date) del board Unidades la llena sync-obra-estatus.py cuando el desarrollo exista en el board (hoy solo la fuente MUTUO la trae, y MUTUO aún no está en Unidades). La receta queda lista para cuando la columna tenga datos.

• Board: Unidades
• Receta: "When a date arrives, notify someone" (categoría Date reminders; en español: "Cuando llegue una fecha, notificar a alguien")
• Parámetros:
  • date column: Venc. autorización
  • when: 7 días antes, a las 9:00
  • notify: el coordinador de ventas (elegir la persona en la receta)
  • mensaje: La autorización de crédito de {item.name} vence en 7 días

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.