Ads
Crear un conjunto o grupo de anuncios en Meta, Google y TikTok Ads con la API
Crea el conjunto dentro de una campaña existente, en la cuenta que el cliente conectó: público, agenda, ubicaciones, meta de optimización y puja. Los campos comunes a cualquier plataforma van arriba y lo específico de Meta va en el bloque facebook_ads. Sin revisión de app y sin manejar tokens. En Google Ads, la misma ruta crea un grupo de anuncios en una campaña Demand Gen. En TikTok Ads, crea un grupo de anuncios en una campaña de Tráfico, Alcance o Visualizaciones de video, con presupuesto diario o total, ubicación, público y agenda.
La llamada
POST /api/ads/adsets?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Idempotency-Key: <unique key>
{
"campaign_id": "120250000000000001",
"name": "BR 25-45",
"budget": {
"amount": 20,
"type": "daily"
},
"targeting": {
"countries": [
"BR"
],
"age_min": 25,
"age_max": 45
},
"facebook_ads": {
"optimization_goal": "link_clicks",
"billing_event": "impressions"
}
}Qué puedes hacer
- Segmentar por países, edad (age_min y age_max) y géneros.
- Segmentar por intereses y públicos personalizados, incluidas exclusiones, en facebook_ads.targeting.
- Definir la agenda con schedule.start y schedule.end.
- Elegir ubicaciones con facebook_ads.placements.
- Elegir la puja con bid_strategy (lowest_cost, bid_cap, cost_cap) y bid_amount.
- Enviar promoted_object, destination_type y attribution_spec al crear.
- En Google Ads, crear un grupo de anuncios en una campaña Demand Gen solo con campaign_id, name y status.
- En TikTok Ads, crear un grupo de anuncios en una campaña de Tráfico, Alcance o Visualizaciones de video, con ubicación, edad, género, públicos, agenda y meta de optimización.
Reglas y límites
- Idempotency-Key es obligatorio en el header; repetir con la misma clave devuelve 200 con Idempotent-Replay: true.
- Sin status, el conjunto nace pausado.
- El presupuesto va en la campaña (CBO) o en el conjunto (ABO), nunca en los dos. Presupuesto en un conjunto de campaña CBO responde 409 budget_level_mismatch.
- budget.type lifetime exige schedule.end.
- facebook_ads.optimization_goal y facebook_ads.billing_event son obligatorios; los valores aceptados están en GET /ads/options.
- promoted_object (píxel, página o conversión personalizada) debe pertenecer a la cuenta de la conexión y vale solo al crear.
- bid_amount exige bid_strategy.
- En Google Ads, budget, schedule, targeting y facebook_ads se rechazan: el presupuesto va en la campaña. En una campaña Performance Max, la ruta responde 422 ads_unsupported_operation, y el grupo de recursos se crea con sus recursos por POST /ads.
- En TikTok Ads, targeting.countries o tiktok_ads.location_ids es obligatorio, y facebook_ads se rechaza. Si la campaña reparte el presupuesto (CBO), el grupo no lleva budget; sin CBO, budget es obligatorio, diario o total, y el total exige schedule.end. En una campaña con CBO, budget en el grupo responde 409 budget_level_mismatch. Edad, género, tiktok_ads.audience_ids y schedule son opcionales; sin schedule.start, empieza ahora. La meta viene de tiktok_ads.optimization_goal y la puja de tiktok_ads.bid_strategy (lowest_cost o cost_cap con bid_amount); tiktok_ads.frequency vale solo en Alcance. El grupo corre solo en la ubicación TikTok. En una campaña de otro objetivo, la ruta responde 422 ads_unsupported_operation.
Campos principales
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| campaign_id | string | Sí | La campaña, por su id o por el uuid de Connect. |
| name | string | Sí | Nombre del conjunto de anuncios. |
| budget.amount | number | No | Presupuesto del conjunto (ABO), en la moneda de la cuenta. Solo vale si la campaña no tiene presupuesto. |
| schedule.end | string | No | Fecha de fin. Obligatoria cuando budget.type es lifetime. |
| targeting.countries | array | Sí | Países del público, por ejemplo ["BR"]. El resto de la segmentación va en facebook_ads.targeting. |
| facebook_ads.optimization_goal | string | Sí | Meta de optimización. Obligatorio al crear; valores en GET /ads/options. Solo en Meta Ads. |
| facebook_ads.billing_event | string | Sí | Evento de facturación. Obligatorio al crear. Solo en Meta Ads. |
| facebook_ads.bid_strategy | string | No | lowest_cost, bid_cap o cost_cap. |
| facebook_ads.bid_amount | number | No | Valor de la puja. Exige bid_strategy. |
| facebook_ads.targeting.interests | array | No | Intereses del público, con id y name. |
| tiktok_ads.location_ids | No | En TikTok Ads: ids de ubicación de TikTok (estados y regiones), de GET /ads/targeting/search (type geo). En la respuesta, los países del grupo también vuelven aquí, como ids de ubicación. |
Para quién
Constructor de campañas dentro del SaaS
Tu producto arma el público (país, edad, intereses) en su propia pantalla y crea el conjunto en la cuenta del cliente con una llamada.
Pruebas A/B de público
Crea varios conjuntos en la misma campaña, cambiando solo la segmentación, y compara el rendimiento después.
Agente de IA que sugiere públicos
El agente propone la segmentación, crea el conjunto pausado y lo entrega para aprobación antes de activar.
Funciona con
Meta Ads
Google Ads
TikTok Ads
Preguntas frecuentes
¿Debo crear la campaña antes?
Para esta ruta sí: campaign_id es obligatorio. Para crear campaña, conjunto y anuncio de una vez, usa POST /ads.
¿Dónde pongo el presupuesto?
En el conjunto solo si la campaña no tiene presupuesto (ABO). Si la campaña tiene budget (CBO), enviar budget en el conjunto responde 409 budget_level_mismatch.
¿Cómo averiguo los valores válidos de optimización y facturación?
En GET /ads/options?integration_slug=facebook_ads. Un valor inválido responde 422 validation_error con supported_values.
Mira Connect aplicado a tu producto.
Pruébalo durante 15 días sin tarjeta, o cuéntale tu caso a nuestro equipo.
