CAPI — Conversions API
Como ativar a Conversions API nativa, deduplicar com o pixel via event_id, reportar reembolsos e validar eventos no Test Events de cada ad network.
Envie suas vendas direto para Meta, Google e TikTok pelo servidor do Synchro Hub, recuperando atribuição perdida pelo navegador e melhorando a otimização da inteligência artificial dos anúncios.
Visão geral
A Conversions API (CAPI) é o canal servidor-a-servidor que Meta, Google e TikTok criaram para receber eventos de conversão direto da sua infraestrutura — sem depender de cookies, pixel no navegador ou consentimento de cada visitante.
Quando você ativa CAPI no Synchro Hub:
- Toda venda aprovada vira automaticamente um evento de conversão enviado ao ad network correspondente.
- Reembolsos e estornos também são reportados, mantendo a base de otimização honesta.
- Os dados pessoais (e-mail, telefone, etc.) são hasheados em SHA-256 antes do envio. O ad network nunca recebe PII em claro.
- Cada evento tem identificador único (
event_id), evitando duplicação caso o pixel do navegador também tenha registrado.
Tempo estimado: 5 minutos por integração de anúncio.
Importante — limitação conhecida: o CAPI só funciona em contas de anúncios conectadas nativamente (login direto Meta/Google/TikTok no Synchro Hub). Contas conectadas via Windsor.ai não suportam este recurso, porque o Windsor é um agregador de leitura — ele não disponibiliza as credenciais necessárias para envio de eventos. Se sua conta ADS aparece marcada como “via Windsor”, reconecte-a diretamente em Integrações → Anúncios para habilitar o CAPI. Esta restrição será sinalizada na própria UI em uma versão futura.
Pré-requisitos
- Plano com CAPI habilitado (Pro ou superior).
- Conta de anúncios conectada nativamente no Synchro Hub (Meta Ads, Google Ads ou TikTok Ads via OAuth direto). Contas via Windsor não servem para este recurso (veja a observação acima).
- No caso da Meta: ter um Pixel configurado no Events Manager.
- No caso do Google: ter uma Conversion Action criada no Google Ads.
- No caso do TikTok: ter um Pixel ou Events API ativos no TikTok Ads Manager.
Passo 1 — Acessar a integração de anúncios
- No menu lateral, abra Integrações → Anúncios.
- Localize o card da conta em que você quer ativar CAPI.
Se o card mostra a marca “via Windsor”, este recurso não estará disponível. Conecte a mesma conta diretamente (login OAuth no Synchro) para liberar o CAPI.
Passo 2 — Habilitar o CAPI
- Clique em Configurar CAPI no card da conta.
- Preencha os campos exigidos pelo ad network:
- Meta: Pixel ID e (opcional) Test Event Code para validação.
- Google: Conversion Action ID.
- TikTok: Pixel Code (ou Event Source ID).
- Clique em Ativar.
A partir desse momento, todas as vendas novas que entrarem no Synchro são automaticamente reportadas para a plataforma escolhida.
Passo 3 — Validar do lado do ad network
Cada plataforma tem uma tela própria pra você confirmar que os eventos estão chegando:
- Meta: Events Manager → seu Pixel → aba Test Events (use o Test Event Code do passo anterior). Eventos aparecem em segundos.
- Google: Google Ads → Tools → Conversions → seu Conversion Action → aba Diagnostics. Pode levar até 3 horas pra refletir.
- TikTok: Events Manager → seu Pixel → aba Test Event.
Dica: gere uma venda de teste (cupom 100%) para validar fim a fim. Em até 1 minuto o evento deve aparecer no painel do ad network.
Passo 4 — Acompanhar o histórico de envios
No próprio painel de Vendas do Synchro, abra qualquer venda e clique em Ver postbacks CAPI →.
Você vê:
- Para qual ad network o evento foi enviado.
- Status (enviado, falha 4xx, falha 5xx exausta, ignorado).
- Quantas tentativas foram feitas.
- Latência da resposta do ad network.
- Botão de Reenviar caso queira forçar uma nova tentativa.
O Synchro tenta novamente automaticamente em caso de erro temporário (5xx, timeout). Erros de cliente (4xx — credencial errada, payload inválido) são marcados como falha definitiva e listados pra você corrigir a configuração.
Verificação
- Faça uma venda de teste em qualquer plataforma conectada (cupom 100% ou compra real).
- Aguarde até 1 minuto.
- Abra a venda em Vendas → detalhe → Ver postbacks CAPI. Status deve estar Enviado.
- Confirme do lado do ad network (Test Events da Meta, Diagnostics do Google ou Events Manager do TikTok).
Solução de problemas
| Sintoma | O que fazer |
|---|---|
| Toggle “Configurar CAPI” desabilitado | A conta foi conectada via Windsor — reconecte nativamente em Integrações → Anúncios para liberar. |
| ”Plano não inclui CAPI” | Faça upgrade para Pro ou superior em Configurações → Plano. |
| Eventos enviados, mas não aparecem na Meta | Confirme que o Pixel ID está correto e que o Test Event Code (se usado) está válido. Eventos sem Test Event Code podem demorar até 20 minutos. |
| Falha 4xx recorrente | Credenciais do ad network podem ter expirado. Tente reconectar a integração de anúncios e gere uma venda nova. |
| Token expirado / “Authentication error” | O Synchro tem auto-refresh do token, mas se o refresh falhou (autorização revogada do lado da Meta/Google/TikTok), você precisa reconectar a conta. |
| Evento duplicado no ad network | Não acontece se você usar o event_id do Synchro. Se está duplicando, provavelmente o pixel do navegador está enviando com um ID diferente — alinhe os dois. |
Perguntas frequentes
Preciso desativar o pixel do navegador?
Não. O recomendado é manter os dois (pixel + CAPI) — Meta, Google e TikTok deduplicam pelo event_id. Ter os dois aumenta a robustez: se o navegador bloqueia o pixel, o CAPI cobre; se a CAPI tem latência, o pixel cobriu antes.
Os dados pessoais são enviados em claro para a Meta/Google/TikTok? Não. E-mail, telefone, nome e CPF são hasheados em SHA-256 no servidor antes do envio. O ad network usa o hash para casar com o usuário internamente, mas nunca recebe o dado em claro.
Funciona pra vendas antigas (retroativo)? A janela útil para CAPI é tipicamente de 7 dias. Eventos mais antigos são aceitos mas têm peso reduzido na otimização. O Synchro envia automaticamente vendas novas; reenvio retroativo manual está no roadmap.
Por que isso vale a pena? Sem CAPI, o ad network depende de pixel no navegador — bloqueado por iOS, ad blockers, modo anônimo, ITP do Safari etc. Com CAPI, a inteligência artificial do ad network recebe sinal de conversão íntegro e otimiza melhor as campanhas. Anunciantes que ativam CAPI consistentemente reportam queda de CPA entre 5–20% nas semanas seguintes.
E se eu mudar de Pixel ou de Conversion Action depois? Edite a configuração CAPI no card da integração e salve. Eventos novos passam a ser enviados pra nova configuração. Eventos antigos não são reenviados automaticamente.