Checklist de implementação da Meta CAPI: do zero à produção sem perder conversão

A Meta Conversions API (CAPI) existe para resolver um problema concreto: o rastreamento que depende só do navegador está cada vez mais frágil. Bloqueadores de anúncio, restrições de cookies de terceiros, limitações do Safari/ITP e a simples perda de eventos por falha de rede corroem a base de dados que o algoritmo de entrega usa para otimizar campanhas. A CAPI complementa (não substitui) o Pixel enviando os mesmos eventos direto do seu servidor para a Meta, num canal que você controla — o resultado é maior cobertura de conversão, melhor qualidade de correspondência (EMQ) e otimização mais estável.

O problema é que uma implementação malfeita causa dano silencioso: eventos duplicados que inflam métricas, hashing errado que zera a correspondência, ou parâmetros faltando que derrubam o EMQ. Este guia é um checklist acionável, do zero à produção, em seis fases. Percorra na ordem, marque cada item e só avance quando a fase anterior estiver fechada. Nada aqui depende de uma tela específica que a Meta muda a cada trimestre — descrevo conceitualmente onde cada coisa vive, para o guia continuar válido.

Fase 1 — Pré-requisitos#

Antes de escrever uma linha de código, garanta que você tem os identificadores, credenciais e permissões corretos. Metade dos problemas de CAPI nasce aqui, com o dataset errado ou um token sem escopo.

• [ ] Localize o Dataset ID (antigo Pixel ID) no gerenciador de eventos da sua conta de negócios. É o mesmo ID usado pelo Pixel no navegador — CAPI e Pixel precisam apontar para o mesmo dataset para a deduplicação funcionar.
• [ ] Gere um access token de sistema (system user token), com permissão de gerenciamento sobre o dataset. Prefira token de usuário do sistema a token pessoal: ele não expira junto com uma sessão humana e pode ser rotacionado sem quebrar a integração.
• [ ] Confirme as permissões: o usuário do sistema precisa ter papel sobre o dataset (nível de gerenciamento de eventos) e sobre a conta de anúncios que consome esses eventos.
• [ ] Guarde o token como segredo server-side. Nunca coloque o access token em bundle de frontend, variável pública (NEXT_PUBLIC_, VITE_, PUBLIC_*) ou repositório. Ele mora em secret manager ou variável de ambiente do servidor. Quem vaza esse token entrega o controle do seu dataset.
• [ ] Defina os eventos-chave do funil (ex.: ViewContent, AddToCart, InitiateCheckout, Purchase, Lead). Não instrumente tudo de uma vez; comece pelos eventos que a campanha otimiza e pelos que reportam valor.
• [ ] Defina a política de valor e moeda: quais eventos carregam value monetário, em qual currency (ISO 4217, ex.: BRL), e de onde esse valor vem no servidor (fonte da verdade é o backend, não o preço exibido na página).
• [ ] Documente um dicionário de eventos interno: para cada evento, o gatilho de negócio, os parâmetros esperados e se dispara também no Pixel. É a referência de todo o resto.

Fase 2 — Modelagem dos eventos#

Aqui você desenha o contrato de dados. A decisão mais crítica é a deduplicação: como a Meta reconhece que o evento do Pixel e o do servidor são o mesmo, e conta uma vez só.

