Ads
Listar campanhas, conjuntos e anúncios do Meta Ads pela API
Três rotas GET listam campanhas, conjuntos e anúncios da conta de anúncios de um cliente, com status, status efetivo, motivos de problema e orçamento. Você escolhe ler o que o Connect guarda ou a conta ao vivo, sem implementar OAuth nem passar pelo app review da Meta.
A chamada
GET /api/ads/campaigns?customer_integration=<connection uuid>&source=external&status=active&per_page=50 Authorization: Bearer <merchant token> x-customer-token: <customer token>
O que dá para fazer
- Listar campanhas, conjuntos de anúncios e anúncios com GET /ads/campaigns, /ads/adsets e /ads.
- Ler a conta ao vivo com source=external, inclusive o que foi criado fora do Connect.
- Filtrar por status (active ou paused) e, com source=connect, por effective_status, como pending_review ou disapproved.
- Ver em issues por que a plataforma está segurando um objeto, como reprovação ou problema de entrega.
- Filtrar conjuntos e anúncios por campaign_id e anúncios por adset_id, e paginar com page e per_page.
Regras e limites
- O padrão é source=connect: o que o Connect criou ou já escreveu na conta, sem chamar a plataforma. Uma conta com campanhas antigas lista vazio até a primeira escrita pelo Connect.
- Para ver tudo da conta, use source=external. A leitura ao vivo tem cache de 120 s, e refresh=true ignora o cache.
- Toda resposta traz synced_at, a última vez que o Connect conferiu o objeto. Com source=connect, refresh=true relê status e nome dos itens da página.
- per_page vai de 1 a 100 (padrão 15) e a resposta é {data, links, meta}. Em source=external não vem meta.total, e com status a página pode passar um pouco de per_page.
- Itens que o Connect guarda vêm com uuid. Os que só existem na conta vêm com uuid null. O orçamento vem na moeda da conta, nunca em centavos.
Campos principais
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| customer_integration | string | Sim | uuid da conexão do cliente. Define a conta de anúncios. Vai sempre na query. |
| source | string | Não | connect (padrão) lê o que o Connect criou ou já escreveu na conta. external lê a conta ao vivo, inclusive o que foi criado fora do Connect. |
| status | string | Não | Filtra por active ou paused. |
| effective_status | string | Não | Só com source=connect. Filtra pelo status que a plataforma aplica de fato, como pending_review, disapproved ou with_issues. |
| refresh | boolean | Não | Com source=external ignora o cache de 120 s. Com source=connect relê status e nome dos itens da página e atualiza o Connect. |
| per_page | integer | Não | Itens por página, de 1 a 100. O padrão é 15. |
| campaign_id | string | Não | Só em /ads/adsets e /ads: filtra pelo id da campanha ou pelo uuid do Connect. |
| include_deleted | boolean | Não | Só com source=connect. Inclui os objetos apagados, com deleted_at. |
Para quem
Painel de campanhas no seu SaaS
Mostre ao cliente as campanhas ativas, o orçamento e o status efetivo de cada uma sem ele abrir o Gerenciador de Anúncios.
Alerta de anúncio reprovado
Consulte periodicamente com effective_status=disapproved e avise o time quando um anúncio for rejeitado, com o motivo em issues.
Agente de IA que audita contas
Um agente lista a conta ao vivo, encontra conjuntos com problemas de entrega e propõe pausar ou ajustar o orçamento.
Funciona com
Meta Ads
Perguntas frequentes
Por que a lista vem vazia numa conta que já tinha campanhas?
Porque o padrão é source=connect, que só mostra o que o Connect criou ou já escreveu na conta. Para ver o que foi criado fora do Connect, use source=external.
Os dados são em tempo real?
Com source=external sim, com cache de 120 s que refresh=true ignora. Com source=connect você vê o último estado conhecido, indicado em synced_at, e refresh=true o atualiza.
Como filtro só o que está com problema?
Use effective_status com valores como with_issues, disapproved ou pending_review (só com source=connect). O motivo vem no campo issues.
Veja o Connect aplicado ao seu produto.
Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.
