Ads
Crear conversiones personalizadas en Meta Ads con la API
Dos rutas crean y listan las conversiones personalizadas de la cuenta de anuncios del cliente. Defines la conversión por la regla que la dispara, una URL o un evento del pixel, y usas el id en el conjunto de anuncios, sin implementar la API de Meta ni pasar por el app review.
La llamada
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"
}Qué puedes hacer
- Crear una conversión con POST /ads/facebook_ads/custom-conversions, por la regla rule.url_contains o rule.event.
- Elegir la categoría con event_type, como purchase, lead, add_to_cart o subscribe.
- Listar las conversiones de la cuenta con GET /ads/facebook_ads/custom-conversions.
- Usar el id en adset.facebook_ads.promoted_object.custom_conversion_id en un conjunto de anuncios.
Reglas y límites
- La conversión se define por la regla, y rule acepta exactamente una de las claves: url_contains o event. pixel_id es obligatorio.
- La regla por URL es la verificada en una cuenta real. La regla por evento existe en el contrato, pero la plataforma la rechaza en algunos pixels, y ese rechazo llega como ads_integration_error.
- event_type acepta un conjunto cerrado de valores. Fuera de él, la respuesta es 422 con la lista. Sin event_type, la plataforma recibe other.
- Idempotency-Key es obligatorio y va en el header. La conversión creada aparece en la siguiente lista sin refresh.
- La lista no está paginada (200 ítems como máximo) y tiene caché de 600 s por conexión.
Campos principales
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| name | string | Sí | Nombre de la conversión personalizada, hasta 255 caracteres. |
| pixel_id | string | Sí | El pixel detrás de la regla. Obligatorio: sin él la plataforma rechaza la creación. Viene de GET /ads/facebook_ads/pixels. |
| rule.url_contains | string | No | Se dispara cuando la dirección visitada contiene este fragmento. Usa esta clave o rule.event, nunca ambas. |
| rule.event | string | No | Se dispara cuando el pixel reporta este evento. Usa esta clave o rule.url_contains, nunca ambas. |
| event_type | string | No | La categoría de la conversión, como purchase, lead o add_to_cart. Si se omite, la plataforma recibe other. |
| Idempotency-Key | string | Sí | Header obligatorio, hasta 255 caracteres. Genéralo una vez y reenvía el mismo en cada reintento. |
Para quién
Conversión de página de agradecimiento
Tu SaaS crea una conversión con url_contains "/obrigado" para que el cliente optimice anuncios por compra completada.
Onboarding de campañas en agencia
Una agencia crea las conversiones estándar del cliente de e-commerce (compra, lead), una llamada idempotente por conversión.
Agente de IA que prepara la medición
Un agente lista las conversiones, crea la que falta y usa su id en el nuevo conjunto de anuncios.
Funciona con
Meta Ads
Preguntas frecuentes
¿Puedo crear la conversión por evento del pixel?
El contrato acepta rule.event, pero la plataforma rechaza esa forma en algunos pixels, y el rechazo llega como ads_integration_error. La regla por URL (rule.url_contains) es la verificada en una cuenta real.
¿Debo informar el pixel?
Sí. pixel_id es obligatorio, porque la plataforma rechaza la creación sin el pixel detrás de la regla. Lista los pixels en GET /ads/facebook_ads/pixels.
¿Dónde uso el id de la conversión?
En adset.facebook_ads.promoted_object.custom_conversion_id, en el conjunto de anuncios.
Mira Connect aplicado a tu producto.
Pruébalo durante 15 días sin tarjeta, o cuéntale tu caso a nuestro equipo.
