cdp-edge 1.2.2 → 1.4.0

package/extracted-skill/tracking-events-generator/agents/utm-agent.md

@@ -0,0 +1,322 @@
+# UTM Agent — CDP Edge
+
+**Papel:** Gerador automático de UTMs completas — usa o contexto já coletado pelo CDP Edge para produzir cada string de UTM pronta, por plataforma e por formato de anúncio. O cliente copia e cola.
+
+---
+
+## Princípio Fundamental
+
+O CDP Edge já sabe tudo que precisa para gerar as UTMs. Nenhuma informação adicional do cliente é necessária além do que já foi coletado nas fases anteriores:
+
+| O que o CDP Edge já sabe | De onde vem |
+|---|---|
+| Quais plataformas serão usadas | FASE 0-B (seleção de plataformas) |
+| Se tem vídeo no funil | Page Analyzer (detecta VSL, videos, players) |
+| Se tem quiz | Lead Scoring Agent (configurado na FASE 6) |
+| Se tem formulário / landing page | Page Analyzer (detecta forms, CTAs) |
+| Se tem Click-to-WhatsApp | Meta selecionado + CTWA habilitado automaticamente |
+| Nicho e categoria do produto | Page Analyzer |
+| Faixa de valor do produto | Pergunta feita pelo próprio UTM Agent na FASE 2-B |
+
+**Com tudo isso, o UTM Agent gera uma tabela completa de UTMs prontas — o cliente não precisa inventar nenhum parâmetro.**
+
+---
+
+## O Que São as 5 Dimensões
+
+```
+utm_source   → PLATAFORMA    — de qual rede de anúncio veio o lead
+utm_medium   → FORMATO       — qual tipo de anúncio foi usado
+utm_campaign → PRODUTO/FAIXA — qual produto e faixa de valor (obfuscado)
+utm_content  → ORIGEM        — qual criativo/página/funil gerou o lead
+utm_term     → QUALIFICAÇÃO  — classificação do quiz (preenchida pelo Worker)
+```
+
+`utm_term` é o único campo que o cliente **nunca** configura nos anúncios — o Worker injeta automaticamente após o Quiz Scoring Engine classificar o lead.
+
+---
+
+## Quando Este Agente Roda
+
+Após o **Lead Scoring Agent** (se quiz habilitado) e antes do **Browser Tracking Agent**.
+
+Inputs que o agente já possui ao ser chamado:
+- `SELECTED_PLATFORMS` — plataformas selecionadas na FASE 0-B
+- `page_analysis` — saída do Page Analyzer (tem video? tem quiz? tem form? tem CTWA?)
+- `lead_scoring_config` — quiz configurado? quais perguntas? qual nome do quiz?
+- `utm_value_range` — faixa de valor do produto (perguntada na FASE 2-B)
+- `product_category` — nicho detectado pelo Page Analyzer
+
+---
+
+## Processo de Geração
+
+### PASSO 1 — Mapear o que foi implementado no funil
+
+O agente lê os outputs das fases anteriores e monta um inventário de origens:
+
+```
+INVENTÁRIO DE ORIGENS (montado automaticamente):
+
+Plataformas ativas:     [facebook, google, tiktok]
+Formatos por plataforma:
+  facebook → [reels, stories, video, cpc, ctwa]  ← detectado: tem VSL + tem CTWA
+  google   → [cpc]                                ← search only
+  tiktok   → [video]                              ← video in-feed
+Tipos de página:
+  → quiz habilitado    → utm_content inclui quiz_{nome_quiz}
+  → landing com VSL   → utm_content inclui video_{tipo}
+  → formulário direto → utm_content inclui landing_principal
+  → CTWA ativo        → utm_content inclui ctwa_direto
+```
+
+### PASSO 2 — Gerar o valor obfuscado da campanha
+
+Com a faixa de valor informada (ex: "700k-1M"):
+```
+SHA256("700k-1M" + "CDP_EDGE_UTM_SALT") → primeiros 8 chars → "8a3f1d2b"
+utm_campaign = imovel_8a3f1d2b
+```
+
+Registrar no `utm-mapping.json` para de-obfuscação no Worker.
+
+### PASSO 3 — Gerar a tabela completa de UTMs prontas
+
+Para CADA combinação de plataforma × formato × origem que existe no funil:
+
+---
+
+## Saída — Tabela de UTMs Prontas para o Cliente
+
+O agente entrega uma tabela assim, gerada automaticamente com base no que foi implementado:
+
+```markdown
+# UTMs do Projeto [NOME DO CLIENTE]
+# Geradas pelo CDP Edge — copie e cole em cada campanha
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+## META ADS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+### Campanhas que levam ao QUIZ DE QUALIFICAÇÃO
+Use quando o anúncio leva para a página do quiz antes do formulário.
+
+Reels:
+utm_source=facebook&utm_medium=reels&utm_campaign=imovel_8a3f1d2b&utm_content=quiz_diagnostico_imovel
+
+Stories:
+utm_source=facebook&utm_medium=stories&utm_campaign=imovel_8a3f1d2b&utm_content=quiz_diagnostico_imovel
+
+Vídeo in-feed:
+utm_source=facebook&utm_medium=video&utm_campaign=imovel_8a3f1d2b&utm_content=quiz_diagnostico_imovel
+
+Feed (imagem/carrossel):
+utm_source=facebook&utm_medium=cpc&utm_campaign=imovel_8a3f1d2b&utm_content=quiz_diagnostico_imovel
+
+### Campanhas que levam ao VÍDEO DE VENDAS (VSL)
+Use quando o anúncio leva direto para a landing page com vídeo.
+
+Reels:
+utm_source=facebook&utm_medium=reels&utm_campaign=imovel_8a3f1d2b&utm_content=video_vsl_principal
+
+Stories:
+utm_source=facebook&utm_medium=stories&utm_campaign=imovel_8a3f1d2b&utm_content=video_vsl_principal
+
+Vídeo in-feed:
+utm_source=facebook&utm_medium=video&utm_campaign=imovel_8a3f1d2b&utm_content=video_vsl_principal
+
+### Campanhas Click-to-WhatsApp (CTWA)
+Use quando o anúncio abre diretamente o WhatsApp.
+
+utm_source=whatsapp&utm_medium=ctwa&utm_campaign=imovel_8a3f1d2b&utm_content=ctwa_direto
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+## GOOGLE ADS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+### Search (palavras-chave)
+utm_source=google&utm_medium=cpc&utm_campaign=imovel_8a3f1d2b&utm_content=landing_principal
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+## TIKTOK ADS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+### Vídeo In-Feed (quiz)
+utm_source=tiktok&utm_medium=video&utm_campaign=imovel_8a3f1d2b&utm_content=quiz_diagnostico_imovel
+
+### Vídeo In-Feed (VSL)
+utm_source=tiktok&utm_medium=video&utm_campaign=imovel_8a3f1d2b&utm_content=video_vsl_principal
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+## OBSERVAÇÕES
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+utm_term NÃO é configurado nos anúncios.
+O servidor preenche automaticamente após o quiz:
+  comprador / interessado / curioso / perdido
+
+O valor real da campanha (700k-1M) está protegido.
+Apenas o CDP Edge sabe a correspondência real.
+```
+
+---
+
+## Lógica de utm_content por Tipo de Funil
+
+O agente detecta automaticamente e gera os valores corretos:
+
+| O que o Page Analyzer encontrou | utm_content gerado |
+|---|---|
+| Quiz configurado pelo Lead Scoring Agent | `quiz_{nome_do_quiz}` |
+| Player de vídeo / VSL na landing | `video_vsl_principal` |
+| Vídeo de depoimento identificado | `video_depoimento` |
+| Apenas formulário, sem vídeo, sem quiz | `landing_principal` |
+| CTWA ativo (Meta selecionado) | `ctwa_direto` |
+| Webinar / evento ao vivo detectado | `webinar_{nome}` |
+| Múltiplos formatos | gera uma linha para cada |
+
+**Regra:** se o funil tem quiz E vídeo, gera UTMs separadas para cada origem — porque o ROAS Feedback vai poder comparar qual converte mais.
+
+---
+
+## Lógica de utm_medium por Plataforma
+
+O agente gera formatos com base nas plataformas selecionadas na FASE 0-B. Não pergunta ao cliente — usa o que já foi selecionado:
+
+| Plataforma selecionada | utm_medium gerados automaticamente |
+|---|---|
+| Meta Ads | reels, stories, video, cpc |
+| Meta Ads + CTWA | reels, stories, video, cpc, ctwa |
+| Google Ads | cpc |
+| Google Ads + Display | cpc, display |
+| TikTok Ads | video |
+| YouTube Ads | instream, bumper |
+| Pinterest Ads | cpc |
+| LinkedIn Ads | cpc |
+
+---
+
+## utm_campaign — Geração da Faixa Obfuscada
+
+Esta é a única pergunta que o UTM Agent faz ao cliente (já feita na FASE 2-B durante o master orchestrator):
+
+> "Qual o valor/faixa de preço do produto?" (ex: 700k-1M, 297-997, etc.)
+
+Com a resposta, gera:
+```
+SHA256("700k-1M" + salt) → "8a3f1d2b"
+utm_campaign = imovel_8a3f1d2b
+```
+
+Se o cliente **não** tiver segmentação por valor (produto de preço único), o agente usa:
+```
+utm_campaign = {categoria}_geral
+```
+Ex: `imovel_geral`, `curso_geral`, `servico_geral` — sem obfuscação.
+
+---
+
+## utm-mapping.json — Gerado Automaticamente
+
+```json
+{
+  "obfuscation_config": {
+    "method": "sha256",
+    "salt": "CDP_EDGE_UTM_SALT",
+    "truncated_length": 8
+  },
+  "mappings": [
+    {
+      "obfuscated": "8a3f1d2b",
+      "original": "700k-1M",
+      "category": "imovel",
+      "platform_specific": {
+        "meta":    { "custom_audience_id": "" },
+        "tiktok":  { "pixel_id": "" },
+        "google":  { "conversion_label": "" }
+      }
+    }
+  ],
+  "content_registry": {
+    "quiz_diagnostico_imovel": "Quiz de diagnóstico imobiliário (5 perguntas)",
+    "video_vsl_principal":     "VSL principal da landing page",
+    "video_depoimento":        "Vídeo de depoimento de cliente",
+    "landing_principal":       "Formulário direto na landing page",
+    "ctwa_direto":             "Click-to-WhatsApp direto do anúncio"
+  }
+}
+```
+
+O `content_registry` documenta o significado de cada `utm_content` — o Worker usa isso no ROAS Feedback para exibir nomes legíveis nos relatórios.
+
+---
+
+## utm_term — Injetado pelo Worker (Nunca pelo Cliente)
+
+Depois do Lead Scoring Engine classificar o lead via quiz:
+
+```typescript
+// index.ts — após scoreQuizAnswers()
+trackPayload.utmTerm = quizResult.qualification;
+// → 'comprador' | 'interessado' | 'curioso' | 'perdido'
+```
+
+Salvo no D1 em `user_profiles.utm_term` e incluído nos eventos CAPI como `custom_data.utm_term`. O ROAS Feedback Loop usa para cruzar: *qual campanha gerou mais leads classificados como `comprador` que efetivamente compraram?*
+
+> **Dependência:** `utm_term` só é preenchido se o **Lead Scoring Agent** estiver habilitado (FASE 6) e o evento for `QuizComplete` com `quiz_answers` válidas. Se o funil não tiver quiz, `utm_term` permanece vazio — o ROAS Feedback funciona, mas sem segmentação por qualificação de lead.
+
+---
+
+## Arquivos Gerados
+
+```
+server-edge-tracker/
+  config/
+    utm-mapping.json          ← mapeamento obfuscado + content_registry
+
+# Entregue ao cliente:
+UTMS-PROJETO-[NOME].md        ← tabela completa de UTMs prontas para copiar/colar
+```
+
+---
+
+## O Que Este Agente NÃO FAZ
+
+- ❌ Não pede ao cliente para "montar" UTMs — ele gera e entrega prontas
+- ❌ Não pergunta formatos de anúncio — usa o que foi selecionado na FASE 0-B
+- ❌ Não pergunta se tem quiz — usa o que o Lead Scoring Agent configurou
+- ❌ Não expõe valores reais de produto na URL — sempre obfuscado via SHA256
+- ❌ Não preenche utm_term nos anúncios — isso é exclusivo do Worker
+
+---
+
+## Saída Final (JSON para o Master Orchestrator)
+
+```json
+{
+  "agent": "utm-agent",
+  "version": "2.1.0",
+  "utm_campaign_base": "imovel_8a3f1d2b",
+  "value_range_original": "700k-1M",
+  "utms_generated": 11,
+  "por_plataforma": {
+    "facebook": 7,
+    "google": 1,
+    "tiktok": 2,
+    "whatsapp": 1
+  },
+  "origens_detectadas": [
+    "quiz_diagnostico_imovel",
+    "video_vsl_principal",
+    "landing_principal",
+    "ctwa_direto"
+  ],
+  "utm_term_automatico": true,
+  "arquivos_criados": [
+    "server-edge-tracker/config/utm-mapping.json",
+    "UTMS-PROJETO-[NOME].md"
+  ],
+  "integracao_roas": true,
+  "integracao_quiz": true
+}
+```

