API de Conversões da Meta e pixel: por que usar os dois e como gerar o token com usuário do sistema

Resposta rápida

A API de Conversões da Meta envia eventos pelo servidor e o pixel, pelo navegador. Use os dois com o mesmo event_id para a Meta contar cada compra uma vez, mande e-mail e telefone normalizados com hash SHA-256 para subir a qualidade de correspondência e gere o token com um usuário do sistema por cliente, só com o pixel.

O que o pixel mede e o que a API de Conversões mede?

Os dois medem a mesma coisa, a ação do cliente depois do anúncio, mas por caminhos diferentes. O pixel é um script que roda no navegador de quem visita a página e manda o evento de lá. A API de Conversões (CAPI) é o seu servidor, ou o servidor da plataforma de vendas, mandando o evento direto para a Meta, sem depender do navegador.

A própria Meta descreve a API de Conversões como a conexão entre os dados do servidor, do site, do app ou do CRM do anunciante e os sistemas de anúncio, e trata os eventos que chegam por ela como trata os do pixel. Na prática: o pixel vê o comportamento, o servidor vê o fato. Um boleto gerado é compra para o pixel; para o servidor, só vira compra quando é pago.

Por que usar os dois ao mesmo tempo?

Porque cada um cobre o buraco do outro, e a Meta recomenda exatamente essa configuração, que ela chama de redundante: pixel e API de Conversões enviando os mesmos eventos. Quando o navegador bloqueia o pixel, o servidor ainda entrega a compra. Quando a integração do servidor não tem o cookie do clique, o pixel ainda leva o contexto da navegação.

• Só pixel: perde a compra de quem usa bloqueador ou fecha a página de obrigado antes de carregar, e conta boleto não pago como venda.
• Só servidor: perde o comportamento de navegação (visualização de página, adição ao carrinho) se o seu backend não souber dele, e costuma ter menos cookies para casar o evento com a pessoa.
• Os dois, com desduplicação: a Meta recebe o evento por dois caminhos e conta uma vez.

Como funciona a desduplicação por event_id?

A Meta junta dois eventos quando eles chegam ao mesmo pixel com o mesmo nome de evento e o mesmo identificador: o eventID do lado do pixel precisa bater com o event_id do lado do servidor, e o event do pixel com o event_name da API. Pela documentação, se a mesma combinação chega do navegador e do servidor em até 48 horas, os eventos seguintes são descartados.

No pixel, o identificador vai no quarto argumento da chamada:

fbq('track', 'Purchase', {value: 197, currency: 'BRL'}, {eventID: 'pedido-48213'});

No servidor, o mesmo pedido-48213 vai no campo event_id do evento Purchase. A Meta sugere usar o número do pedido ou o ID da transação quando ele existe. Para evento sem ID natural, como visualização de página, vale um número aleatório, desde que seja o mesmo nos dois lados, o que na prática significa gerar no navegador e repassar ao servidor.

Quais são os erros de event_id mais comuns?

• ID gerado duas vezes: o navegador sorteia um, o servidor sorteia outro. Nada casa e tudo conta dobrado.
• Nome de evento diferente: Purchase no pixel e purchase ou Compra no servidor não é o mesmo evento.
• ID repetido entre pedidos: usar o ID do produto em vez do ID do pedido faz a Meta descartar a segunda venda do mesmo produto como se fosse cópia.
• Servidor atrasado demais: passou da janela de 48 horas, o evento do servidor não é mais reconhecido como duplicata.

Existe um método alternativo, por fbp ou external_id, mas a própria documentação limita: ele funciona quando o evento do navegador chega primeiro. Se você controla o código, use event_id.

O que é a qualidade de correspondência de eventos (EMQ)?

É a nota, de 0 a 10, que a Meta dá para cada evento de servidor, indicando o quanto os dados de cliente enviados ajudam a ligar aquele evento a uma conta da Meta. Ela aparece no Gerenciador de Eventos, no detalhe de cada evento, e hoje vale para eventos de site.

A lógica é simples: a Meta só otimiza e atribui a compra se souber quem comprou. Um evento de compra sem e-mail, sem telefone e sem cookie é um número solto, que não ensina nada ao algoritmo. A Meta não publica uma nota mínima oficial; a regra prática é comparar a nota de cada evento com a dos outros da mesma conta e atacar primeiro o evento que otimiza a campanha, geralmente a compra ou o lead.

Quais parâmetros de usuário sobem a nota?

A Meta lista como recomendados, além dos obrigatórios, e-mail, IP, nome completo e telefone. Veja o que cada um exige:

