Tracking e atribuição

API de Conversões da Meta (CAPI): guia completo para e-commerce

A API de Conversões manda as vendas da loja direto do servidor para a Meta. Veja os eventos de e-commerce, os campos obrigatórios, o hash dos dados e a deduplicação com o pixel.

Notebook diante de um rack de servidores mostrando um painel de eventos de conversão confirmados

A API de Conversões da Meta (CAPI) é a forma de enviar os eventos da loja, como compra, carrinho e checkout, direto do servidor para a Meta, sem depender do navegador do cliente. Ela complementa o pixel: os dois mandam o mesmo evento com o mesmo ID, a Meta conta uma vez e recebe as vendas que o pixel perderia.

Este guia é para quem vende com anúncios no Facebook e no Instagram e quer que o Gerenciador de Anúncios receba todas as compras pagas. Ele faz parte do hub tracking e atribuição. Se o conceito de envio pelo servidor ainda é novo para você, comece pelo guia de tracking server-side e volte aqui para os detalhes da Meta.

O que é a API de Conversões da Meta?

A API de Conversões é uma interface da Meta que recebe eventos enviados por servidor. A documentação oficial descreve a API como uma conexão entre os dados de marketing do anunciante e os sistemas de otimização e medição da Meta, e diz que os eventos do servidor são processados como os eventos do pixel.

Na prática, a loja sabe quando um pedido foi pago, porque o gateway avisa. Com a API, a loja repassa esse fato para a Meta na hora: "o pedido de R$ 189,90, com estes itens, foi pago por esta pessoa". O pixel no navegador continua lá, mas deixa de ser a única fonte da informação.

Se eu já tenho o pixel, por que usar a API de Conversões?

Porque o pixel perde eventos que você não vê. Bloqueadores de anúncio impedem o script de carregar. O Safari limita a vida dos cookies criados por script. No Pix e no boleto, o pagamento é confirmado quando o cliente já saiu da página. Cada evento perdido é uma venda que o algoritmo não usa para aprender.

A Meta recomenda, nas boas práticas da API de Conversões, usar a API além do pixel e compartilhar os mesmos eventos pelas duas ferramentas, porque a API permite enviar eventos do site que o pixel pode perder. As mesmas boas práticas pedem que o evento seja enviado quando acontece, em tempo real ou em lotes próximos disso.

Quais eventos uma loja virtual deve enviar?

Os eventos padrão de e-commerce cobrem a jornada inteira. Um bom ponto de partida:

EventoQuando disparaDados que importam
PageViewQualquer página abertaURL da página
ViewContentPágina de produtoID do produto, valor e moeda
AddToCartProduto adicionado ao carrinhoID, quantidade, valor e moeda
InitiateCheckoutInício do checkoutItens, valor do carrinho e moeda
PurchasePagamento confirmadoValor pago, moeda, itens e dados do cliente

O evento que mais pesa é o Purchase. Ele precisa sair do pagamento confirmado e não da criação do pedido. Pix gerado e não pago não é compra. Se o seu checkout conta como Purchase todo pedido criado, a Meta otimiza para quem gera Pix, não para quem paga.

Quais campos são obrigatórios em um evento?

A Meta lista os campos do evento nos parâmetros de evento do servidor. Os que mais aparecem em erro de configuração:

  • event_name: o nome do evento, igual ao do pixel (Purchase, AddToCart…).
  • event_time: o momento do evento. A Meta aceita eventos de até 7 dias antes do envio; um evento mais antigo faz a requisição inteira ser recusada.
  • action_source: onde a conversão aconteceu. Para loja virtual, website.
  • event_source_url: a URL da página onde o evento aconteceu.
  • event_id: o ID que permite deduplicar com o pixel. Não é obrigatório para a API aceitar o evento, mas sem ele a compra conta duas vezes.
  • user_data: os dados do cliente, assunto da próxima seção.
  • custom_data: valor (value), moeda (currency) e itens (contents) nos eventos de comércio.

Que dados do cliente enviar e o que precisa de hash?

Para a Meta ligar a compra à pessoa que viu o anúncio, o evento leva dados do cliente. As regras estão em parâmetros de informações do cliente:

CampoO que éHash?
emE-mail, sem espaços nas pontas e em minúsculasSim, SHA-256
phTelefone só com dígitos e com código do país (55 no Brasil)Sim, SHA-256
external_idID do cliente ou do visitante na lojaRecomendado
fbpCookie do navegador criado pelo pixelNão
fbcIdentificador do clique no anúncioNão
client_ip_addressIP do clienteNunca
client_user_agentNavegador do clienteNão

Um erro comum no Brasil é o telefone sem o 55 na frente. A Meta pede o código do país para usar o número na correspondência. Outro é aplicar hash no fbp e no fbc, que devem ir abertos.

Como funciona a deduplicação com o pixel?

Com o pixel e a API mandando o mesmo evento, a Meta precisa saber que é uma compra só. A regra está na página de deduplicação de eventos do pixel e do servidor:

  • o eventID do pixel tem que ser igual ao event_id da API;
  • o nome do evento tem que ser igual nos dois (Purchase e Purchase);
  • a deduplicação vale para eventos recebidos em até 48 horas do primeiro com aquele ID;
  • quando os dois envios não diferem de forma relevante, a Meta em geral fica com o que chegou primeiro.

O jeito seguro de ter o mesmo ID nos dois lados é derivar o ID do pedido, em vez de sortear um número no navegador. Assim o servidor chega ao mesmo valor sem depender do que aconteceu na página.

