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

CampoTipoObrigatórioDescrição
customerstringNãouuid de um dos seus clientes. Sem ele, a resposta inclui todos os clientes.
customer_integrationstringNãouuid de uma conexão de um dos seus clientes, para restringir a uma só conta. Com customer, a conexão precisa ser desse cliente.
statusstringNãoFiltra pelo último status conhecido: active ou paused.
effective_statusstringNãoFiltra pelo último status efetivo visto, como pending_review, disapproved ou with_issues.
refreshbooleanNãoRelê os objetos da resposta na plataforma e atualiza o Connect. Exige customer_integration.
include_deletedbooleanNãoInclui os objetos apagados, com deleted_at.
per_pageintegerNãoItens por página, de 1 a 100. O padrão é 15.
customer_uuidstringNãoNa 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.

Relacionadas

Ver tudo que dá para fazer em Ads

Veja o Connect aplicado ao seu produto.

Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.