# 🏆 Ventajas Competitivas y Guía de Integración Técnica: Meta CAPI y Google Data Manager API en VEIA CRM

Este documento detalla las ventajas estratégicas y las directrices técnicas para que el equipo de desarrollo de **VEIA** integre las conversiones de servidor a servidor (S2S) de **Meta Conversions API (CAPI)** y la nueva **Google Data Manager API** (vigente a partir de Junio 2026).

---

## 🔵 1. Meta Conversions API (CAPI)

### Requisitos de Permisos en Meta Business Manager:
Para realizar llamadas a la API de Conversiones, el equipo de desarrollo necesitará:
1.  **Pixel ID**: Generado en el Administrador de Eventos de Meta.
2.  **Long-Lived Access Token (Token de Acceso de Sistema)**: Generado en Meta Business Suite ➔ Configuración del Negocio ➔ Usuarios del Sistema. Este token tiene permisos de servidor perpetuos.
3.  **Permisos de API de Marketing**: Configurar la aplicación de Meta en estado de producción (Full Access) completando el umbral reducido de 500 llamadas en 15 días.

### Código de Conexión en Node.js (Fetch API):
El backend realiza una petición POST directa a los servidores de Meta. Los datos confidenciales (como email y teléfono) **deben ser hasheados en SHA-256** antes del envío para cumplir con las normas de privacidad de datos personales de Meta.

```javascript
const crypto = require('crypto');

/**
 * Hashea datos confidenciales con SHA-256
 */
function sha256Hash(data) {
    if (!data) return null;
    return crypto
        .createHash('sha256')
        .update(data.trim().toLowerCase())
        .digest('hex');
}

/**
 * Envía un evento de conversión calificada a Meta CAPI
 */
async function sendMetaConversionEvent(contact, eventName = 'Lead') {
    const pixelId = process.env.META_PIXEL_ID;
    const accessToken = process.env.META_ACCESS_TOKEN;
    
    if (!pixelId || !accessToken) {
        console.warn('[META-CAPI] Faltan credenciales META_PIXEL_ID o META_ACCESS_TOKEN en el .env');
        return;
    }

    const url = `https://graph.facebook.com/v25.0/${pixelId}/events`;
    
    const payload = {
        data: [
            {
                event_name: eventName,
                event_time: Math.floor(Date.now() / 1000),
                action_source: 'chat',
                event_source_url: 'https://veiaeducar.com',
                user_data: {
                    em: contact.email ? [sha256Hash(contact.email)] : [],
                    ph: contact.phone ? [sha256Hash(contact.phone)] : [],
                    fb_login_id: contact.campaign_id || null, 
                },
                custom_data: {
                    lead_category: contact.lead_category || 'frio',
                    interested_product: contact.interested_product || 'General'
                },
                event_id: `veia_evt_${contact.id}` // Para deduplicación con el Pixel del navegador
            }
        ]
    };

    try {
        const response = await fetch(url, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(payload)
        });

        const result = await response.json();
        console.log('[META-CAPI] Respuesta de Meta:', result);
    } catch (err) {
        console.error('[META-CAPI] Error:', err.message);
    }
}
```

---

## 🟢 2. Google Data Manager API (Vigencia Junio 2026)

### Requisitos y Flujo en Google Ads:
A partir del **15 de Junio de 2026**, la API clásica de Google Ads ya no acepta el método legacy `UploadClickConversions` para nuevas implementaciones. Los desarrolladores deben usar la **Data Manager API**.
1.  **OAuth 2.0 Client Credentials**: Credenciales de Google Cloud Platform (GCP) habilitadas con acceso a Google Ads.
2.  **Data Manager Source Link**: Configurar un "Source Link" (origen de datos) de tipo API desde el panel de Google Ads Data Manager.
3.  **Google Click ID (GCLID)**: Asegurar que la landing de VEIA capture el parámetro `gclid` de las URLs de Google Ads y lo pase al CRM.

### Código de Conexión en Node.js:
El CRM envía las conversiones offline llamando al endpoint del Source Link de Data Manager:

```javascript
/**
 * Envía un evento de conversión a Google Data Manager API
 */
async function sendGoogleConversionEvent(contact, googleAccessToken) {
    const dataManagerEndpoint = process.env.GOOGLE_DATA_MANAGER_ENDPOINT; 
    
    if (!dataManagerEndpoint || !googleAccessToken) {
        console.warn('[GOOGLE-DATA-MANAGER] Faltan credenciales de Google en el .env');
        return;
    }

    const payload = {
        events: [
            {
                event_type: 'CONVERSION',
                event_time: new Date().toISOString(),
                gclid: contact.campaign_id || null, // Google Click ID
                user_identifier: {
                    hashed_email: contact.email ? sha256Hash(contact.email) : null,
                    hashed_phone_number: contact.phone ? sha256Hash(contact.phone) : null
                },
                conversion_details: {
                    conversion_name: 'Lead Calificado',
                    value: contact.lead_category === 'caliente' ? 250000 : 0,
                    currency_code: 'ARS'
                }
            }
        ]
    };

    try {
        const response = await fetch(dataManagerEndpoint, {
            method: 'POST',
            headers: {
                'Authorization': `Bearer ${googleAccessToken}`,
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(payload)
        });

        const result = await response.json();
        console.log('[GOOGLE-DATA-MANAGER] Respuesta de Google:', result);
    } catch (err) {
        console.error('[GOOGLE-DATA-MANAGER] Error:', err.message);
    }
}
```

---

## 💎 Ventajas de la Medición Server-to-Server (S2S)

1.  **Deduplicación e Inmunidad a Adblockers**: La comunicación de servidor a servidor no pasa por el navegador, por lo que bloqueadores de publicidad (como uBlock, Brave o Safari ITP) no pueden frenarla. Capturamos el 100% de la atribución publicitaria.
2.  **Optimización Automática del Algoritmo (Conversion Leads)**: Al notificar a Meta y Google cuando un usuario es calificado como "Tibio" o "Caliente" por el bot, la IA de Ads reajusta sus impresiones para mostrar anuncios exclusivamente a personas de alto valor.
3.  **Seguridad de Token**: La API Key de Meta y Google se mantiene oculta de forma 100% segura en las variables de entorno de nuestro servidor, protegiendo las credenciales contra filtraciones.