Ads
Ver os anúncios de todos os clientes do Meta Ads pela API
Três rotas em /merchants/ads dão o panorama de campanhas, conjuntos e anúncios de todos os seus clientes, só com o token do merchant, sem x-customer-token. Você monitora a base inteira numa chamada, sem percorrer cliente por cliente e sem implementar a API da Meta.
A chamada
GET /api/merchants/ads/campaigns?customer=<customer uuid>&effective_status=disapproved&per_page=50 Authorization: Bearer <merchant token>
O que dá para fazer
- Listar campanhas, conjuntos e anúncios de todos os clientes com GET /merchants/ads/campaigns, /merchants/ads/adsets e /merchants/ads.
- Restringir a um cliente com customer ou a uma conta com customer_integration.
- Filtrar por status e por effective_status, como disapproved, with_issues ou pending_review.
- Identificar o dono de cada objeto pelos campos customer_uuid e customer_integration_uuid.
- Incluir os apagados com include_deleted=true e paginar com page e per_page.
Regras e limites
- Essas rotas usam só Authorization: Bearer. Não levam x-customer-token, e customer e customer_integration são filtros, nunca credencial.
- Mostram o que o Connect guarda: o que ele criou ou já escreveu nas contas. Uma conta com campanhas antigas só aparece depois da primeira escrita pelo Connect.
- Os dados são o último estado conhecido, com synced_at. refresh=true relê os objetos da resposta, mas exige customer_integration.
- O customer e a conexão informados precisam ser do merchant do token. Com os dois, a conexão precisa ser desse cliente.
- per_page vai de 1 a 100 (padrão 15) e a resposta é {data, links, meta}.
Campos principais
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| customer | string | Não | uuid de um dos seus clientes. Sem ele, a resposta inclui todos os clientes. |
| customer_integration | string | Não | uuid de uma conexão de um dos seus clientes, para restringir a uma só conta. Com customer, a conexão precisa ser desse cliente. |
| status | string | Não | Filtra pelo último status conhecido: active ou paused. |
| effective_status | string | Não | Filtra pelo último status efetivo visto, como pending_review, disapproved ou with_issues. |
| refresh | boolean | Não | Relê os objetos da resposta na plataforma e atualiza o Connect. Exige customer_integration. |
| include_deleted | boolean | Não | Inclui os objetos apagados, com deleted_at. |
| per_page | integer | Não | Itens por página, de 1 a 100. O padrão é 15. |
| customer_uuid | string | Não | Na resposta: o cliente dono da conta de cada objeto. |
Para quem
Monitorar anúncios reprovados na base inteira
Um SaaS de tráfego lista com effective_status=disapproved e avisa cada cliente afetado, sem consultar conta por conta.
Visão do gestor numa agência
Uma agência vê campanhas ativas de todos os clientes numa única tela, filtrando por cliente quando precisa aprofundar.
Agente de IA de suporte
Um agente recebe o pedido de um cliente, filtra por customer e responde o que está ativo, pausado ou com problema.
Funciona com
Meta Ads
Perguntas frequentes
Preciso do x-customer-token nessas rotas?
Não. Elas usam só o Bearer do merchant. O cliente e a conexão entram como filtros (customer e customer_integration), e são conferidos contra o seu merchant.
Qual a diferença para GET /ads/campaigns?
GET /ads/campaigns é de um cliente, com x-customer-token e conexão obrigatória. A rota de /merchants/ads cobre todos os clientes e mostra o que o Connect guarda.
Os dados estão atualizados?
São o último estado conhecido, indicado em synced_at. Para atualizar, use refresh=true junto com customer_integration.
Veja o Connect aplicado ao seu produto.
Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.