O que é a qualidade da correspondência de eventos?

É uma nota que a Meta mostra no Gerenciador de Eventos para dizer o quanto os dados do cliente nos seus eventos ajudam a encontrar a pessoa certa (veja qualidade da correspondência de eventos). Segundo as boas práticas da Meta, ela só existe para eventos da web. O que mais ajuda:

  • pedir e-mail e telefone no checkout e mandar os dois no Purchase;
  • repassar o fbp e o fbc do navegador para o evento do servidor;
  • enviar o external_id de forma consistente em todos os eventos do mesmo visitante;
  • incluir IP e user agent do navegador, e não os do servidor.

Como configurar a API de Conversões na sua loja

Existem três caminhos: um servidor de tags próprio (como o GTM server-side), uma ferramenta de tracking de terceiros ou o envio nativo da plataforma da loja. A comparação está no guia de tracking server-side. Na Horsee, o envio é nativo, e o passo a passo é este:

  1. No Gerenciador de Eventos da Meta, abra o seu pixel e copie o ID do pixel.
  2. Nas configurações do pixel, na seção da API de Conversões, gere um token de acesso.
  3. Na Horsee, abra Rastreamento no menu lateral e adicione o Meta (pixel e API de Conversões).
  4. Cole o Pixel ID e o token. Se quiser acompanhar os eventos ao vivo, cole também o código de teste do Gerenciador de Eventos.
  5. Deixe o envio pelo navegador e pelo servidor ligados. O mesmo evento pelos dois canais conta uma vez.
  6. Salve e envie um evento de teste. Confira na ferramenta de eventos de teste da Meta.

A partir daí, a loja envia PageView, ViewContent, AddToCart, InitiateCheckout e Purchase sem configuração extra. A compra pelo servidor sai quando o pedido é marcado como pago, com qualquer gateway conectado, e uma rotina reenvia as compras pagas que não chegaram à Meta. O token fica guardado criptografado. Os detalhes de cada tela estão no artigo de ajuda Pixels de Rastreamento, e o que mais vem junto (automação, CRM e copiloto de dados) está em operação da Horsee.

Como testar antes de confiar nos números?

  1. Com o código de teste ativo, navegue pela loja e veja cada evento aparecer na ferramenta de eventos de teste.
  2. Faça uma compra real de valor baixo, de preferência com Pix, e feche a aba antes de pagar. A compra precisa aparecer quando o pagamento for confirmado.
  3. Abra o evento Purchase e confira valor, moeda e itens contra o pedido.
  4. Veja se o evento aparece como recebido pelo navegador e pelo servidor, e contado uma vez.
  5. Depois de alguns dias, olhe a qualidade da correspondência e os avisos de diagnóstico do Gerenciador de Eventos.
  6. Remova o código de teste quando terminar, para os eventos voltarem a valer normalmente.

Quais são os erros mais comuns com a API de Conversões?

  • Dois envios com IDs diferentes. Um app antigo de tracking e o envio nativo ao mesmo tempo. A Meta recebe duas compras e o ROAS parece melhor do que é.
  • Token vencido ou revogado. O servidor tenta e a Meta recusa, mas o pixel continua mandando, e ninguém percebe. Olhe a taxa de falha do envio pelo servidor toda semana.
  • Purchase sem valor ou com moeda errada. Loja em reais mandando USD, ou valor zero no Purchase. A otimização por valor fica cega.
  • Evento atrasado demais. Reprocessar compras de semanas atrás faz a Meta recusar a requisição, porque o limite é de 7 dias.
  • Esquecer o consentimento. Se a loja exige aceite para cookies de marketing, o envio pelo servidor precisa respeitar o mesmo aceite. Na Horsee, a opção Exibir banner de consentimento faz os pixels só dispararem depois do aceite. Ela vem desligada por padrão, e a decisão de ligar é sua, com base na LGPD e na orientação do seu jurídico.

A API de Conversões melhora o ROAS?

Ela melhora a medição, e a medição melhor costuma melhorar a otimização. Com mais compras chegando, o algoritmo aprende com mais exemplos de quem compra de verdade. Mas a API não muda a regra de atribuição da Meta: as vendas continuam creditadas pela janela e pela data do clique. Para saber quanto cada campanha vendeu em pedidos pagos, cruze os dados com UTM, como mostra o artigo Análise UTM. E quando o tracking estiver confiável, vale olhar para a outra ponta: as vendas que você perde no carrinho, assunto do guia de recuperação de carrinho abandonado.

Perguntas frequentes

O que é o event_id na API de Conversões?

É o identificador único do evento. Quando o pixel e o servidor mandam o mesmo evento com o mesmo event_id e o mesmo nome, a Meta conta uma vez só.

Posso usar só a API de Conversões, sem o pixel?

Pode, mas a Meta recomenda usar os dois e deduplicar. O pixel traz cookies e o identificador do clique que ajudam a casar o evento com a pessoa.

Como saber se a deduplicação está funcionando?

No Gerenciador de Eventos, o evento aparece como recebido pelo navegador e pelo servidor. Se o número de compras for o dobro dos pedidos pagos, os IDs não estão batendo.

Preciso de programador para configurar a API de Conversões?

Para montar um servidor de tags próprio, sim. Em plataformas com envio nativo, basta colar o ID do pixel e o token de acesso no painel da loja.

Quanto tempo depois da compra posso enviar o evento?

A Meta aceita eventos de até 7 dias antes do envio, mas recomenda mandar na hora em que acontecem. Evento mais antigo faz a requisição ser recusada.

Leia também