• [ ] Mapeie a jornada e associe cada etapa a um evento. Uma etapa do funil = um evento nomeado de forma estável.
• [ ] Prefira eventos padrão (standard events) sempre que existir um que descreva a ação. Eles têm suporte nativo para otimização e relatórios. Use evento customizado só quando nenhum padrão descreve a ação — e mantenha o nome consistente entre Pixel e servidor.
• [ ] Defina o action_source por evento. Para compras no site, use website. Outros valores (app, phone_call, chat, email, physical_store, system_generated, other) descrevem onde a conversão aconteceu de fato. Enviar action_source errado degrada a atribuição.
• [ ] Preencha o event_time com o momento real da conversão, em Unix timestamp (segundos), no fuso UTC. A Meta aceita eventos com atraso (útil para conversões offline e processamento assíncrono), mas há uma janela limite — não envie eventos velhos demais.
• [ ] Gere um event_id compartilhado entre Pixel e CAPI para o mesmo evento. Esse é o coração da deduplicação: quando os dois canais mandam o mesmo event_id + event_name, a Meta conta uma única conversão. Sem isso, você dobra a contagem.
• [ ] Padronize a origem do event_id: gere-o no servidor (ou no ponto que dispara os dois canais) e propague o mesmo valor para o Pixel via eventID. IDs independentes em cada lado nunca vão bater.
• [ ] Envie o event_source_url (a URL onde a ação ocorreu) para eventos de website; ele reforça a correspondência.
• [ ] Decida a estratégia de redundância: o padrão recomendado é enviar cada evento pelos dois canais com o mesmo event_id, deixando a deduplicação limpar a sobreposição — máxima cobertura sem inflar contagem.

Fase 3 — Parâmetros de correspondência (user_data)#

O user_data é o que permite à Meta casar o evento com uma pessoa. Quanto mais sinais válidos e bem normalizados você enviar, maior o EMQ (Event Match Quality) e melhor a atribuição. A regra inegociável: todo dado pessoal identificável vai hasheado com SHA-256, exceto os identificadores de clique e IP/user agent, que vão em texto puro.

• [ ] Selecione os parâmetros de correspondência disponíveis com segurança no servidor: e-mail (em), telefone (ph), nome (fn, ln), cidade (ct), estado (st), CEP (zp), país (country), data de nascimento (db), gênero (ge) e ID externo (external_id).
• [ ] Normalize antes de hashear. O hash de " JOAO@Email.com " é diferente do hash de joao@email.com. Normalização errada é a causa nº 1 de EMQ baixo. Aplique a cada campo:
• [ ] E-mail: trim, tudo minúsculo.
• [ ] Telefone: só dígitos, com código do país, sem +, sem espaços, sem traços.
• [ ] Nome/cidade/estado: minúsculo, sem espaços nas pontas; remova pontuação; para estado, use a abreviação de duas letras quando aplicável.
• [ ] CEP: minúsculo, sem espaços; no Brasil, os oito dígitos sem traço.
• [ ] País: código ISO de duas letras em minúsculo (ex.: br).
• [ ] Data de nascimento: formato YYYYMMDD.
• [ ] Hasheie com SHA-256 e envie o resultado em hexadecimal minúsculo. Um campo por valor; nunca concatene dois dados no mesmo hash.
• [ ] Nunca hasheie os identificadores de clique nem os técnicos: fbc, fbp, client_ip_address, client_user_agent e external_id (este pode ir hasheado ou não, mas seja consistente) vão conforme a especificação, e os três primeiros vão em texto puro.
• [ ] Capture o fbc (click ID) a partir do parâmetro fbclid da URL de entrada. Se o fbc não estiver no cookie _fbc, construa-o no formato fb.1.<timestamp_ms>.<fbclid> e persista.
• [ ] Capture o fbp (browser ID) do cookie _fbp que o Pixel grava. Propague-o do navegador para o servidor (via corpo da requisição ou cookie) para enviá-lo no user_data.
• [ ] Envie client_ip_address e client_user_agent capturados na requisição real do usuário — do cabeçalho da requisição que chega ao seu servidor, não do IP do próprio servidor. Sem eles, a correspondência baseada em navegador enfraquece.
• [ ] Trate campos ausentes omitindo-os, nunca enviando string vazia hasheada. Um hash de string vazia é um valor válido e sujo, que polui a correspondência.

Exemplo de normalização e hashing de um campo (ilustrativo, em JavaScript):

