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

CampoTipoObligatorioDescripción
namestringSíNombre de la conversión personalizada, hasta 255 caracteres.
pixel_idstringSí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_containsstringNoSe dispara cuando la dirección visitada contiene este fragmento. Usa esta clave o rule.event, nunca ambas.
rule.eventstringNoSe dispara cuando el pixel reporta este evento. Usa esta clave o rule.url_contains, nunca ambas.
event_typestringNoLa categoría de la conversión, como purchase, lead o add_to_cart. Si se omite, la plataforma recibe other.
Idempotency-KeystringSí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.

Relacionadas

Ver todo lo que puedes hacer con Ads

Mira Connect aplicado a tu producto.

Pruébalo durante 15 días sin tarjeta, o cuéntale tu caso a nuestro equipo.