## Asset Header

- **Asset ID:** ARQ-MPX-CRM-BridgeSpec-v0.1
- **Version:** v00
- **Status:** Draft
- **Owner:** Victor Heredia
- **IntellBank:** IB-MPX-MasterPlaybooks
- **Tipo:** ARQ — Architecture
- **Propósito:** Puente MasterPlaybooks → CRM
- **Última actualización:** 2026-04-11

---

# Puente MasterPlaybooks → CRM
## Mini-Spec Técnica v0.1 — Para Juan Carlos
**EmpowerLabs / MasterPlaybooks**
Fecha: 24 marzo 2026

---

## Contexto

El AI Sherpa OS registra todo lo que pasa con un usuario en el Event Ledger. Tu trabajo, Juan Carlos, es construir el **puente** que hace que esos eventos lleguen al CRM en tiempo real — para que el equipo de ventas y onboarding sepa exactamente en qué estado está cada usuario y cuándo actuar.

El Sherpa detecta las señales. El CRM activa a las personas.

---

## Tu entregable

Un webhook bidireccional (o unidireccional en primera fase) entre:

```
MasterPlaybooks (plataforma) → Event Ledger (Supabase) → CRM
```

Coordina con Alex para usar el endpoint `POST /events` — él tiene el Event Ledger. Tú conectas los dos extremos: la plataforma MasterPlaybooks y el CRM.

---

## Mapa de disparadores

### PRIORIDAD 1 — Señales comerciales (acción inmediata del equipo)

| Evento en Sherpa | Qué pasó | Acción en CRM |
|-----------------|----------|---------------|
| `pricing_interest_detected` | Usuario preguntó por precio o costo | Crear tarea: "Contactar en las próximas 2 horas" + asignar a ejecutivo de ventas |
| `call_intent_detected` | Usuario pidió hablar con alguien | Crear tarea urgente: "Usuario quiere llamada — contactar hoy" |
| `urgency_detected` | Usuario expresó fecha límite o urgencia | Marcar lead como HOT + notificación inmediata al equipo |
| `upgrade_interest_detected` | Usuario preguntó por plan superior | Crear oportunidad de upsell en CRM |

### PRIORIDAD 2 — Señales de progreso (actualización de perfil)

| Evento en Sherpa | Qué pasó | Acción en CRM |
|-----------------|----------|---------------|
| `session_started` | Usuario entró al Sherpa | Actualizar `last_activity` en el contacto CRM |
| `user_goal_declared` | Usuario declaró su objetivo | Actualizar campo `goal` en el contacto |
| `module_completed` | Usuario completó un módulo | Actualizar `progress_score` + registrar nota |
| `milestone_reached` | Usuario alcanzó un hito importante | Registrar nota + considerar mensaje de felicitación |
| `session_ended` | Sesión cerrada | Actualizar `sessions_count` y `last_session_summary` |

### PRIORIDAD 3 — Señales de riesgo (intervención proactiva)

| Evento en Sherpa | Qué pasó | Acción en CRM |
|-----------------|----------|---------------|
| `engagement_drop_detected` | Señal de desenganche | Crear tarea: "Check-in proactivo con usuario" |
| `blocker_detected` | Usuario expresó un bloqueo | Registrar nota + crear tarea de seguimiento |
| Sin actividad 14 días | Inactividad prolongada (regla del State Engine) | Tarea de reactivación + enviar mensaje de WhatsApp |

---

## Estructura del webhook

### De MasterPlaybooks → Event Ledger

Cada acción del usuario en la plataforma MasterPlaybooks dispara un POST al Event Ledger:

```http
POST https://[supabase-project].supabase.co/functions/v1/capture-event

Headers:
  Authorization: Bearer [service_key]
  Content-Type: application/json

Body:
{
  "user_id": "uuid-del-usuario",
  "session_id": "uuid-de-la-sesion",
  "event_type": "module_completed",
  "event_category": "progress",
  "payload": {
    "module_id": "NOM035-001",
    "module_name": "Diagnóstico inicial",
    "completion_time_seconds": 1240
  },
  "playbook_id": "sherpa-nom035-v1"
}
```

**Obtener de Alex:** URL del proyecto Supabase + service key para el webhook.

### Del Event Ledger → CRM

Supabase puede disparar una función cuando se inserta un evento con categoría `commercial` o cuando el State Engine detecta un cambio en `risk_level`:

**Opción A (recomendada para v0.1):** Polling desde el CRM
- El CRM consulta `GET /state/{user_id}` cada X horas
- Si detecta cambio en `engagement_level` o `risk_level`, actualiza el perfil

**Opción B (más tiempo real):** Supabase Realtime
- Suscribirse a cambios en la tabla `events` con `event_category = 'commercial'`
- Cuando llega uno, disparar webhook al CRM

**Opción C (más simple para arrancar):** Edge Function con notificación directa
- Cuando `on-event-created` detecta `event_category = 'commercial'`, hace POST al webhook del CRM
- Implementar junto con Alex en la misma edge function

---

## Campos que necesitas en el CRM por contacto

Para que el puente sea útil, el perfil del contacto en CRM debe tener estos campos:

| Campo | Tipo | Fuente |
|-------|------|--------|
| `sherpa_user_id` | UUID | Enlace con el Event Ledger |
| `active_sherpa` | texto | Ej: "sherpa-nom035" |
| `progress_score` | número 0-100 | Del State Engine |
| `engagement_level` | texto (high/medium/low) | Del State Engine |
| `readiness_level` | texto | Del State Engine |
| `active_goal` | texto | Declarado por el usuario |
| `last_activity` | fecha | Último evento registrado |
| `sessions_count` | número | Total de sesiones |
| `commercial_signals` | lista | Señales detectadas |
| `last_session_summary` | texto | Resumen de última sesión |

---

## Definition of Done — Fase 1

- [ ] Webhook funcional: acción en MasterPlaybooks → POST /events en Supabase
- [ ] Al menos 3 event_types de progreso disparándose correctamente desde la plataforma
- [ ] Al menos 1 señal comercial (`pricing_interest_detected`) llegando al CRM como tarea
- [ ] Campos básicos del perfil CRM actualizándose con cada sesión
- [ ] Prueba end-to-end documentada: usuario completa módulo → CRM actualizado

---

## Preguntas que necesitas responder con Alex antes de arrancar

1. ¿Qué CRM están usando actualmente? ¿Tiene webhook de entrada?
2. ¿Los usuarios de MasterPlaybooks ya tienen UUID consistente o necesitamos crear el mapeo?
3. ¿Cuál es el primer Sherpa que va a producción? (Priorizar los eventos de ese Sherpa primero)
4. ¿La plataforma MasterPlaybooks puede disparar webhooks hoy o requiere desarrollo adicional?

---

## Coordinación con Alex

Alex tiene el Event Ledger. Tú tienes el puente. Puntos de coordinación:

- **Alex te da:** URL de Supabase + service key + documentación de POST /events
- **Tú le das a Alex:** webhook URL del CRM para las señales comerciales (para que las envíe desde la edge function)
- **Checkpoint:** al final de Semana 1, prueba conjunta del flujo completo

---

*Mini-spec: MP-CRM-Bridge-Spec-v0.1.md | Para: Juan Carlos | EmpowerLabs | 24 marzo 2026*