```js import { createHash } from "node:crypto";

// Normaliza e-mail e telefone, depois aplica SHA-256 em hex minúsculo. // Onde: chamado ao montar o user_data de cada evento CAPI, antes do envio. function sha256(value) { return createHash("sha256").update(value, "utf8").digest("hex"); }

function hashEmail(raw) { if (!raw) return undefined; // ausente: OMITE, não manda vazio const normalized = raw.trim().toLowerCase(); return sha256(normalized); }

function hashPhone(raw, countryCode = "55") { if (!raw) return undefined; let digits = raw.replace(/\D/g, ""); // só dígitos if (!digits.startsWith(countryCode)) { // garante código do país digits = countryCode + digits; } return sha256(digits); // sem "+", sem espaços }

// hashEmail(" Joao@Email.com ") -> hash de "joao@email.com" // hashPhone("(11) 98888-7777") -> hash de "5511988887777" ```

Fase 4 — Envio server-side#

Com o payload modelado, o envio precisa ser resiliente. Rede falha, a API responde 5xx, timeouts acontecem — e sua fila não pode nem travar o fluxo do usuário nem perder conversão.

• [ ] Envie os eventos para o endpoint do Graph API do dataset, no caminho /{dataset-id}/events, via POST, passando o access token. Fixe a versão da API na URL para evitar quebra silenciosa quando a Meta lança versão nova.
• [ ] Monte o payload com um array data de eventos. Cada objeto traz event_name, event_time, event_id, action_source, event_source_url, user_data e custom_data (com value, currency, content_ids, etc.).
• [ ] Faça batching: agrupe vários eventos num único data, respeitando o limite de eventos por requisição. Para alto volume, uma fila que despacha em lotes é mais robusta que um POST por evento.
• [ ] Desacople o envio do request do usuário. Coloque o evento numa fila/outbox e despache em background (worker). O checkout não pode esperar a resposta da Meta nem falhar porque a CAPI está lenta.
• [ ] Implemente retry com backoff exponencial para erros transitórios (timeout, 5xx, rate limit). Não faça retry de erro 4xx de validação — corrija o payload.
• [ ] Garanta idempotência: o event_id estável já protege contra dobra de contagem no lado da Meta, mas mantenha na fila um controle para não reprocessar o mesmo evento indefinidamente. Combine event_id + limite de tentativas.
• [ ] Configure timeout curto na chamada HTTP e trate a resposta: nunca engula o erro; logue falhas com um identificador de rastreio.
• [ ] Persistir na fila antes de despachar dá durabilidade: se a Meta estiver fora, o evento espera e é retomado, sem perder conversão.

Exemplo de payload da CAPI (ilustrativo — sem chaves reais):

``json { "data": [ { "event_name": "Purchase", "event_time": 1735680000, "event_id": "order-7f3c1a92-b8d4-4e21", "action_source": "website", "event_source_url": "https://loja.exemplo.com/checkout/sucesso", "user_data": { "em": ["e3b0c44298fc1c149afbf4c8996fb924..."], "ph": ["8d969eef6ecad3c29a3a629280e686cf..."], "fbc": "fb.1.1735679000000.IwAR0abc123", "fbp": "fb.1.1735670000000.987654321", "client_ip_address": "203.0.113.42", "client_user_agent": "Mozilla/5.0 (X11; Linux x86_64)" }, "custom_data": { "value": 249.90, "currency": "BRL", "content_ids": ["SKU-1023"], "content_type": "product" } } ] } ``

Note que o event_id (order-7f3c1a92-b8d4-4e21) é exatamente o mesmo que o Pixel enviaria como eventID para esta compra — essa igualdade dispara a deduplicação. Os campos em e ph estão hasheados; fbc, fbp, IP e user agent, em texto puro.

Fase 5 — Validação#

Não suba para produção sem provar que os eventos chegam, são atribuídos e desduplicam. Esta fase separa "o código roda" de "os dados estão corretos".