Dois cuidados que derrubam nota sem ninguém perceber. Primeiro, não aplique hash em IP, user agent, `fbp` e `fbc`: esses vão como estão. Segundo, fbp e fbc mudam; leia do cookie no momento do evento, não de um valor guardado meses atrás. Em venda que chega por webhook dias depois, guarde os dois junto com o pedido no momento do checkout.

Quais campos o evento de site não pode esquecer?

• event_name, event_time e user_data em todo evento.
• action_source, obrigatório: website para site, business_messaging para conversa, physical_store para loja física, entre outros. A Meta exige que ele seja verdadeiro.
• event_source_url, obrigatório em evento de site: a URL onde a ação aconteceu.
• event_time de no máximo 7 dias atrás. Um evento velho no lote faz a Meta recusar o lote inteiro, e o mesmo vale para qualquer evento inválido num lote de até 1.000.

A recomendação da Meta é enviar assim que o evento acontece, idealmente em até uma hora. Para testar, use o test_event_code na ferramenta de teste de eventos e tire antes de ir para produção.

Qual caminho de implementação escolher?

Depende de onde a venda acontece, não de preferência técnica:

O Gateway é a opção sem código da Meta: roda numa conta de nuvem do próprio anunciante (AWS ou GCP), recebe os eventos do pixel e os reenvia pelo servidor, gerando e propagando o event_id sozinho. Ele exige alguma familiaridade técnica e custo de nuvem, mas resolve a desduplicação sem mexer no site.

Em todos os casos, alguém vai pedir um token de acesso. É aqui que a agência costuma errar.

Como a agência gera o token da CAPI com um usuário do sistema?

Usuário do sistema é uma conta de máquina dentro do Business Manager (o portfólio empresarial): não é uma pessoa, não sai de férias, não troca de senha e só enxerga os ativos que você atribuir a ele. É o jeito certo de dar a uma integração acesso ao pixel sem usar o perfil pessoal de ninguém.

Há dois caminhos oficiais. O rápido: no Gerenciador de Eventos, nas configurações do pixel, a opção de gerar token na configuração manual da API de Conversões. A Meta cria sozinha um app e um usuário do sistema para a API de Conversões. O controlado, que recomendamos para agência:

1. Nas configurações do negócio do cliente, abra a área de usuários do sistema e crie um, com nome que diga o que ele faz, por exemplo capi-loja-exemplo.
2. Escolha a função padrão (funcionário), não administrador. A Meta reserva o administrador para ações administrativas e recomenda proteger esse token com cuidado redobrado.
3. Atribua a esse usuário só o pixel do cliente, com permissão para gerenciá-lo. Nada de conta de anúncio, página ou catálogo se a integração só envia evento.
4. Clique em gerar token, escolha o app e marque o mínimo de permissões que a tela pedir. A Meta dispensa revisão de app para a API de Conversões.
5. Escolha a validade. A Meta oferece token que nunca expira e token de 60 dias, e chama o de 60 dias de boa prática de segurança.
6. Copie o token na hora e guarde no cofre de senhas da agência. Trate como senha: quem tem o token envia evento em nome do cliente.
7. Cole o token na integração (plataforma de checkout, Gateway ou variável de ambiente do servidor) e dispare um evento de teste com test_event_code.

Um usuário do sistema por cliente ou um para todos?

Um por cliente, criado no Business Manager do cliente. Juntar todos os pixels num único usuário do sistema da agência parece prático até o dia em que o token vaza: aí um só código dá acesso ao pixel de todos os clientes. A própria Meta recomenda criar um usuário do sistema para cada tipo de acesso.

• O ativo é do cliente. Pixel, token e usuário do sistema ficam no negócio dele. Se a agência sai, ele revoga o acesso da agência e a medição continua funcionando.
• O dano de um vazamento fica contido a um cliente e a um pixel.
• Revogar é um clique: cliente encerrou o contrato, a agência apaga o token ou tira o pixel do usuário do sistema.
• Token nunca em código de navegador, nem em planilha compartilhada, nem colado no grupo de WhatsApp da equipe. Vai para o cofre e para variável de ambiente.

A mesma lógica vale para a equipe: cada pessoa acessa só as contas de que cuida. Montamos esse raciocínio em equipe com acesso por conta de anúncio e em como gerenciar várias contas de anúncio.

Como saber se a implementação está certa?

1. Na ferramenta de teste de eventos, dispare uma compra de teste e confira se chegam o evento do navegador e o do servidor, e se a Meta marca um deles como desduplicado.
2. No detalhe do evento de compra, veja a nota de qualidade de correspondência e quais parâmetros a Meta diz estarem faltando.
3. Compare, por uma semana, as compras do Gerenciador com as vendas aprovadas da plataforma. Diferença grande para cima é contagem dupla ou boleto; para baixo é evento perdido.
4. Remova o test_event_code antes de liberar a produção.