Ads
Listar campañas, conjuntos y anuncios de Meta Ads con la API
Tres rutas GET listan las campañas, conjuntos y anuncios de la cuenta de anuncios de un cliente, con estado, estado efectivo, problemas y presupuesto. Eliges leer lo que Connect guarda o la cuenta en vivo, sin implementar OAuth ni pasar por el app review de Meta.
La llamada
GET /api/ads/campaigns?customer_integration=<connection uuid>&source=external&status=active&per_page=50 Authorization: Bearer <merchant token> x-customer-token: <customer token>
Qué puedes hacer
- Listar campañas, conjuntos de anuncios y anuncios con GET /ads/campaigns, /ads/adsets y /ads.
- Leer la cuenta en vivo con source=external, incluso lo creado fuera de Connect.
- Filtrar por status (active o paused) y, con source=connect, por effective_status, como pending_review o disapproved.
- Ver en issues por qué la plataforma retiene un objeto, como un rechazo o un problema de entrega.
- Filtrar conjuntos y anuncios por campaign_id y anuncios por adset_id, y paginar con page y per_page.
Reglas y límites
- El valor por defecto es source=connect: lo que Connect creó o ya escribió en la cuenta, sin llamar a la plataforma. Una cuenta con campañas antiguas lista vacío hasta la primera escritura por Connect.
- Para ver toda la cuenta, usa source=external. La lectura en vivo tiene caché de 120 s y refresh=true lo ignora.
- Toda respuesta trae synced_at, la última vez que Connect revisó el objeto. Con source=connect, refresh=true relee estado y nombre de los ítems de la página.
- per_page va de 1 a 100 (por defecto 15) y la respuesta es {data, links, meta}. Con source=external no viene meta.total, y con status la página puede superar un poco per_page.
- Los ítems que Connect guarda traen uuid. Los que solo existen en la cuenta traen uuid null. El presupuesto viene en la moneda de la cuenta, nunca en centavos.
Campos principales
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| customer_integration | string | Sí | El uuid de la conexión del cliente. Define la cuenta de anuncios. Va siempre en la query. |
| source | string | No | connect (por defecto) lee lo que Connect creó o ya escribió en la cuenta. external lee la cuenta en vivo, incluso lo creado fuera de Connect. |
| status | string | No | Filtra por active o paused. |
| effective_status | string | No | Solo con source=connect. Filtra por el estado que la plataforma aplica realmente, como pending_review, disapproved o with_issues. |
| refresh | boolean | No | Con source=external ignora el caché de 120 s. Con source=connect relee estado y nombre de los ítems de la página y actualiza Connect. |
| per_page | integer | No | Ítems por página, de 1 a 100. El valor por defecto es 15. |
| campaign_id | string | No | Solo en /ads/adsets y /ads: filtra por el id de la campaña o el uuid de Connect. |
| include_deleted | boolean | No | Solo con source=connect. Incluye los objetos eliminados, con deleted_at. |
Para quién
Panel de campañas en tu SaaS
Muestra al cliente sus campañas activas, el presupuesto y el estado efectivo sin que abra el Administrador de Anuncios.
Alerta de anuncio rechazado
Consulta periódicamente con effective_status=disapproved y avisa al equipo cuando un anuncio sea rechazado, con el motivo en issues.
Agente de IA que audita cuentas
Un agente lista la cuenta en vivo, encuentra conjuntos con problemas de entrega y propone pausar o ajustar el presupuesto.
Funciona con
Meta Ads
Preguntas frecuentes
¿Por qué la lista viene vacía en una cuenta que ya tenía campañas?
Porque el valor por defecto es source=connect, que solo muestra lo que Connect creó o ya escribió en la cuenta. Para ver lo creado fuera de Connect, usa source=external.
¿Los datos son en tiempo real?
Con source=external sí, con caché de 120 s que refresh=true ignora. Con source=connect ves el último estado conocido, indicado en synced_at, y refresh=true lo actualiza.
¿Cómo filtro solo lo que tiene problemas?
Usa effective_status con valores como with_issues, disapproved o pending_review (solo con source=connect). El motivo viene en el campo issues.
Mira Connect aplicado a tu producto.
Pruébalo durante 15 días sin tarjeta, o cuéntale tu caso a nuestro equipo.
