v2026.2.6

Fecha de lanzamiento: 13 de Febrero de 2026

---

✨ Nuevas Funcionalidades

🎯 API de Conversiones de Facebook - Rastreo Automático

Implementación completa de Facebook Conversions API (CAPI) para rastreo server-side de conversiones, permitiendo que cada cambio de etapa en el CRM dispare automáticamente eventos de conversión a Facebook.

¿Para qué sirve?

• Rastreo Preciso: Eventos enviados directamente desde el servidor a Facebook, más confiables que píxeles browser-side
• Optimización de Anuncios: Facebook recibe datos de conversión en tiempo real y optimiza campañas automáticamente
• Atribución Perfecta: El sistema identifica automáticamente de qué anuncio vino el cliente a través de datos de rastreo
• Alta Tasa de Coincidencia: Envía email, teléfono, nombre, IP y Click ID cifrados para mejor coincidencia con usuarios de Facebook

¿Cómo usar?

1. Configure su Campaña UTM:

   • Acceda a Menú UTM → Campañas
   • Cree una nueva campaña
   • IMPORTANTE: Ingrese el ID de Campaña de Facebook (ej: 120233174044090606)
   • Configure el Píxel de Facebook (ID + Token de Acceso)

2. Configure Eventos en las Etapas del CRM:

   • Acceda a CRM → Administrar Etapas
   • En cada etapa importante (Lead Calificado, Compró, etc.)
   • Active "Evento de Conversión"
   • Seleccione la plataforma: Facebook
   • Elija el tipo de evento apropiado
   • Configure valor y moneda (o deje usar el sale_price del cliente)

3. Rastreo Automático:

   • Cliente hace clic en anuncio "Click to WhatsApp" de Facebook
   • WhatsApp envía datos de rastreo en el primer mensaje
   • Sistema identifica automáticamente la campaña por ID
   • Cliente se vincula a la campaña
   • ¡Al cambiar de etapa → evento enviado a Facebook!

Eventos Soportados

19 eventos estándar de Facebook Conversions API:

Categoría	Eventos
Compra	Purchase, InitiateCheckout, AddToCart, AddToWishlist, AddPaymentInfo
Lead	Lead, CompleteRegistration, Contact
Interés	ViewContent, Search
Agendamiento	Schedule, StartTrial
Acción	Subscribe, SubmitApplication, CustomizeProduct
Especiales	Donate, FindLocation, PageView, Other

Datos Enviados Automáticamente

Datos del Cliente (cifrado SHA256):

• ✉️ Email
• 📱 WhatsApp/Teléfono
• 👤 Nombre (primero y último)
• 🆔 ID del Cliente

Datos del Evento:

• 🎯 Tipo de Evento (Purchase, Lead, etc.)
• 💰 Valor de Conversión
• 💵 Moneda (BRL, USD, etc.)
• 📝 Nombre de la Etapa
• 📂 Categoría del Embudo

Datos del Anuncio (rastreo):

• 🔗 Click ID (fbclid/ctwa_clid)
• 🆔 ID del Anuncio
• 📢 ID de la Campaña
• 📰 Título y Texto del Anuncio
• 🌐 URL de Origen

Datos Técnicos:

• 🌍 IP del Cliente
• 🖥️ User Agent (navegador/dispositivo)
• ⏰ Timestamp Preciso

Identificación Automática de Origen

Cómo el sistema identifica de dónde vino el cliente:

1. Cliente hace clic en anuncio "Click to WhatsApp"
   ↓
2. WhatsApp agrega datos INVISIBLES al primer mensaje:
   - sourceID: ID de Campaña de Facebook
   - ctwaClid: ID único del clic
   - adTitle, adBody, thumbnailURL
   - messageTimestamp
   ↓
3. Cliente envía mensaje (ej: "Hola, quiero saber más")
   ↓
4. Sistema recibe mensaje + datos invisibles
   ↓
5. Sistema busca: "Campaña con sourceID = 120233..."
   ↓
6. ¡Cliente vinculado automáticamente a la campaña!

Importante: ¡Los datos de rastreo vienen solo en el primer mensaje!

Alertas en el Chat

El sistema guarda alertas automáticas en el chat cuando:

• ❌ Cliente no tiene campaña UTM asociada
• ❌ Píxel no configurado o inactivo
• ❌ Token de acceso inválido
• ❌ Error en la API de Facebook (con detalles completos del error)

Action Source: physical_store

Utiliza action_source: 'physical_store' (eventos offline) que:

• ✅ Funciona con Píxel existente (no necesita crear Dataset)
• ✅ Soporta TODOS los 19 eventos estándar
• ✅ Permite incluir todos los campos de rastreo
• ✅ Listo para producción sin configuración adicional

---

🔧 Mejoras Técnicas