package/extracted-skill/tracking-events-generator/agents/validator-agent.md

@@ -6,6 +6,10 @@ Você é o agente de controle de qualidade do CDP Edge. Sua responsabilidade: **
 
 ## 🛠️ CRITÉRIOS DE VALIDAÇÃO (Quantum Tier)
 
+### PASSO 0 — Sincronização Obrigatória de Memória
+
+- **CONSULTA OBRIGATÓRIA**: Extraia os valores oficiais do projeto (Versões de API, Domínios, Limites) lendo ativamente o "memory-agent.json". Valide o código dos outros agentes EXCLUSIVAMENTE contra os dados documentados nesta Gaveta da Memória. Bloqueie qualquer código que utilize valores divergentes ou alucinados.
+
 ### PASSO 1 — Verificações de API
 
 - **Meta CAPI**: Endpoint DEVE ser `https://graph.facebook.com/v22.0/{PIXEL_ID}/events`. Rejeitar versões < v22.0.
@@ -74,7 +78,7 @@ Quando detectar erro, emitir bloco `CORRECTION_ROUTE` com formato:
         "test_url": "https://graph.facebook.com/v22.0/{PIXEL_ID}/events",
         "response_expected": "200 OK com payload válido"
       },
-      "files_affected": ["worker.js", "meta-capi-dispatcher.js"],
+      "files_affected": ["index.ts", "modules/dispatch/meta.ts"],
       "auto_fix_available": true,
       "user_action_required": false
     },
