Ads

Crear un anuncio en Meta Ads, Google Ads y TikTok Ads con la API

Un solo POST /ads crea el anuncio y, si quieres, la campaña y el conjunto que lo contienen. Cada nivel usa uno existente ({"id": ...}) o describe el nuevo. Si algo falla a mitad, lo creado se deshace y nada queda gastando. En Google Ads, el mismo POST /ads crea anuncios Demand Gen y grupos de recursos Performance Max. En TikTok Ads, crea un anuncio de video en una campaña de Tráfico, Alcance o Visualizaciones de video.

La llamada

POST /api/ads?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Idempotency-Key: <unique key>

{
  "name": "Black Friday, imagem",
  "status": "active",
  "campaign": {
    "name": "Black Friday",
    "budget": {
      "amount": 50,
      "type": "daily"
    },
    "facebook_ads": {
      "objective": "traffic",
      "special_ad_categories": []
    }
  },
  "adset": {
    "name": "BR 25-45",
    "schedule": {
      "start": "2026-11-20T00:00:00-03:00"
    },
    "targeting": {
      "countries": [
        "BR"
      ],
      "age_min": 25,
      "age_max": 45
    },
    "facebook_ads": {
      "optimization_goal": "link_clicks",
      "billing_event": "impressions",
      "placements": {
        "publisher_platforms": [
          "facebook",
          "instagram"
        ]
      },
      "targeting": {
        "interests": [
          {
            "id": "6003139266461",
            "name": "Moda"
          }
        ],
        "advantage_audience": false
      }
    }
  },
  "ad": {
    "format": "image",
    "headline": "Black Friday",
    "body": "Up to 50% off",
    "link_url": "https://loja.com/bf",
    "call_to_action": "shop_now",
    "media": [
      {
        "type": "image",
        "url": "https://cdn.loja.com/bf.jpg"
      }
    ],
    "facebook_ads": {
      "page_id": "1068595869664481"
    }
  }
}

Qué puedes hacer

  • Crear campaña, conjunto y anuncio en una sola llamada.
  • Reutilizar una campaña o un conjunto existente pasando {"id": ...}.
  • Anunciar una imagen (por url o hash) o un video (por url o id, con thumbnail_url).
  • Usar dos archivos del mismo creativo, uno para el feed y otro para stories y reels, con placements.
  • Definir la página y la cuenta de Instagram que firman el anuncio en el bloque facebook_ads.
  • Pedir status active para activar el árbol al final.
  • En Google Ads, crear un anuncio Demand Gen, con campaña y grupo de anuncios nuevos o existentes.
  • En Google Ads, crear un grupo de recursos Performance Max, o sumar recursos a uno existente, con títulos, títulos largos, descripciones, imágenes, videos y logo en el bloque google_adwords.
  • En TikTok Ads, crear un anuncio de video con portada, en una campaña de Tráfico, Alcance o Visualizaciones de video y un grupo de anuncios nuevos o existentes, que corre como una de las cuentas de TikTok de GET /ads/tiktok_ads/identities.

Reglas y límites

  • Todo se crea pausado. El status pedido se aplica en el último paso, cuando todo el árbol ya existe.
  • Idempotency-Key es obligatorio en el header. Repetir con la misma clave devuelve 200 con Idempotent-Replay: true.
  • Si un paso de creación falla, lo creado se deshace en orden inverso; lo que no se pudo deshacer viene en created. Repetir con la misma clave retoma donde quedó.
  • En la activación solo se activan los niveles que creó la propia llamada; los niveles referenciados por id no se tocan.
  • Un video aún en procesamiento responde 409 ads_video_not_ready. Repite con la misma clave: el video y los niveles ya creados se reutilizan.
  • campaign está prohibido cuando se envía adset.id. La página debe ser de la cuenta de la conexión.
  • La respuesta es síncrona: 201 con el resultado.
  • En Google Ads, imágenes, videos y logos entran por el asset_id de POST /ads/google_adwords/media. Una campaña nueva lleva budget diario y google_adwords.type: demand_gen o performance_max.
  • Performance Max no tiene anuncios: el grupo de recursos lleva el creativo, así que la respuesta es el conjunto. Una campaña que no sea Demand Gen ni Performance Max responde 422 ads_unsupported_operation.
  • En TikTok Ads, el anuncio es un video: ad.body (hasta 100 caracteres), link_url, call_to_action y, en el bloque tiktok_ads, identity_id, identity_type, video_id y cover_image_id, estos dos de POST /ads/tiktok_ads/media. La campaña nueva lleva tiktok_ads.objective (traffic, reach o video_views) y, si quieres, budget, que ella reparte entre los grupos (CBO); sin él, el grupo nuevo lleva budget diario o total. El grupo nuevo lleva también targeting.countries o tiktok_ads.location_ids. Antes de la primera escritura, todo se verifica en la cuenta solo con lecturas.

