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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| name | string | Sim | Nome da conversão personalizada, até 255 caracteres. |
| pixel_id | string | Sim | O 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_contains | string | Não | Dispara quando o endereço visitado contém este trecho. Use esta chave ou rule.event, nunca as duas. |
| rule.event | string | Não | Dispara quando o pixel reporta este evento. Use esta chave ou rule.url_contains, nunca as duas. |
| event_type | string | Não | A categoria da conversão, como purchase, lead ou add_to_cart. Sem ele, a plataforma recebe other. |
| Idempotency-Key | string | Sim | Header 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.
Veja o Connect aplicado ao seu produto.
Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.