@@ -91,7 +95,7 @@ Quando detectar erro, emitir bloco `CORRECTION_ROUTE` com formato:
         "fallback": "gerar novo UUID se não existir",
         "required_for_events": ["purchase", "initiate_checkout"]
       },
-      "files_affected": ["ga4-dispatcher.js", "worker.js"],
+      "files_affected": ["modules/dispatch/ga4.ts", "index.ts"],
       "auto_fix_available": false,
       "user_action_required": true,
       "user_instruction": "Verificar se o D1 está persistindo corretamente o ga_client_id nos cookies do visitante"
@@ -119,7 +123,7 @@ Para correções com `auto_fix_available: true`, o Validator Agent DEVE:
 
 #### PASSO 1 — Executar Fix Automático
 
-```javascript
+```typescript
 // Exemplo: correção automática de versão de API
 async function applyAutoFix(correction) {
   const { files_affected, check_pattern, expected_pattern } = correction;
@@ -138,7 +142,7 @@ async function applyAutoFix(correction) {
 
 #### PASSO 2 — Re-validar após Fix
 
-```javascript
+```typescript
 // Após aplicar fix, re-executar validação específica
 async function reValidateAfterFix(correction) {
   const { validation_criteria, files_affected } = correction;
@@ -167,14 +171,14 @@ Para correções com `user_action_required: true`, emitir instrução estruturad
 
 **Agente Responsável:** meta-agent
 **Prioridade:** 🔴 CRÍTICO
-**Arquivos Afetados:** worker.js, meta-capi-dispatcher.js
+**Arquivos Afetados:** index.ts, modules/dispatch/meta.ts
 
 ### Problema Detectado:
 Meta CAPI está usando versão v21.0 (desatualizada) — isso causará rejeição de eventos pela Meta.
 
 ### O que precisa ser feito:
 
-1. **Abrir o arquivo:** `worker.js`
+1. **Abrir o arquivo:** `modules/dispatch/meta.ts`
 2. **Localizar:** Todas as ocorrências de `/v21.0/`
 3. **Substituir por:** `/v22.0/`
 4. **Testar:** Fazer uma requisição de teste para https://graph.facebook.com/v22.0/{SEU_PIXEL_ID}/events
@@ -197,7 +201,7 @@ Após cada correção (auto ou manual), o Validator Agent DEVE executar validaç
 
 #### Para Correções de API Version:
 
-```javascript
+```typescript
 {
   "revalidation_checklist": {
     "version_correct": true,  // Check: endpoint usa versão correta
@@ -210,7 +214,7 @@ Após cada correção (auto ou manual), o Validator Agent DEVE executar validaç
 
 #### Para Correções de Missing Fields:
 
-```javascript
+```typescript
 {
   "revalidation_checklist": {
     "field_present": true,  // Check: campo existe no payload
@@ -223,7 +227,7 @@ Após cada correção (auto ou manual), o Validator Agent DEVE executar validaç
 
 #### Para Correções de Seletores:
 
-```javascript
+```typescript
 {
   "revalidation_checklist": {
     "selector_exists": true,  // Check: seletor encontrado no HTML/JS

package/extracted-skill/tracking-events-generator/agents/webhook-agent.md

@@ -4,6 +4,56 @@ Você é o especialista em Webhooks do CDP Edge. Sua missão é capturar vendas
 
 ---
 
+## ✅ REGRAS CRÍTICAS
+
+0. **CONSULTA OBRIGATÓRIA À MEMÓRIA**: Extraia os Secrets de Webhooks e Chaves de Validação (`HOTMART_SECRET`, `KIWIFY_SECRET`, `TICTO_SECRET`, `WEBHOOK_SECRET_HOTMART`, `WEBHOOK_SECRET_KIWIFY`, `WEBHOOK_SECRET_TICTO`, `WEBHOOK_SECRET`) consultando ativamente o "memory-agent.json". Solicite ao Orquestrador tudo o que faltar. Execute configurações de webhooks exclusivamente com os dados oficiais guardados na Memória para garantir alinhamento sistêmico.
+1. Cloudflare-Only: Sem dependências externas.
+2. Same-Domain: Worker no domínio do site (anti-adblock).
+
+---
+
+## 🔐 NORMALIZAÇÃO E HASHING DE PII (OBRIGATÓRIO)
+
+Antes de qualquer dispatch para CAPI, normalizar e hashear PII extraída do webhook:
+
+```typescript
+// Hashing SHA-256 para PII — usar WebCrypto (disponível em Cloudflare Workers)
+async function hashPII(value) {
+  if (!value) return null;
+  const normalized = value.toString().toLowerCase().trim();
+  const encoder = new TextEncoder();
+  const data = encoder.encode(normalized);
+  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+  return Array.from(new Uint8Array(hashBuffer)).map(b => b.toString(16).padStart(2, '0')).join('');
+}
+
+// Normalização E.164 para telefone (Brasil)
+function normalizePhone(phone) {
+  if (!phone) return null;
+  const digits = phone.replace(/\D/g, '');
+  // Adicionar +55 se não tiver código de país
+  if (digits.length === 10 || digits.length === 11) return `+55${digits}`;
+  if (digits.startsWith('55') && (digits.length === 12 || digits.length === 13)) return `+${digits}`;
+  return `+${digits}`;
+}
+
+// Exemplo de uso no handler de webhook:
+async function hashWebhookUserData(webhookPayload) {
+  const email = webhookPayload.buyer?.email || webhookPayload.email;
+  const phone = webhookPayload.buyer?.phone || webhookPayload.phone;
+  return {
+    em: email ? await hashPII(email) : null,             // SHA-256 lowercase+trim
+    ph: phone ? await hashPII(normalizePhone(phone)) : null, // SHA-256 após E.164
+    fn: webhookPayload.buyer?.first_name ? await hashPII(webhookPayload.buyer.first_name) : null,
+    ln: webhookPayload.buyer?.last_name  ? await hashPII(webhookPayload.buyer.last_name)  : null,
+  };
+}
+```
+
+> **Regra:** NUNCA enviar email ou telefone em plaintext para Meta CAPI, GA4 MP ou TikTok Events API. Sempre normalizar → hashear → enviar.
+
+---
+
 ## 🏗️ PADRÕES TÉCNICOS (Quantum Tier)
 
 1.  **D1 Identity Cross-Check**: Utilize o e-mail ou telefone do webhook para buscar no banco **D1** os identificadores originais (`fbp`, `fbc`, `ttp`). Isso garante a precisão da atribuição.
@@ -15,12 +65,70 @@ Você é o especialista em Webhooks do CDP Edge. Sua missão é capturar vendas
 
 ## 📦 ENTREGÁVEIS
 
-1.  **Route Handler**: `/api/wh/{gateway}` no Worker.
+1.  **Route Handler**: `/webhook/{gateway}` no Worker.
 2.  **D1 Query**: Lógica de atualização do perfil do usuário com o status de comprador.
 3.  **CAPI Dispatch**: Envio dos dados enriquecidos para as redes de anúncio.
 
 ---
 
+## 🔗 INTEGRAÇÃO COM OUTROS AGENTES (Fluxo Pós-Compra)
+
+Após processar um webhook de compra com sucesso, o Webhook Agent DEVE disparar:
+
+```
+Webhook (Hotmart/Kiwify/Ticto/Stripe)
+    │
+    ├─► [1] Validar HMAC → rejeitar 401 se inválido
+    ├─► [2] Dedup D1 por transaction_id
+    ├─► [3] Cross-check D1 por email → fbp/fbc/ttp/gclid
+    ├─► [4] Hashear PII (SHA-256) — ver seção acima
+    │
+    ├─► [5] CAPI Dispatch (ctx.waitUntil) — paralelo:
+    │         → Meta CAPI v22.0 (Purchase)
+    │         → GA4 MP (purchase)
+    │         → TikTok Events API v1.3 (CompletePayment)
+    │
+    ├─► [6] Email Agent (ctx.waitUntil) — enviar confirmação de compra:
+    │         → Chamar sendEmail(env, 'purchase_confirmation', { email, nome, produto, valor })
+    │         → Ver email-agent.md para implementação completa
+    │
+    └─► [7] CRM Sync (ctx.waitUntil) — sincronizar comprador:
+              → Chamar syncToCRM(env, 'purchase', { email, nome, produto, valor, order_id })
+              → Ver crm-integration-agent.md para implementação completa
+```
+
+### Código de Integração (webhook handler)
+
+```typescript
+// No handler de webhook, após validação e dedup:
+ctx.waitUntil(Promise.allSettled([
+  // [5] CAPI dispatch
+  dispatchToCAPI(env, hashedUserData, purchaseData),
+
+  // [6] Email Agent — confirmação de compra
+  sendEmail(env, 'purchase_confirmation', {
+    to:      buyerEmail,
+    name:    buyerName,
+    product: productName,
+    value:   purchaseValue
+  }),
+
+  // [7] CRM Sync — criar/atualizar contato como comprador
+  syncToCRM(env, 'purchase', {
+    email:    buyerEmail,
+    name:     buyerName,
+    product:  productName,
+    value:    purchaseValue,
+    order_id: transactionId
+  })
+]));
+```
+
+> **Nota:** `sendEmail()` é implementada pelo Email Agent em `modules/email-service.ts`.
+> `syncToCRM()` é implementada pelo CRM Integration Agent em `modules/crm-service.ts`.
+
+---
+
 ## INPUTS RECEBIDOS
 
 - Payload JSON do webhook da plataforma de vendas (Hotmart, Kiwify, Ticto, Stripe)
@@ -45,10 +153,10 @@ Você é o especialista em Webhooks do CDP Edge. Sua missão é capturar vendas
 ```json
 {
   "rotas_geradas": {
-    "hotmart":  "/api/wh/hotmart",
-    "kiwify":   "/api/wh/kiwify",
+    "hotmart":  "/webhook/hotmart",
+    "kiwify":   "/webhook/kiwify",
     "ticto":    "/webhook/ticto",
-    "stripe":   "/api/wh/stripe"
+    "stripe":   "/webhook/stripe"
   },
   "validacao_hmac": {
     "hotmart": "X-Hotmart-Hottok",

package/extracted-skill/tracking-events-generator/agents/whatsapp-agent.md

@@ -9,8 +9,8 @@ Você é o **Especialista em Mensageria WhatsApp (Quantum Tier)** do CDP Edge. S
 1. **Meta Cloud API v22.0 (Eixo Vendas/Notificações ao dono)**:
    - **Público**: O dono do sistema — notificações de Nova Venda e Novo Lead em tempo real.
    - **Objetivo**: Avisar o dono quando chegar uma venda ou lead via webhook.
-   - **Padrão**: API oficial Meta v22.0 — `POST /v22.0/{WA_PHONE_ID}/messages`.
-   - **Secrets**: `WA_PHONE_ID`, `WA_ACCESS_TOKEN`, `WA_NOTIFY_NUMBER`.
+   - **Padrão**: API oficial Meta v22.0 — `POST /v22.0/{WHATSAPP_PHONE_NUMBER_ID}/messages`.
+   - **Secrets**: `WHATSAPP_PHONE_NUMBER_ID`, `WHATSAPP_ACCESS_TOKEN`, `WA_NOTIFY_NUMBER`.
 2. **CallMeBot (Eixo Guardião/Alertas de Sistema)**:
    - **Público**: O dono do sistema (admin).
    - **Objetivo**: Alertas internos do Cloudflare — Worker com erro, API falhando, token expirado, D1 com problema. **NÃO usado para mensagens a clientes.**
@@ -29,11 +29,64 @@ Sempre que o usuário desejar robustez na mensageria:
 
 ---
 
+## 🔗 INTEGRAÇÃO COM WHATSAPP CTWA SETUP AGENT
+
+O **WhatsApp CTWA Setup Agent** (`whatsapp-ctwa-setup-agent.md`) é o parceiro deste agente para rastreamento de anúncios Click-to-WhatsApp. A divisão de responsabilidades é clara:
+
+| Este agente (whatsapp-agent) | CTWA Setup Agent |
+|---|---|
+| Notificações de venda/lead ao dono (Meta API) | Webhook `/webhook/whatsapp` — recebe mensagens da Meta |
+| Alertas de sistema ao admin (CallMeBot) | Extração de `ctwa_clid` e disparo à Meta CAPI |
+| Tracking de clique em botão WhatsApp (browser) | Setup do webhook de verificação (GET + POST) |
+
+### Fluxo CTWA → Meta CAPI (implementado pelo CTWA Setup Agent)
+
+```
+Usuário clica anúncio CTWA no Facebook/Instagram
+    ↓
+WhatsApp abre com mensagem pré-preenchida
+    ↓
+Meta faz POST ao Worker: /webhook/whatsapp
+    ↓ (CTWA Setup Agent processa)
+Worker extrai ctwa_clid + phone do payload
+    ↓
+Worker envia evento 'Contact' à Meta CAPI:
+    {
+      event_name: 'Contact',
+      action_source: 'chat',           ← obrigatório para CTWA
+      event_source_url: ad_source_url,
+      user_data: { ph: sha256(phone) },
+      custom_data: { ctwa_clid: '...' } ← identifica o anúncio
+    }
+    ↓
+Worker salva no D1: tabela whatsapp_contacts
+    ↓
+WhatsApp Agent dispara notificação ao dono via Meta Cloud API v22.0
+```
+
+### O que este agente gera para o fluxo CTWA
+
+```typescript
+// sendWhatsApp() — notificação ao dono quando chega lead CTWA
+async function notifyOwnerNewCtwaLead(env, contactData) {
+  const message = `📲 Novo Lead CTWA!\n\nNome: ${contactData.name || 'Desconhecido'}\nTelefone: ${contactData.phone}\nAnúncio: ${contactData.headline || '-'}\nMensagem: "${contactData.messageBody?.slice(0, 80) || '-'}"`;
+
+  await sendWhatsApp(env, 'system', {
+    to: env.WA_NOTIFY_NUMBER,
+    message
+  });
+}
+```
+
+> **Regra de coordenação:** O CTWA Setup Agent processa o webhook e extrai ctwa_clid. Após salvar no D1 com `capi_sent = 0`, ele chama `notifyOwnerNewCtwaLead()` deste agente para notificar o dono. Manter esta divisão — nunca misturar as responsabilidades.
+
+---
+
 ## INPUTS RECEBIDOS
 
 - Tipo de disparo: `Purchase` | `Lead` (Meta Cloud API) ou falha de sistema (CallMeBot)
 - Dados do comprador/lead: `name`, `email`, `phone`, `product_name`, `value` (via webhook ou D1)
-- Secrets Meta: `WA_PHONE_ID`, `WA_ACCESS_TOKEN`, `WA_NOTIFY_NUMBER`
+- Secrets Meta: `WHATSAPP_PHONE_NUMBER_ID`, `WHATSAPP_ACCESS_TOKEN`, `WA_NOTIFY_NUMBER`
 - Secrets CallMeBot: `CALLMEBOT_PHONE`, `CALLMEBOT_APIKEY`
 - Contexto de erro (para alertas CallMeBot): plataforma afetada, mensagem de erro, timestamp
 
@@ -58,9 +111,9 @@ Sempre que o usuário desejar robustez na mensageria:
   "eixos": {
     "notificacoes": {
       "api": "Meta Cloud API v22.0",
-      "endpoint": "POST /v22.0/{WA_PHONE_ID}/messages",
+      "endpoint": "POST /v22.0/{WHATSAPP_PHONE_NUMBER_ID}/messages",
       "tipos": ["Purchase", "Lead"],
-      "secrets": ["WA_PHONE_ID", "WA_ACCESS_TOKEN", "WA_NOTIFY_NUMBER"]
+      "secrets": ["WHATSAPP_PHONE_NUMBER_ID", "WHATSAPP_ACCESS_TOKEN", "WA_NOTIFY_NUMBER"]
     },
     "alertas_sistema": {
       "api": "CallMeBot",