Ads
Crear una campaña en Meta Ads, Google Ads y TikTok Ads con la API
Una llamada crea la campaña en la cuenta de anuncios que el cliente conectó, sin implementar la API de Meta ni pasar por la revisión de app. Describes objetivo y presupuesto en un vocabulario único y Connect se encarga del token y de la traducción. La campaña nace pausada, así que nada gasta hasta que la actives. En Google Ads, la misma ruta crea campañas Demand Gen y Performance Max, con presupuesto diario y estrategia de puja. En TikTok Ads, la ruta crea campañas de Tráfico, Alcance y Visualizaciones de video, con presupuesto diario o total opcional: con él, la campaña reparte el presupuesto entre los grupos (CBO); sin él, cada grupo de anuncios lleva el suyo.
La llamada
POST /api/ads/campaigns?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Idempotency-Key: <unique key>
{
"name": "Black Friday",
"budget": {
"amount": 50,
"type": "daily"
},
"facebook_ads": {
"objective": "traffic",
"special_ad_categories": []
}
}Qué puedes hacer
- Elegir el objetivo: awareness, traffic, engagement, leads, app_promotion o sales.
- Definir el presupuesto en la campaña (CBO) o dejarlo para cada conjunto (ABO).
- Usar presupuesto daily o lifetime, en la moneda de la cuenta del cliente.
- Enviar special_ad_categories para crédito, empleo, vivienda y política.
- Definir un límite de gasto con facebook_ads.spend_cap.
- Consultar los valores aceptados en GET /ads/options?integration_slug=facebook_ads.
- En Google Ads, crear una campaña Demand Gen o Performance Max con google_adwords.type y presupuesto diario propio.
- En Google Ads, elegir la puja en google_adwords.bidding: maximize_conversions, con target_cpa opcional, o maximize_conversion_value, con target_roas opcional.
- En Google Ads, listar las acciones de conversión activas de la cuenta con GET /ads/google_adwords/conversion-actions; la puja optimiza por las que tienen primary_for_goal.
- En TikTok Ads, crear una campaña de Tráfico, Alcance o Visualizaciones de video con tiktok_ads.objective: traffic, reach o video_views.
Reglas y límites
- Sin status, la campaña nace pausada.
- Idempotency-Key es obligatorio en el header. Repetir la llamada con la misma clave y el mismo cuerpo devuelve 200 con Idempotent-Replay: true, sin crear otra campaña.
- El presupuesto va en la campaña (CBO) o en cada conjunto (ABO), nunca en los dos. No existe un campo level: el nivel es donde está el budget.
- budget.amount va en la moneda de la cuenta, nunca en centavos.
- facebook_ads.objective es obligatorio y no cambia después de crear.
- La respuesta es síncrona: 201 con la campaña creada. Si la clave ya se usó con otro cuerpo, responde 422 idempotency_key_reused.
- En Google Ads, budget es obligatorio y solo daily: el presupuesto va siempre en la campaña. facebook_ads se rechaza.
- En TikTok Ads, tiktok_ads.objective es traffic, reach o video_views, y budget es opcional en la campaña, diario o total: con él, la campaña reparte el presupuesto entre los grupos (CBO), que no llevan budget; el total exige schedule.end en el grupo. facebook_ads también se rechaza.
Campos principales
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| name | string | Sí | Nombre de la campaña. |
| status | string | No | active o paused. Sin el campo, la campaña nace pausada. |
| budget.amount | number | Sí | Valor en la moneda de la cuenta de anuncios, nunca en centavos. Enviar el budget aquí hace la campaña CBO. |
| budget.type | string | No | daily o lifetime. lifetime exige schedule.end en el conjunto. |
| facebook_ads.objective | string | Sí | awareness, traffic, engagement, leads, app_promotion o sales. Obligatorio al crear y no cambia después. Solo en Meta Ads. |
| facebook_ads.special_ad_categories | array | No | Obligatorio para crédito, empleo, vivienda y política. |
| facebook_ads.spend_cap | number | No | Límite de gasto de la campaña, en la moneda de la cuenta. null lo quita. |
| google_adwords.type | string | No | Google Ads: demand_gen o performance_max. Obligatorio en Google. |
| google_adwords.bidding | object | No | Google Ads: strategy (maximize_conversions, por defecto, o maximize_conversion_value) y, opcional, target_cpa o target_roas (4 es 400%). |
| tiktok_ads.objective | No | TikTok Ads: traffic, reach o video_views. Obligatorio en TikTok; el budget de la campaña es opcional (CBO). |
Para quién
Plataforma de anuncios para pymes
El cliente final completa objetivo y presupuesto en tu producto y tú creas la campaña en su cuenta, sin armar un flujo OAuth con Meta.
Agencia con panel propio
Crea campañas estandarizadas para varios clientes desde una plantilla, cambiando solo nombre, objetivo y presupuesto.
Agente de IA de medios pagos
El agente lee el vocabulario en GET /ads/options, arma la campaña y la deja pausada para que una persona la revise antes de activar.
Funciona con
Meta Ads
Google Ads
TikTok Ads
Preguntas frecuentes
¿La campaña empieza a gastar apenas se crea?
No. Sin status nace pausada. La activas cuando quieras con PATCH /ads/campaigns/{id} y status active.
¿Puedo repetir la llamada sin crear una campaña duplicada?
Sí. Envía siempre el mismo Idempotency-Key. Si la primera llamada funcionó, la repetición devuelve la misma respuesta con Idempotent-Replay: true.
¿El presupuesto va en la campaña o en el conjunto?
En uno de los dos. Con budget en la campaña es CBO; sin él, cada conjunto lleva el suyo (ABO). Enviarlo al nivel equivocado responde 409 budget_level_mismatch.
Mira Connect aplicado a tu producto.
Pruébalo durante 15 días sin tarjeta, o cuéntale tu caso a nuestro equipo.
