Meta CAPI — Conversions API

O módulo Meta CAPI (backend/src/marketing/meta-capi.service.ts) envia eventos de conversão ao Meta de forma server-side, complementando o Pixel do browser para cobrir sessões sem cookie ou com ad-blocker.

Visão Geral

Característica	Detalhe
Módulo backend	backend/src/marketing/
Service	MetaCapiService
Controller	MarketingController — backend/src/marketing/marketing.controller.ts
Schema de config	MarketingConfig — backend/src/marketing/schemas/marketing-config.schema.ts
Permissão	Role.Admin ou Role.Superadmin
Rota	GET/PUT /t/:slug/admin/marketing/capi-config

Eventos Implementados

Evento	Quando disparado
Purchase	Pedido marcado como pago / entregue
AddToCart	Heartbeat de carrinho com itens (opcional)
ViewContent	Visualização de item do cardápio (opcional)

Acionados via MetaCapiService.firePurchase() e MetaCapiService.sendEvent().

Schema MarketingConfig

Campo	Descrição
tenant	ObjectId — isolamento multi-tenant
pixelId	ID do Meta Pixel (ex: 1234567890)
accessTokenEncrypted	Token da CAPI criptografado com AES-256-GCM (via token-encrypt.ts) — nunca retornado pela API
enabled	true para habilitar envio real
dryRun	true para logar eventos sem enviar ao Meta (útil em homologação)

Configuração

1. Obter Pixel ID e Access Token

No Gerenciador de Eventos do Meta:

1. Selecione o Pixel existente (ou crie um novo)
2. Acesse Configurações → Conversions API
3. Gere um Token de Acesso (escopo: ads_management)
4. Anote o Pixel ID (número de 15 dígitos)

2. Configurar no PopinaFlow

PUT /t/:slug/admin/marketing/capi-config
{
  "pixelId": "1234567890",
  "accessToken": "EAABwz...",
  "enabled": true,
  "dryRun": false
}

Ou via painel: Configurações → Marketing → Meta CAPI.

O accessToken é criptografado antes de ser persistido. O endpoint GET /capi-config retorna hasAccessToken: true/false — nunca o token real.

3. Verificar com Dry Run

Ative dryRun: true para validar sem enviar ao Meta. Eventos aparecem nos logs do servidor:

[MetaCapiService] [DRY-RUN] Would send Purchase event: { event_id: "...", value: 45.90 }

Hashing de PII

Todos os dados pessoais são hasheados SHA-256 antes do envio (requisito Meta):

Campo	Normalização	Campo CAPI
Email	lowercase, trim	em[]
Telefone	E.164 sem +	ph[]
_fbp cookie	—	fbp
_fbc click ID	—	fbc

Nenhum dado em plaintext é enviado ao Meta.

Event Deduplication

Cada evento tem um event_id único (UUID ou orderNumber). O Meta usa esse campo para deduplicar entre o Pixel browser e o evento CAPI server-side — não conta a conversão duas vezes.

Endpoints

Método	Rota	Descrição
GET	/admin/marketing/capi-config	Retorna config atual (sem accessToken)
PUT	/admin/marketing/capi-config	Atualiza config

Relacionados

• Segurança PII
• CRM — Clientes
• LGPD — Conformidade