Ads

Criar conversões personalizadas no Meta Ads pela API

Duas rotas criam e listam as conversões personalizadas da conta de anúncios do cliente. Você define a conversão pela regra que a dispara, uma URL ou um evento do pixel, e usa o id no conjunto de anúncios, sem implementar a API da Meta nem passar pelo app review.

A chamada

POST /api/ads/facebook_ads/custom-conversions?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Idempotency-Key: <unique key>

{
  "name": "Purchase completed",
  "pixel_id": "900000000000001",
  "rule": {
    "url_contains": "/obrigado"
  },
  "event_type": "purchase"
}

O que dá para fazer

  • Criar uma conversão com POST /ads/facebook_ads/custom-conversions, pela regra rule.url_contains ou rule.event.
  • Escolher a categoria com event_type, como purchase, lead, add_to_cart ou subscribe.
  • Listar as conversões da conta com GET /ads/facebook_ads/custom-conversions.
  • Usar o id em adset.facebook_ads.promoted_object.custom_conversion_id num conjunto de anúncios.

Regras e limites

  • A conversão é definida pela regra, e rule aceita exatamente uma das chaves: url_contains ou event. pixel_id é obrigatório.
  • A regra por URL é a verificada numa conta real. A regra por evento existe no contrato, mas a plataforma a recusa em alguns pixels, e essa recusa chega como ads_integration_error.
  • event_type aceita um conjunto fechado de valores. Fora dele, a resposta é 422 com a lista. Sem event_type, a plataforma recebe other.
  • O Idempotency-Key é obrigatório e vai no header. A conversão criada aparece na listagem seguinte sem refresh.
  • A listagem não é paginada (200 itens no máximo) e tem cache de 600 s por conexão.

Campos principais

CampoTipoObrigatórioDescrição
namestringSimNome da conversão personalizada, até 255 caracteres.
pixel_idstringSimO pixel por trás da regra. Obrigatório: sem ele a plataforma recusa a criação. Vem de GET /ads/facebook_ads/pixels.
rule.url_containsstringNãoDispara quando o endereço visitado contém este trecho. Use esta chave ou rule.event, nunca as duas.
rule.eventstringNãoDispara quando o pixel reporta este evento. Use esta chave ou rule.url_contains, nunca as duas.
event_typestringNãoA categoria da conversão, como purchase, lead ou add_to_cart. Sem ele, a plataforma recebe other.
Idempotency-KeystringSimHeader obrigatório, até 255 caracteres. Gere uma vez e reenvie a mesma em cada nova tentativa.

Para quem

  • Conversão de página de obrigado

    Seu SaaS cria uma conversão com url_contains "/obrigado" para o cliente otimizar anúncios pela compra concluída.

  • Onboarding de campanhas em agência

    Uma agência cria as conversões padrão do cliente de e-commerce (compra, lead) numa chamada por conversão, de forma idempotente.

  • Agente de IA que prepara a medição

    Um agente lista as conversões, cria a que falta e usa o id no conjunto de anúncios novo.

Funciona com

  • Meta Ads

Perguntas frequentes

Posso criar a conversão por evento do pixel?

O contrato aceita rule.event, mas a plataforma recusa essa forma em alguns pixels, e a recusa chega como ads_integration_error. A regra por URL (rule.url_contains) é a verificada numa conta real.

Preciso informar o pixel?

Sim. pixel_id é obrigatório, porque a plataforma recusa a criação sem o pixel por trás da regra. Liste os pixels em GET /ads/facebook_ads/pixels.

Onde uso o id da conversão?

Em adset.facebook_ads.promoted_object.custom_conversion_id, no conjunto de anúncios.

Relacionadas

Ver tudo que dá para fazer em Ads

Veja o Connect aplicado ao seu produto.

Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.