v2026.2.6

Data de lançamento: 13 de Fevereiro de 2026

✨ Novas Funcionalidades

🎯 API de Conversões do Facebook - Rastreamento Automático

Implementação completa da Facebook Conversions API (CAPI) para rastreamento server-side de conversões, permitindo que cada mudança de estágio no CRM dispare automaticamente eventos de conversão para o Facebook.

Para que serve?

Rastreamento Preciso: Eventos enviados diretamente do servidor para o Facebook, mais confiáveis que pixels browser-side
Otimização de Anúncios: Facebook recebe dados de conversão em tempo real e otimiza campanhas automaticamente
Atribuição Perfeita: Sistema identifica automaticamente de qual anúncio o cliente veio através dos dados de rastreamento
Match Rate Alto: Envia email, telefone, nome, IP e Click ID criptografados para melhor correspondência com usuários do Facebook

Como usar?

Configure sua Campanha UTM:
- Acesse Menu UTM → Campanhas
- Crie uma nova campanha
- IMPORTANTE: Insira o ID da Campanha do Facebook (ex: 120233174044090606)
- Configure o Pixel do Facebook (ID + Token de Acesso)
Configure Eventos nos Estágios do CRM:
- Acesse CRM → Gerenciar Estágios
- Em cada estágio importante (Lead Qualificado, Comprou, etc.)
- Ative "Evento de Conversão"
- Selecione a plataforma: Facebook
- Escolha o tipo de evento apropriado
- Configure valor e moeda (ou deixe usar o sale_price do cliente)
Rastreamento Automático:
- Cliente clica em anúncio "Click to WhatsApp" do Facebook
- WhatsApp envia dados de rastreamento na primeira mensagem
- Sistema identifica automaticamente a campanha pelo ID
- Cliente é vinculado à campanha
- Ao mudar de estágio → evento disparado ao Facebook!

Eventos Suportados

19 eventos padrão do Facebook Conversions API:

Categoria	Eventos
Compra	Purchase, InitiateCheckout, AddToCart, AddToWishlist, AddPaymentInfo
Lead	Lead, CompleteRegistration, Contact
Interesse	ViewContent, Search
Agendamento	Schedule, StartTrial
Ação	Subscribe, SubmitApplication, CustomizeProduct
Especiais	Donate, FindLocation, PageView, Other

Dados Enviados Automaticamente

Dados do Cliente (criptografados SHA256):

✉️ Email
📱 WhatsApp/Telefone
👤 Nome (primeiro e último)
🆔 ID do Cliente

Dados do Evento:

🎯 Tipo de Evento (Purchase, Lead, etc.)
💰 Valor da Conversão
💵 Moeda (BRL, USD, etc.)
📝 Nome do Estágio
📂 Categoria do Funil

Dados do Anúncio (rastreamento):

🔗 Click ID (fbclid/ctwa_clid)
🆔 ID do Anúncio
📢 ID da Campanha
📰 Título e Texto do Anúncio
🌐 URL de Origem

Dados Técnicos:

🌍 IP do Cliente
🖥️ User Agent (navegador/dispositivo)
⏰ Timestamp preciso

Identificação Automática de Origem

Como o sistema identifica de onde veio o cliente:

1. Cliente clica no anúncio "Click to WhatsApp"
   ↓
2. WhatsApp adiciona dados INVISÍVEIS à primeira mensagem:
   - sourceID: ID da Campanha do Facebook
   - ctwaClid: ID único do click
   - adTitle, adBody, thumbnailURL
   - messageTimestamp
   ↓
3. Cliente envia mensagem (ex: "Olá, quero saber mais")
   ↓
4. Sistema recebe mensagem + dados invisíveis
   ↓
5. Sistema busca: "Campanha com sourceID = 120233..."
   ↓
6. Cliente automaticamente vinculado à campanha!

Importante: Os dados de rastreamento vêm apenas na primeira mensagem!

Alertas no Chat

Sistema salva alertas automáticos no chat quando:

❌ Cliente não tem campanha UTM associada
❌ Pixel não configurado ou inativo
❌ Token de acesso inválido
❌ Erro na API do Facebook (com detalhes completos do erro)

Action Source: physical_store

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

✅ Funciona com Pixel existente (não precisa criar Dataset)
✅ Suporta TODOS os 19 eventos padrão
✅ Permite incluir todos os campos de rastreamento
✅ Pronto para produção sem configuração adicional

🔧 Melhorias Técnicas

Arquitetura de Conversão

Service Layer: conversion-events-service.js com suporte multi-plataforma
Event Dispatching: Sistema modular para Facebook, Google Ads e TikTok
Error Handling: Tratamento robusto com logs estruturados e Sentry
Deduplicação: Event ID único baseado em hash SHA256
Match Quality: Cálculo estimado de Event Match Quality Score
Encryption: Dados sensíveis criptografados com AES-256
Hashing: PII hasheado com SHA256 conforme GDPR

