Relatórios de Meta Ads
API do Meta Ads: o que dá para puxar e o que exige App Review
O que a Marketing API entrega, o caminho real até o primeiro dado (app, verificação, permissões, App Review, token) e o que quebra integração caseira.
Este artigo também está em: Español
A API do Meta Ads é a Marketing API: a parte da Graph API que dá acesso programático às contas de anúncio. Por ela você lê gasto, impressões, cliques, conversões e custo por resultado nos níveis de conta, campanha, conjunto e anúncio, com quebras por posicionamento, dispositivo, idade, gênero e região. Também dá para criar e alterar campanhas, com uma permissão diferente e uma revisão mais dura. O que separa quem consegue o primeiro dado de quem desiste no meio não é código: é o caminho de app, verificação de negócio, permissões e App Review.
Este artigo é para quem está avaliando construir por conta própria. Ele mostra o caminho real, o que costuma quebrar depois que a integração já está de pé, e quando fazer não compensa.
O que a Marketing API entrega
O ponto principal da leitura é o relatório de desempenho. Você pede um período, um nível e uma lista de campos, e recebe as métricas correspondentes.
| Nível | O que você consegue | Uso típico |
|---|---|---|
| Conta | Totais do período, por dia ou agregados | Painel executivo, controle de gasto |
| Campanha | Desempenho por campanha, com objetivo e status | Onde o dinheiro está e o que pausar |
| Conjunto | Desempenho por público, posicionamento e orçamento | Diagnóstico de segmentação e entrega |
| Anúncio | Desempenho por criativo | Qual peça sustenta o resultado |
Além dos números, a API expõe a estrutura: nomes, status, orçamentos, objetivos, criativos, formulários de leads e o histórico de alterações da conta. As quebras funcionam junto com o período, e é aí que a API supera qualquer exportação manual: pedir gasto por campanha, por dia e por posicionamento de uma vez é trivial na API e é um inferno no Gerenciador.
Vale saber o que a API não resolve. Ela devolve a leitura do Meta, com as regras de atribuição do Meta. Se o seu CRM conta leads de outro jeito, a API não vai reconciliar isso por você. E métricas calculadas que você usa no relatório, como taxa de conversão sobre visualizações da página, continuam sendo conta sua. A lista do que vale a pena calcular está em as métricas do Meta Ads que importam.
O caminho real até o primeiro dado
Ninguém chega na API do Meta Ads pelo código. Chega pela burocracia. A ordem é esta:
- Criar um app no painel de desenvolvedores da Meta e associá-lo a um portfólio de negócios (Business Manager).
- Verificação do negócio. A Meta pede documentos que comprovem a existência da empresa por trás do app. Sem isso, o app fica preso no modo de desenvolvimento, servindo só a quem já tem acesso às contas.
- Escolher as permissões. Cada dado tem uma permissão associada. Leitura de anúncios e gestão de anúncios são permissões distintas, e existem outras para Páginas, Instagram e negócios.
- App Review. É onde a Meta avalia se o seu app pode pedir aquelas permissões a usuários que não são você. Envolve descrever o caso de uso, mostrar a tela onde o dado aparece e gravar um vídeo do fluxo, do login à exibição do dado.
- Token de acesso. Depois do OAuth, o app recebe um token que carrega as permissões concedidas. Tokens de curta duração são trocados por tokens de duração maior, que também vencem e podem ser invalidados antes da hora.
Não vou dizer quanto tempo cada etapa leva. Varia, a Meta muda o processo, e prazo inventado em artigo é o tipo de coisa que faz alguém prometer entrega para o chefe e se queimar. Planeje como projeto com data em aberto, não como sprint.
O detalhe que pega quase todo mundo desprevenido: no modo de desenvolvimento tudo funciona. Você puxa os dados da sua conta, monta o painel, mostra para o time. O muro aparece no dia em que um cliente precisa conectar a conta dele.
Leitura contra escrita: por que a segunda é mais difícil
Permissão de leitura devolve números. Permissão de escrita movimenta dinheiro: cria campanha, altera orçamento, pausa e reativa anúncio.
Do ponto de vista de quem revisa, o risco é assimétrico. Uma integração de leitura mal feita mostra um número errado. Uma integração de escrita mal feita gasta o orçamento de outra pessoa. Por isso a revisão da escrita costuma pedir mais evidência: qual é a tela onde a ação acontece, o que impede uma ação acidental, como o usuário confirma.
Se você está desenhando um produto, isso tem uma consequência prática. Vale separar leitura e escrita desde o começo, deixar a escrita desligada por padrão e construir confirmação e limite antes de pedir a permissão. Não é só para passar na revisão: é o que evita a ligação de domingo à noite.
As armadilhas que quebram integração caseira
A integração que funciona na sua máquina não é a que sobrevive um ano. Estas são as quatro fontes de manutenção que aparecem depois.
Paginação. Praticamente toda listagem da Graph API vem paginada. Quem lê só a primeira página monta um relatório que parece certo e está incompleto, e o erro não aparece em conta pequena, só na conta grande do cliente maior. Trate cursor e página seguinte desde o primeiro dia.
Versão da API. A Meta lança versões novas em ritmo constante e aposenta as antigas depois de um tempo. Isso significa que a sua integração tem prazo de validade embutido: em algum momento ela para de responder e alguém precisa migrar. Não é um bug, é o modelo. Quem constrói assume esse calendário para sempre.
Limite de requisição. Existe controle de volume por app e por conta, e ele não é um número fixo que você possa decorar: depende de uso, do tamanho da conta e da própria plataforma. O sintoma clássico é o painel funcionar bem com três contas e começar a falhar com trinta. A defesa é a mesma de sempre: repetição com espera crescente, cache do que não muda a toda hora e pedidos agregados em vez de um pedido por campanha.
Métricas que mudam ou saem. Campos são renomeados, deprecados e removidos. Aconteceu no orgânico: no nível de Página do Facebook, o alcance saiu da API. Quando um campo some, quem tem integração caseira descobre pelo painel vazio.
Construir por conta própria ou usar uma ferramenta pronta
Os dois lados têm custo de manutenção. A pergunta honesta não é qual é mais barato hoje, é quem paga a conta daqui a um ano.
| Construir por conta própria | Usar uma ferramenta pronta | |
|---|---|---|
| Custo inicial | Tempo de desenvolvimento mais o processo de app e revisão | Conectar a conta, minutos |
| Custo recorrente | Migração de versão, monitoramento, correção quando um campo muda | Assinatura, normalmente por conta conectada |
| Controle | Total: você define o modelo de dados e onde ele mora | Limitado ao que a ferramenta expõe |
| Quando compensa | O dado precisa entrar num sistema que só você tem | O objetivo é ler, comparar e reportar |
| Risco principal | A pessoa que construiu sai da empresa | A ferramenta não cobrir um caso específico seu |
Uma regra que funciona: se o resultado final é um relatório ou uma consulta, compre. Se o resultado final é um sistema (atribuição própria, precificação dinâmica, integração com um ERP que ninguém mais tem), construa, e trate a integração como produto, com dono e orçamento de manutenção.
Um meio-termo cresceu nos últimos tempos: em vez de a sua aplicação falar com a API, um modelo de linguagem fala. É o que faz um conector MCP, explicado em o que é MCP, e a versão aplicada a anúncios está em Meta Ads MCP. Você continua acessando a API do Meta, só que a camada de perguntas fica por conta do chat.
Antes de escrever a primeira linha de código
Faça este teste rápido. Ele economiza semanas.
- Quem vai conectar a conta? Só você, ou clientes? Se for cliente, o App Review não é opcional.
- Você precisa de escrita? Se a resposta é "seria legal", a resposta é não. Escrita entra depois, com trava.
- Quem migra a versão da API daqui a um ano? Se não tem nome, você está construindo dívida.
- O dado vai para onde? Se a resposta é planilha ou painel, provavelmente existe pronto. Se é um sistema seu, construa.
- O que acontece quando o token cai? Precisa existir uma tela dizendo que a conexão caiu, não um gráfico vazio.
Se em algum ponto você percebeu que só quer os números para reportar, o caminho mais curto passa antes por como exportar relatório do Meta Ads e por relatório de Meta Ads.
Próximo passo
Decida primeiro se o seu problema é de dado ou de sistema. Problema de dado, quase sempre, já tem solução pronta, e o tempo de desenvolvimento vira tempo de análise. Problema de sistema justifica a integração, e aí o caminho de app, verificação, permissões e revisão vale a pena ser percorrido com calma.
Se for o primeiro caso, veja como fica a consulta pelo chat em conectar Meta Ads no Claude e o que cabe em cada plano em preços.
Perguntas frequentes
O que é a API do Meta Ads?
É a Marketing API, a parte da Graph API que dá acesso programático às contas de anúncio do Meta. Por ela você lê métricas nos níveis de conta, campanha, conjunto e anúncio, com quebras como posicionamento, dispositivo, idade, gênero e região, e também cria e edita campanhas quando tem permissão de escrita.
Preciso de App Review para usar a API do Meta Ads?
Para uso interno, no seu próprio app, com as suas contas, dá para começar sem revisão. Assim que o app precisa acessar contas de outras pessoas ou empresas, a Meta exige verificação do negócio e revisão das permissões pedidas.
Qual a diferença entre permissão de leitura e de escrita no Meta Ads?
A leitura devolve métricas e estrutura das campanhas. A escrita cria, pausa e altera campanhas, conjuntos, anúncios e orçamentos, ou seja, movimenta dinheiro. Por isso a revisão da escrita costuma ser mais rigorosa e pede demonstração clara do uso.
Vale a pena construir a própria integração com a API do Meta?
Vale quando o dado precisa entrar num sistema que só você tem, como um CRM próprio ou um modelo de atribuição interno. Para relatório e leitura de campanha, o custo de manter versão da API, paginação e mudanças de métrica costuma superar o de assinar uma ferramenta pronta.
O token de acesso da API do Meta expira?
Tokens de curta duração expiram rápido e podem ser trocados por tokens de duração maior, que também têm validade e podem ser invalidados quando a senha muda, quando a pessoa perde acesso à conta ou quando as permissões são revogadas. Qualquer integração séria precisa tratar renovação e falha de token.