Arquitectura de Conversión

• Service Layer: conversion-events-service.js con soporte multi-plataforma
• Event Dispatching: Sistema modular para Facebook, Google Ads y TikTok
• Error Handling: Manejo robusto con logs estructurados y Sentry
• Deduplicación: Event ID único basado en hash SHA256
• Match Quality: Cálculo estimado de Event Match Quality Score
• Encryption: Datos sensibles cifrados con AES-256
• Hashing: PII hasheado con SHA256 conforme GDPR

Frontend

• StageModal.tsx: Interfaz completa para configurar múltiples eventos
• Soporte Multi-Evento: Array de eventos (Facebook, Google, TikTok simultáneamente)
• UI/UX Intuitiva: Formulario con validación y hints informativos
• Traducciones: Soporte completo en PT, EN y ES para todos los 19 eventos

Backend

• Customer Stage Service: Integración automática al cambiar etapa
• UTM Tracking: Búsqueda automática de contactos en customer_contacts
• Fallback Logic: Prioridad inteligente (cliente → etapa → predeterminado)
• Webhook Integration: Extracción automática de datos de WhatsApp
• Campaign Matching: Vinculación por sourceID del metadata

Base de Datos

• Migration: Conversión de utm_event de objeto a array (soporte multi-evento)
• JSONB: Estructura flexible para metadata UTM y configuración de eventos
• Backward Compatibility: Migración automática de datos existentes

---

📚 Documentación

GUIA_CONVERSOES.md (Nuevo)

Guía completa para usuarios finales con:

• ✅ Paso a paso de configuración
• ✅ Explicación de todos los 19 eventos disponibles
• ✅ Tablas de casos de uso para cada evento
• ✅ Flujo visual completo de rastreo
• ✅ Explicación detallada de datos invisibles
• ✅ Cómo el sistema identifica origen (sourceID, ctwaClid)
• ✅ Troubleshooting y FAQ extenso
• ✅ Ejemplo práctico completo (e-commerce)
• ✅ Buenas prácticas y checklist
• ✅ Resumen ejecutivo de puntos principales

CONVERSION_EVENTS.md (Actualizado)

Documentación técnica completa:

• 📊 Arquitectura del sistema
• 🔌 Integración con Facebook CAPI
• 📈 Event Match Quality y optimización
• 🔐 Seguridad y cifrado
• 🚨 Sistema de alertas en el chat
• ⚙️ Configuración de campañas y píxeles
• 🧪 Ejemplos de payload y pruebas

---

🎯 Beneficios

• ✅ Rastreo 100% Automático: Cliente vinculado automáticamente al hacer clic en anuncio
• ✅ Cero Configuración Manual: No necesita marcar manualmente de dónde vino
• ✅ Datos Precisos: sourceID garantiza identificación correcta de campaña
• ✅ Click ID Único: ctwa_clid permite rastreo preciso de cada clic
• ✅ Optimización Automática: Facebook optimiza anuncios basándose en conversiones reales
• ✅ ROI Medible: Vea exactamente qué anuncios generan ventas
• ✅ Alta Tasa de Coincidencia: Múltiples campos de identificación (email, phone, Click ID)
• ✅ Transparencia Total: Alertas en chat muestran cualquier error
• ✅ Multi-Evento: Configure diferentes eventos para cada etapa
• ✅ Escalable: Soporte futuro para Google Ads y TikTok

---

🔄 Migration

-- Migración automática de utm_event de objeto a array
-- Soporta configuración de múltiples eventos simultáneamente

Archivo: 20260212100000_migrate_utm_event_to_array.sql

---

🚀 Cómo Empezar

1. Lea la guía: Acceda a docs/GUIA_CONVERSOES.md
2. Configure su primera campaña: Menú UTM → Campañas
3. Agregue el ID de Campaña de Facebook: Ej: 120233174044090606
4. Configure el Píxel: ID + Token de Acceso
5. Configure eventos en etapas: CRM → Administrar Etapas
6. Pruebe: Mueva un cliente que vino de anuncio a otra etapa
7. Verifique: Administrador de Eventos de Facebook

---

⚠️ Importante

• 🎯 ID de Campaña es obligatorio: Sin él, el sistema no vincula automáticamente
• 📱 Solo Click to WhatsApp Ads: Anuncios normales no envían datos de rastreo
• 💬 Primer mensaje es crucial: Datos vienen solo en el primer mensaje del cliente
• 🔑 Token válido: Verifique que el Token de Acceso de Facebook esté activo
• ✅ Probado en Producción: Sistema funcionando con action_source: physical_store

---

Tiempo estimado de configuración: 10-15 minutos
Impacto: Alto - Reducción de costos de anuncio y aumento de conversiones
Prioridad: 🔥 Esencial para quienes usan Facebook Ads