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.

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:
| Evento | Quando dispara | Dados que importam |
|---|---|---|
| PageView | Qualquer página aberta | URL da página |
| ViewContent | Página de produto | ID do produto, valor e moeda |
| AddToCart | Produto adicionado ao carrinho | ID, quantidade, valor e moeda |
| InitiateCheckout | Início do checkout | Itens, valor do carrinho e moeda |
| Purchase | Pagamento confirmado | Valor 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:
| Campo | O que é | Hash? |
|---|---|---|
em | E-mail, sem espaços nas pontas e em minúsculas | Sim, SHA-256 |
ph | Telefone só com dígitos e com código do país (55 no Brasil) | Sim, SHA-256 |
external_id | ID do cliente ou do visitante na loja | Recomendado |
fbp | Cookie do navegador criado pelo pixel | Não |
fbc | Identificador do clique no anúncio | Não |
client_ip_address | IP do cliente | Nunca |
client_user_agent | Navegador do cliente | Nã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
eventIDdo pixel tem que ser igual aoevent_idda 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
fbpe ofbcdo navegador para o evento do servidor; - enviar o
external_idde 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:
- No Gerenciador de Eventos da Meta, abra o seu pixel e copie o ID do pixel.
- Nas configurações do pixel, na seção da API de Conversões, gere um token de acesso.
- Na Horsee, abra Rastreamento no menu lateral e adicione o Meta (pixel e API de Conversões).
- 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.
- Deixe o envio pelo navegador e pelo servidor ligados. O mesmo evento pelos dois canais conta uma vez.
- 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?
- Com o código de teste ativo, navegue pela loja e veja cada evento aparecer na ferramenta de eventos de teste.
- 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.
- Abra o evento Purchase e confira valor, moeda e itens contra o pedido.
- Veja se o evento aparece como recebido pelo navegador e pelo servidor, e contado uma vez.
- Depois de alguns dias, olhe a qualidade da correspondência e os avisos de diagnóstico do Gerenciador de Eventos.
- 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
Tracking e atribuiçãoTracking server-side: o que é e por que o seu pixel perde vendas
O pixel do navegador perde compras por bloqueador, cookie curto e pagamento confirmado depois. Veja como o envio pelo servidor fecha essa lacuna sem contar venda duas vezes.
