Como configurar a Meta CAPI passo a passo

Pré-requisitos

Antes de começar, garante que você tem:

• Conta de Meta Business Manager (business.facebook.com);
• Pixel do Facebook já criado e funcionando no site (com pelo menos PageView disparando);
• Acesso de admin no pixel;
• Servidor backend onde rodar o código (PHP, Node, Python, Ruby — qualquer um serve);
• Capacidade de fazer requests HTTPS de saída (firewall permitindo graph.facebook.com).

Passo 1 — Gerar o access token

1. Abra Events Manager;
2. Selecione o pixel que você quer usar;
3. Vá em Settings → role até Conversions API;
4. Clique em Generate access token;
5. Copie o token. Você não conseguirá ver de novo depois. Guarde com cuidado.

Passo 2 — Copiar o Pixel ID

Ainda no Events Manager, no topo da página do pixel você verá o Pixel ID (15 dígitos). Copie. Vai junto com o access token.

Passo 3 — Montar o payload

Estrutura mínima do payload de um evento Purchase:

{
  "data": [{
    "event_name": "Purchase",
    "event_time": 1716640000,
    "event_id": "order_10042_purchase",
    "action_source": "website",
    "event_source_url": "https://sualoja.com.br/checkout/success",
    "user_data": {
      "em": ["a3f2b9c8d4e5f6a1..."],
      "ph": ["b4e5f6a2c3d9..."],
      "client_ip_address": "200.123.45.67",
      "client_user_agent": "Mozilla/5.0...",
      "fbp": "fb.1.1716640000.123456789",
      "fbc": "fb.1.1716640000.IwAR..."
    },
    "custom_data": {
      "value": 99.90,
      "currency": "BRL",
      "content_ids": ["SKU-001"],
      "content_type": "product"
    }
  }],
  "test_event_code": "TEST12345"
}

Campos obrigatórios:

• event_name: nome padrão do Meta — Purchase, Lead, CompleteRegistration, AddToCart, etc.
• event_time: Unix timestamp em segundos, não milissegundos. Erro comum.
• action_source: "website", "app", "phone_call", etc.
• event_id: pra deduplicação com pixel client (ver guia de dedupe).
• user_data: identificadores do usuário (email, telefone, IP). Quanto mais campos, maior o Match Quality.

Passo 4 — Enviar via cURL (ou seu HTTP client favorito)

curl -X POST "https://graph.facebook.com/v19.0/{PIXEL_ID}/events" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [...],
    "access_token": "EAAxx..."
  }'

Em PHP:

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://graph.facebook.com/v19.0/{$pixel_id}/events");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'data' => [$event_payload],
    'access_token' => $access_token
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

Resposta de sucesso (HTTP 200):

{
  "events_received": 1,
  "messages": [],
  "fbtrace_id": "AbcDefGhi..."
}

Passo 5 — Compartilhar event_id com o pixel pra deduplicação

No frontend, ao disparar o pixel:

fbq('track', 'Purchase', {
  value: 99.90,
  currency: 'BRL'
}, {
  eventID: 'order_10042_purchase'  // ← mesmo do CAPI
});

Detalhamos no guia completo de deduplicação.

Passo 6 — Hashear PII com SHA-256

Email e telefone nunca podem ir em plaintext. Normalize antes do hash:

// PHP
function hashEmail($email) {
    return hash('sha256', strtolower(trim($email)));
}

function hashPhone($phone) {
    // Normaliza pra E.164: +5511999998888
    $digits = preg_replace('/[^0-9]/', '', $phone);
    if (strlen($digits) === 11) $digits = '55' . $digits;
    return hash('sha256', '+' . $digits);
}

$user_data = [
    'em' => [hashEmail($order->customer_email)],
    'ph' => [hashPhone($order->customer_phone)],
    'fn' => [hash('sha256', strtolower(trim($order->customer_first_name)))],
    'ln' => [hash('sha256', strtolower(trim($order->customer_last_name)))],
    'ct' => [hash('sha256', strtolower($order->city))],
    'st' => [hash('sha256', strtolower($order->state))],
    'zp' => [hash('sha256', preg_replace('/[^0-9]/', '', $order->zip))],
    'country' => [hash('sha256', 'br')],
    'client_ip_address' => $_SERVER['REMOTE_ADDR'],
    'client_user_agent' => $_SERVER['HTTP_USER_AGENT'],
    'fbp' => $_COOKIE['_fbp'] ?? null,
    'fbc' => $_COOKIE['_fbc'] ?? null,
];

Passo 7 — Testar no Events Manager

Antes de subir pra produção, teste com test_event_code:

1. Events Manager → seu pixel → aba Test Events;
2. Copie o código de teste (formato: TEST12345);
3. Inclua no payload: "test_event_code": "TEST12345";
4. Dispare o evento. Em segundos ele aparece no Events Manager com label "Test event";
5. Confira: campos do user_data hasheados? event_id casando com pixel?

Passo 8 — Validar em produção

Depois de testar, remova o test_event_code do payload de produção. Senão Meta marca como teste e não conta na otimização.

Monitore no Events Manager:

• Event Activity: quantos eventos chegando por hora;
• Diagnostics: avisos de problemas (deduplicação falha, campos malformados);
• Event Match Quality: score 1-10 por evento — meta 7+.

Troubleshooting comum

"Event time in the past" ou "in the future"

Você está enviando timestamp em milissegundos. Meta espera segundos. Divida por 1000.

EMQ travado em 0

Provavelmente o email/telefone não está sendo hasheado, ou está sendo hasheado errado (sem lowercase/trim antes). Compare seu hash com echo -n "[email protected]" | shasum -a 256.

Eventos duplicados (Meta avisa)

event_id do pixel ≠ event_id do CAPI. Garantir que é a MESMA string. Ver guia de dedupe.

"Invalid OAuth access token"

Token expirou ou foi revogado. Gere outro no Events Manager.

FAQ

Preciso de programador pra configurar CAPI?

Depende. Setup via Shopify ou CMS com integração nativa (Cartpanda, Yampi) leva 5-15 minutos sem código. Setup via webhook ou direto na API requer dev pra umas 2-4 horas. Setup via SaaS (Trakvo, Stape) requer 0 código — só conectar OAuth.

Quanto tempo até ver melhoria no Match Quality?

EMQ atualiza em até 48h após eventos começarem a chegar. Pra subir de 5 → 8+ você precisa de pelo menos 7 dias de eventos consistentes com PII enriquecido (email + telefone + click IDs).

O Meta cobra pra usar a CAPI?

Não. CAPI é gratuito. Você só paga sua infra (servidor) ou o SaaS que cuida disso pra você.

Posso configurar CAPI sem o pixel?

Tecnicamente sim, mas Meta NÃO recomenda. Pixel pega eventos rápidos no client (PageView, AddToCart) com baixa latência. CAPI cobre conversões críticas com privacidade. Rodando os dois juntos = melhor cenário.

O que é o access token da CAPI e onde gero?

Access token é uma chave secreta que autoriza seu servidor a enviar eventos pra Meta. Gerado em Meta Events Manager → Settings → Conversions API → Generate Access Token. Trate como senha — nunca expor no frontend.