Frontend

StageModal.tsx: Interface completa para configurar múltiplos eventos
Suporte Multi-Evento: Array de eventos (Facebook, Google, TikTok simultaneamente)
UI/UX Intuitivo: Formulário com validação e hints informativos
Traduções: Suporte completo em PT, EN e ES para todos os 19 eventos

Backend

Customer Stage Service: Integração automática ao mudar estágio
UTM Tracking: Busca automática de contatos em customer_contacts
Fallback Logic: Prioridade inteligente (cliente → estágio → default)
Webhook Integration: Extração automática de dados do WhatsApp
Campaign Matching: Vinculação por sourceID do metadata

Database

Migration: Conversão de utm_event de objeto para array (suporte multi-evento)
JSONB: Estrutura flexível para metadata UTM e configuração de eventos
Backward Compatibility: Migração automática de dados existentes

📚 Documentação

GUIA_CONVERSOES.md (Novo)

Guia completo para usuários finais com:

✅ Passo a passo de configuração
✅ Explicação de todos os 19 eventos disponíveis
✅ Tabelas de casos de uso para cada evento
✅ Fluxo visual completo de rastreamento
✅ Explicação detalhada dos dados invisíveis
✅ Como o sistema identifica origem (sourceID, ctwaClid)
✅ Troubleshooting e FAQ extenso
✅ Exemplo prático completo (e-commerce)
✅ Boas práticas e checklist
✅ Resumo executivo dos pontos principais

CONVERSION_EVENTS.md (Atualizado)

Documentação técnica completa:

📊 Arquitetura do sistema
🔌 Integração com Facebook CAPI
📈 Event Match Quality e otimização
🔐 Segurança e criptografia
🚨 Sistema de alertas no chat
⚙️ Configuração de campanhas e pixels
🧪 Exemplos de payload e testes

🎯 Benefícios

✅ Rastreamento 100% Automático: Cliente vinculado automaticamente ao clicar no anúncio
✅ Zero Configuração Manual: Não precisa marcar manualmente de onde veio
✅ Dados Precisos: sourceID garante identificação correta da campanha
✅ Click ID Único: ctwa_clid permite rastreamento preciso de cada click
✅ Otimização Automática: Facebook otimiza anúncios com base em conversões reais
✅ ROI Mensurável: Veja exatamente quais anúncios geram vendas
✅ Match Rate Alto: Múltiplos campos de identificação (email, phone, Click ID)
✅ Transparência Total: Alertas no chat mostram qualquer erro
✅ Multi-Evento: Configure diferentes eventos para cada estágio
✅ Escalável: Suporte futuro para Google Ads e TikTok

🔄 Migration

sql

-- Migração automática de utm_event de objeto para array
-- Suporta configuração de múltiplos eventos simultaneamente

Arquivo: 20260212100000_migrate_utm_event_to_array.sql

🚀 Como Começar

Leia o guia: Acesse docs/GUIA_CONVERSOES.md
Configure sua primeira campanha: Menu UTM → Campanhas
Adicione o ID da Campanha do Facebook: Ex: 120233174044090606
Configure o Pixel: ID + Token de Acesso
Configure eventos nos estágios: CRM → Gerenciar Estágios
Teste: Mova um cliente que veio de anúncio para outro estágio
Verifique: Gerenciador de Eventos do Facebook

⚠️ Importante

🎯 ID da Campanha é obrigatório: Sem ele, o sistema não vincula automaticamente
📱 Apenas Click to WhatsApp Ads: Anúncios normais não enviam dados de rastreamento
💬 Primeira mensagem é crucial: Dados vêm apenas na primeira mensagem do cliente
🔑 Token válido: Verifique se o Token de Acesso do Facebook está ativo
✅ Testado em Produção: Sistema funcionando com action_source: physical_store

Tempo estimado de configuração: 10-15 minutos
Impacto: Alto - Redução de custos de anúncio e aumento de conversões
Prioridade: 🔥 Essencial para quem usa Facebook Ads

v2026.2.6 ​

✨ Novas Funcionalidades ​

🎯 API de Conversões do Facebook - Rastreamento Automático ​

Para que serve? ​

Como usar? ​

Eventos Suportados ​

Dados Enviados Automaticamente ​

Identificação Automática de Origem ​

Alertas no Chat ​

Action Source: physical_store ​

🔧 Melhorias Técnicas ​

Arquitetura de Conversão ​

Frontend ​

Backend ​

Database ​

📚 Documentação ​

GUIA_CONVERSOES.md (Novo) ​

CONVERSION_EVENTS.md (Atualizado) ​

🎯 Benefícios ​

🔄 Migration ​

🚀 Como Começar ​

⚠️ Importante ​