• [ ] Use um test event code (código de teste de eventos, gerado na área de teste do gerenciador de eventos) e inclua-o no campo test_event_code do payload durante os testes. Eventos com esse código aparecem em tempo real na aba de teste, sem poluir os dados de produção.
• [ ] Confirme no gerenciador de eventos que cada evento-chave aparece, com o event_name correto e a origem marcada como servidor.
• [ ] Verifique os parâmetros recebidos: o gerenciador indica quais campos de user_data chegaram e quais foram reconhecidos. Campos rejeitados normalmente indicam normalização ou hashing errados — volte à Fase 3.
• [ ] Cheque a deduplicação: dispare o mesmo evento pelo Pixel e pela CAPI com o mesmo event_id e confirme que a plataforma reporta os eventos como desduplicados, não como dois eventos separados. Se aparecerem dois, o event_id ou o event_name estão divergindo entre os canais.
• [ ] Avalie o EMQ (Event Match Quality) de cada evento. Um EMQ baixo aponta poucos parâmetros de correspondência ou dados mal normalizados. Adicione mais sinais válidos (fbc, fbp, e-mail, telefone, external_id) e corrija a normalização até subir.
• [ ] Valide casos de borda: usuário sem e-mail, sem fbclid, com telefone internacional, com caracteres acentuados no nome. O payload deve omitir o ausente e normalizar o presente sem quebrar.
• [ ] Remova o test_event_code antes do go-live. Se ele ficar no payload de produção, seus eventos reais podem ser tratados como teste.

Fase 6 — Go-live e monitoramento#

Publicar não é o fim; é o começo do monitoramento. A CAPI falha de forma silenciosa — o volume cai, o EMQ despenca ou a deduplicação para de casar — e sem alertas você só descobre pela campanha entregando pior.

• [ ] Faça o rollout gradual: ative a CAPI primeiro para uma fração do tráfego ou um evento, confirme a saúde dos dados, e então expanda para todos os eventos-chave.
• [ ] Crie alerta de queda de volume: compare o volume de eventos por hora/dia contra a linha de base. Uma queda abrupta indica quebra de integração (token expirado, deploy que sumiu com o fbp, endpoint fora).
• [ ] Monitore a cobertura de deduplicação: acompanhe a proporção de eventos que casam entre Pixel e CAPI. Se a taxa cair, algo divergiu no event_id.
• [ ] Monitore o EMQ ao longo do tempo, por evento. Regressão de EMQ costuma vir de mudança no frontend que parou de propagar um parâmetro (ex.: cookie _fbp não chegando mais ao servidor).
• [ ] Instrumente observabilidade no worker de envio: taxa de sucesso/erro, latência da chamada, tamanho da fila, tentativas de retry. Exponha métricas e logue falhas com identificador de rastreio.
• [ ] Configure alerta de erro da API: picos de 4xx indicam payload inválido (corrija o código); picos de 5xx ou timeout indicam problema do lado da Meta ou de rede (deixe o retry trabalhar, mas alerte se a fila crescer sem drenar).
• [ ] Estabeleça rotação do access token: defina lembrete de rotação e um procedimento que troca o segredo sem downtime. Token vencido derruba a integração inteira de uma vez.
• [ ] Faça revisão periódica do dicionário de eventos: sempre que o funil mudar (novo passo, novo produto, novo valor), atualize a modelagem, os parâmetros e os testes antes de mexer no código de produção.
• [ ] Documente um runbook de incidente: como diagnosticar volume zerado, EMQ despencando ou deduplicação quebrada — e quem aciona. O time que herda a integração precisa disso.

Fechando o ciclo#

A Meta CAPI bem implementada é invisível quando funciona e barulhenta quando quebra — desde que você tenha construído os alertas. As três armadilhas que mais custam conversão são sempre as mesmas: event_id divergente entre Pixel e servidor (dobra a contagem ou zera a dedup), normalização errada antes do hash (mata o EMQ) e envio acoplado ao request do usuário (perde evento quando a API oscila).

Trate este checklist como um contrato de qualidade, não como um passo burocrático. Cada item marcado é uma classe de bug que você já não vai depurar em produção com a campanha entregando mal. Comece pelos eventos que a campanha otimiza, prove a deduplicação e o EMQ na validação antes de escalar, e mantenha o monitoramento ligado desde o primeiro dia. A diferença entre uma CAPI que recupera conversão perdida e uma que só polui o dataset está nos detalhes que este guia enumera.