Como configurar CAPI (Conversions API) server-side em 2026

Tutorial prático para subir Conversions API server-side conectada ao Pixel, com deduplicação correta, eventos avançados e validação no Events Manager.

:::tldr CAPI server-side recupera 30-40% dos eventos perdidos por bloqueador, iOS e ITP. Mas só funciona com deduplicação correta (event_id + event_name + event_time idênticos entre Pixel e CAPI). Errar dedup = inflação de conversão e ruído no algoritmo. :::

Pixel sozinho em 2026 é instalar metade do sensor. Subir CAPI server-side é o que separa operação amadora de operação que escala mantendo ROAS.

Por que CAPI server-side

| Fonte | Perde para... | Recupera com CAPI | |---|---|---| | Bloqueador (uBlock, Brave) | ~15% | Sim | | iOS 14+ App Tracking | ~20% | Parcial | | Safari ITP | ~10% | Sim | | Conexão instável | ~5% | Sim |

Pré-requisitos

BM verificada com pixel/dataset ativo.
Domínio verificado em Segurança da marca.
Servidor capaz de POST HTTPS (Node, PHP, Edge function, etc.).
Access token de longa duração gerado no Events Manager.

Passo a passo

1. Gerar Access Token

\Events Manager → seu dataset → Configurações → Gerar token de acesso\. Guarde no servidor (variável de ambiente, nunca no frontend).

2. Endpoint do Meta

\POST https://graph.facebook.com/v19.0/{dataset_id}/events?access_token={TOKEN}\

3. Payload mínimo (Purchase)

\\\json { "data": [{ "event_name": "Purchase", "event_time": 1716156000, "event_id": "ord_abc123", "action_source": "website", "event_source_url": "https://loja.com/obrigado", "user_data": { "em": ["sha256_email"], "ph": ["sha256_telefone"], "client_ip_address": "189.x.x.x", "client_user_agent": "Mozilla/5.0..." }, "custom_data": { "value": 349.90, "currency": "BRL", "content_ids": ["sku-1234"] } }] } \\\

4. Deduplicação correta

O mesmo \event_id\ deve sair do Pixel e do CAPI para o mesmo evento.
\event_name\ e \event_time\ idênticos.
O Meta junta os dois e conta como 1.

Quero CAPI configurada e deduplicada na minha BM

5. Hash dos dados pessoais

Sempre SHA-256.
Lowercase + trim antes do hash.
E-mail: \crypto.createHash("sha256").update(email.trim().toLowerCase()).digest("hex")\.

6. Validação no Events Manager

\Test Events\ → cole o test code → dispara evento → confirma recebido.
\Visão geral → Diagnostics\ mostra match quality (>7 = bom, >8.5 = excelente).

:::callout type=warning Não enviar IP + user_agent reduz match quality drasticamente. E sem match quality bom, o algoritmo otimiza pior — você paga CAPI sem colher ROI. :::

Eventos prioritários

| Evento | event_id sugerido | Quando enviar | |---|---|---| | PageView | uuid por carregamento | Toda navegação | | ViewContent | content_id + uuid | Página de produto | | Lead | lead_id do CRM | Form enviado | | InitiateCheckout | cart_id | Início checkout | | AddPaymentInfo | cart_id | Cartão preenchido | | Purchase | order_id | Pagamento aprovado |

Erros comuns

Hash em UPPERCASE → quebra match.
\event_time\ em milissegundos (Meta espera segundos).
Enviar CAPI sem Pixel correspondente → conversões duplicadas.
Esquecer \fbp\ e \fbc\ (cookies do navegador) no \user_data\.

> Próximo nível: integrar CAPI com migração de pixel sem perder aprendizado.

Este artigo faz parte do pilar Escala & Performance

Veja o guia completo em Escala e performance: warm-up, Trust Score e CAPI. Consulte também Ver serviço de aquecimento.