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
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| name | string | Sí | Nombre del anuncio, y de los niveles creados que no tengan uno. |
| status | string | No | Estado final del árbol (active o paused). Todo nace pausado y la activación es el último paso. |
| campaign | object | No | {"id": ...} usa una campaña existente; sin id, describe la que se creará. Prohibido cuando se envía adset.id. |
| adset | object | Sí | {"id": ...} usa un conjunto existente; sin id, describe el que se creará. |
| ad.format | string | Sí | image o video. |
| ad.link_url | string | Sí | URL de destino del anuncio. |
| ad.call_to_action | string | No | Botón del anuncio. Valores en GET /ads/options. |
| ad.media | array | Sí | 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_id | string | Sí | 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_id | string | No | Cuenta de Instagram que firma el anuncio. |
| campaign.google_adwords.type | string | No | Google Ads, en una campaña nueva: demand_gen o performance_max. Con ella va un budget diario. |
| ad.titles | array | No | Google 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.images | array | No | Google Ads: las imágenes, cada una con field (marketing, square, portrait, logo o landscape_logo) y asset_id. |
| campaign.tiktok_ads.objective | No | TikTok Ads, en una campaña nueva: traffic, reach o video_views. | |
| ad.body | No | Texto principal del anuncio. En TikTok Ads, hasta 100 caracteres. | |
| ad.tiktok_ads.identity_id | No | TikTok 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_id | No | TikTok Ads: el id del video de POST /ads/tiktok_ads/media, ya ready. | |
| ad.tiktok_ads.cover_image_id | No | TikTok 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.
Mira Connect aplicado a tu producto.
Pruébalo durante 15 días sin tarjeta, o cuéntale tu caso a nuestro equipo.