Campos principales

CampoTipoObligatorioDescripción
namestringSíNombre del anuncio, y de los niveles creados que no tengan uno.
statusstringNoEstado final del árbol (active o paused). Todo nace pausado y la activación es el último paso.
campaignobjectNo{"id": ...} usa una campaña existente; sin id, describe la que se creará. Prohibido cuando se envía adset.id.
adsetobjectSí{"id": ...} usa un conjunto existente; sin id, describe el que se creará.
ad.formatstringSíimage o video.
ad.link_urlstringSíURL de destino del anuncio.
ad.call_to_actionstringNoBotón del anuncio. Valores en GET /ads/options.
ad.mediaarraySíUn archivo para todas las ubicaciones, o dos (versión feed y versión story) con placements. Imagen por url o hash; video por url o id. Solo en Meta Ads.
ad.facebook_ads.page_idstringSíPágina que firma el anuncio. Debe ser una página de la cuenta de la conexión. Solo en Meta Ads.
ad.facebook_ads.instagram_account_idstringNoCuenta de Instagram que firma el anuncio.
campaign.google_adwords.typestringNoGoogle Ads, en una campaña nueva: demand_gen o performance_max. Con ella va un budget diario.
ad.titlesarrayNoGoogle Ads: los títulos. Demand Gen, de 1 a 5 de hasta 40 caracteres; Performance Max, de 3 a 15 de hasta 30.
ad.google_adwords.imagesarrayNoGoogle Ads: las imágenes, cada una con field (marketing, square, portrait, logo o landscape_logo) y asset_id.
campaign.tiktok_ads.objectiveNoTikTok Ads, en una campaña nueva: traffic, reach o video_views.
ad.bodyNoTexto principal del anuncio. En TikTok Ads, hasta 100 caracteres.
ad.tiktok_ads.identity_idNoTikTok Ads: la cuenta de TikTok que firma el anuncio, de GET /ads/tiktok_ads/identities, con su type en identity_type.
ad.tiktok_ads.video_idNoTikTok Ads: el id del video de POST /ads/tiktok_ads/media, ya ready.
ad.tiktok_ads.cover_image_idNoTikTok Ads: el image_id de la portada, de POST /ads/tiktok_ads/media, en la proporción del video.

Para quién

  • Creador de anuncios dentro de tu producto

    El cliente elige creativo, texto y público y tú publicas el anuncio completo en su cuenta, sin armar el flujo OAuth de Meta.

  • Agencia que sube creativos a escala

    Reutiliza una campaña y un conjunto existentes y crea decenas de anuncios nuevos cambiando solo la media y el texto.

  • Agente de IA que genera creativos

    El agente crea el anuncio pausado, valida antes con POST /ads/validate y solo activa tras la aprobación.

Funciona con

  • Meta Ads
  • Google Ads
  • TikTok Ads

Preguntas frecuentes

¿El anuncio sale al aire apenas termina la llamada?

Solo si envías status active. Aun así, todo se crea pausado y la activación es el último paso.

¿Y si la llamada falla a mitad?

Lo ya creado se deshace y nada queda gastando. Lo que no se pudo deshacer viene en created. Repitiendo con el mismo Idempotency-Key, retoma donde quedó.

¿Funciona en Google Ads y TikTok Ads?

Sí, en campañas Demand Gen y Performance Max. El cuerpo es el mismo POST /ads, con los campos de Google en el bloque google_adwords. En Performance Max la respuesta es el grupo de recursos, porque no tiene anuncios. En TikTok Ads, en campañas de Tráfico, Alcance y Visualizaciones de video con un anuncio de video, con los campos de TikTok en el bloque tiktok_ads.

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.