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

CampoTipoObligatorioDescripción
campaign_idstringSíLa campaña, por su id o por el uuid de Connect.
namestringSíNombre del conjunto de anuncios.
budget.amountnumberNoPresupuesto del conjunto (ABO), en la moneda de la cuenta. Solo vale si la campaña no tiene presupuesto.
schedule.endstringNoFecha de fin. Obligatoria cuando budget.type es lifetime.
targeting.countriesarraySíPaíses del público, por ejemplo ["BR"]. El resto de la segmentación va en facebook_ads.targeting.
facebook_ads.optimization_goalstringSíMeta de optimización. Obligatorio al crear; valores en GET /ads/options. Solo en Meta Ads.
facebook_ads.billing_eventstringSíEvento de facturación. Obligatorio al crear. Solo en Meta Ads.
facebook_ads.bid_strategystringNolowest_cost, bid_cap o cost_cap.
facebook_ads.bid_amountnumberNoValor de la puja. Exige bid_strategy.
facebook_ads.targeting.interestsarrayNoIntereses del público, con id y name.
tiktok_ads.location_idsNoEn 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.

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.