Como configurar a Meta Ads CLI: tutorial passo a passo para 2026

Para configurar a Meta Ads CLI, você cria um System User no Business Manager, gera um token que nunca expira com as permissões ads_management, ads_read e business_management, vincula sua conta de anúncios e sua página como ativos e, em seguida, aponta a CLI para esse token através de um arquivo de configuração. Todo o processo leva cerca de 45 minutos se você tiver acesso de administrador a um Business Manager, uma página do Facebook e um método de pagamento verificado na sua conta de anúncios.

Este é o aprofundamento complementar à nossa visão geral sobre como rodar Facebook Ads com agentes de IA. Aquele artigo explica por que uma configuração orientada por CLI supera os cliques no Ads Manager para quem gerencia mais do que um punhado de campanhas. Este aqui é o guia prático: cada passo, cada mensagem de erro que enfrentamos ao montar nosso próprio stack e um passo a passo real da primeira campanha ao final.

O que a Meta Ads CLI realmente faz

A "Meta Ads CLI" não é um único binário oficial. É uma fina camada de automação no lado do servidor que fica entre seus scripts e a Meta Marketing API. Você escreve código em Python ou Node, a CLI cuida da autenticação, da assinatura das requisições e do token de longa duração do System User, e suas campanhas sobem através de graph.facebook.com/v23.0/ sem que ninguém precise clicar pelo Ads Manager.

A parte difícil não é o código wrapper — são umas cem linhas. A parte difícil é o ritual de configuração em 7 passos dentro do Business Manager que produz um token que a Meta realmente aceita para tráfego de produção. Esse ritual elimina a dança de refresh do OAuth e a dor de expiração de token que quebra toda automação baseada em navegador mais cedo ou mais tarde.

O retorno é real. Uma vez que o stack da CLI esteja rodando, você pode lançar uma campanha com 6 variantes de anúncio em menos de 90 segundos, puxar o desempenho de ontem para um relatório diário às 7:00 da manhã via cron e pausar automaticamente os anúncios com baixo desempenho — sem nunca fazer login no Ads Manager.

Pré-requisitos

Antes de começar, garanta que você tem tudo isso pronto. Pular qualquer um deles te joga em um buraco de 2 horas depois.

Você precisa de uma conta do Meta Business Manager com direitos de administrador — contas pessoais do Facebook não funcionam para tokens de System User. Você precisa de uma página do Facebook onde você esteja listado como administrador, não apenas editor. Você precisa de uma conta de anúncios da Meta dentro desse Business Manager com um método de pagamento verificado e pelo menos um país aprovado para faturamento. Você precisa de um Pixel (ou "Dataset" na nova terminologia) configurado para o site para onde você está enviando tráfego. E você precisa de Python 3.10+ ou Node 18+ instalado localmente, com permissão para instalar pacotes.

Se você ainda não tem um Pixel, crie um antes de continuar. Mesmo que você planeje usar apenas a Conversions API (CAPI) — como nós fazemos — você ainda precisa do Pixel ID como endereço de roteamento para eventos do lado do servidor.

A configuração em 7 passos

Esses passos são sequenciais. Cada um desbloqueia o próximo. Pular adiante quebra a corrente de formas difíceis de depurar, porque as mensagens de erro da Meta costumam ser enganosas.

Passo 1: criar um System User no Business Manager

Vá em Business Settings → Users → System Users. Clique em "Add" e crie um novo System User. O nome não importa para a API, mas importa para a sua sanidade futura — dê um nome como seu-marca-agent para você lembrar do que ele faz daqui a seis meses. Escolha o papel "Admin" (não "Employee"), porque System Users sem direitos de administrador não conseguem gerenciar Custom Conversions ou eventos do Pixel.

Quando montamos nosso stack, criamos o emaxstudioagent. O ID do System User é atribuído automaticamente (número de 15 dígitos). Anote.

Passo 2: criar um Developer App com use case de Marketing API

Vá em developers.facebook.com → My Apps → Create App. Escolha o use case "Marketing API" se ele aparecer no dropdown. Se você só vir "Other", tudo bem também — tokens de System User funcionam de qualquer jeito. A UI em alemão chama isso de "Werbeanzeigen mit Marketing API", enquanto a UI em inglês chama apenas de "Marketing API" ou "Other". Ambos produzem tokens idênticos.

Defina o app como tipo Business, não Consumer. Adicione o produto Marketing API ao app pela barra lateral esquerda. O app começa em modo de desenvolvimento (Development Mode). Você precisa movê-lo para o modo Live (mais sobre isso abaixo) antes que o token do System User funcione para anúncios reais.

Para mover para o modo Live, a Meta exige uma URL pública de política de privacidade e um ícone do app (PNG 1024×1024). Os dois são inegociáveis. O ícone do app não precisa ser polido — um placeholder funciona — mas a URL precisa de fato resolver para uma página de política de privacidade. Hospedamos a nossa em /legal no nosso domínio principal.

Passo 3: gerar um token de System User que nunca expira

De volta em Business Settings → System Users → [seu System User] → clique em "Generate New Token". Selecione o app que você acabou de criar no Passo 2. Em seguida, selecione as permissões:

• ads_management — necessária para criar, editar e pausar campanhas
• ads_read — necessária para puxar insights e dados de relatórios
• business_management — necessária para gerenciar ativos e custom conversions

Defina a expiração como "Never". Tokens de System User são os únicos tokens da Meta que de fato nunca expiram — User Access Tokens chegam no máximo a 60 dias, Page Tokens dependem do User Token do qual foram derivados. Esse é exatamente o motivo de usar um System User em vez de OAuth para automação de backend.

Copie o token imediatamente. A Meta mostra ele só uma vez. Guarde em um gerenciador de segredos ou em um arquivo .env com chmod 600. Nunca faça commit dele no git.

Passo 4: vincular a conta de anúncios e a página como ativos

O System User existe, mas ainda não tem acesso a nada. Você precisa atribuir os ativos explicitamente. Em Business Settings → System Users → [seu System User] → clique em "Add Assets".

Atribua sua conta de anúncios com permissão total ("Manage Campaigns" + "Manage Performance"). Atribua sua página com permissão total. Atribua seu Pixel/Dataset com permissão total. Se você tem várias contas de anúncios e quer que a CLI gerencie todas elas, atribua cada uma.

Quando configuramos isso, atribuímos act_975780295197610 (nossa conta de anúncios) e a página 1113585798495892 (nossa página EMAX Studio) mais o Pixel 1464075091373537. O prefixo act_ nos IDs de conta de anúncios é obrigatório quando você chama a API — ele faz parte do ID propriamente dito, não é uma convenção de formatação.

Passo 5: atribuir a permissão "Page verwalten" / "Manage Page"

Esse é o passo que pega quase todo mundo de primeira. O passo 4 atribuiu a página como ativo, mas o nível de permissão padrão é "Anzeigen erstellen" / "Create Ads" — o que não é suficiente. O System User precisa de "Page verwalten" / "Manage Page" para publicar criativos de anúncio que referenciam a página.

Se você pular isso, toda chamada de API para criação de anúncio vai retornar um erro genérico de "permission denied" que não menciona a página. Você vai passar horas verificando os escopos do seu token e as permissões da conta de anúncios, enquanto o problema real está a um clique de distância nas configurações do ativo da página.

Clique na página na lista de ativos, role até as permissões e ative "Manage Page" para o System User. Salve.

Passo 6: instalar a CLI e criar um arquivo de configuração

Para Python, instale o SDK oficial:

pip install facebook-business

Para Node, use o cliente mantido pela comunidade:

npm install facebook-nodejs-business-sdk

Crie um arquivo de configuração em ~/.meta-ads/config.json (ou onde quer que seu stack guarde segredos):

{
  "access_token": "EAA...seu-token-de-system-user",
  "app_id": "910292175368026",
  "app_secret": "seu-app-secret",
  "ad_account_id": "act_975780295197610",
  "page_id": "1113585798495892",
  "pixel_id": "1464075091373537",
  "api_version": "v23.0"
}

Defina as permissões: chmod 600 ~/.meta-ads/config.json. O app_secret é opcional para tokens de System User, mas habilita a assinatura appsecret_proof, que a Meta recomenda para produção.

Passo 7: rodar o primeiro comando de teste

Verifique se tudo funciona listando suas campanhas. Em Python:

from facebook_business.api import FacebookAdsApi
from facebook_business.adobjects.adaccount import AdAccount
import json

cfg = json.load(open("/caminho/para/config.json"))
FacebookAdsApi.init(access_token=cfg["access_token"])
account = AdAccount(cfg["ad_account_id"])
campaigns = account.get_campaigns(fields=["name", "status", "objective"])
for c in campaigns:
    print(c["name"], c["status"], c["objective"])

Se isso retornar uma lista (mesmo uma lista vazia, se você ainda não tiver campanhas), você terminou. Se levantar OAuthException ou Permission denied, volte para a tabela de erros abaixo.

Erros comuns de configuração e como corrigi-los

Esses são os 8 erros que nos pegaram durante a construção. Cada um deles custou horas reais. Economize essa dor.

O da Custom Conversion é o mais cruel porque a mensagem de erro tecnicamente te diz o que está errado, mas a solução não é óbvia. Uma Custom Conversion novinha em folha tem zero eventos no sistema da Meta. A Meta se recusa a otimizar uma campanha para algo sobre o qual não tem dados históricos. O truque é lançar a campanha otimizada para Landing Page Views primeiro, deixar mais de 50 conversões dispararem via CAPI e então trocar o promoted_object do Ad Set para OFFSITE_CONVERSIONS com o ID da sua Custom Conversion. Depois disso, a otimização realmente funciona.

Um passo a passo real da primeira campanha

Aqui está o que rodamos como nosso primeiro teste ao vivo. Valores reais, fluxo real, resultados reais.

Crie a campanha. Objetivo: OUTCOME_TRAFFIC (depois trocado para OUTCOME_SALES quando tivemos dados de conversão). Status: PAUSED inicialmente, para que o Ad Set e os Ads possam ser criados embaixo antes de virar tudo para ACTIVE num passo só. O orçamento fica no nível do Ad Set na nossa configuração.

Crie o Ad Set. Orçamento diário: 1000 (centavos = $10/dia). Otimização: LANDING_PAGE_VIEWS. Estratégia de lance: LOWEST_COST_WITHOUT_CAP. Segmentação: países ["US", "GB", "CA"], idade 25 a 55, idioma inglês. Placements: feed, instagram_reels, stories, marketplace. Targeting automation: {"advantage_audience": 1}.

Monte os criativos. Três criativos de imagem e três criativos de vídeo — seis anúncios no total. Para as imagens, usamos a própria saída do EMAX Studio (use o que você mesmo produz): três hooks, três fundos com a cor da marca, todos 1080×1080. Para os vídeos, três reels verticais de 15 segundos com legendas palavra por palavra e voz de IA, gerados pelo nosso próprio pipeline (descrito em Como criar uma campanha de marketing com IA passo a passo). Cada criativo de vídeo precisa de um image_hash para o thumbnail — extraia um frame em 1,5 segundo com o ffmpeg, faça upload em /adimages e use o hash retornado dentro do bloco video_data.

Ative. Vire a campanha, depois o Ad Set, depois os seis anúncios para ACTIVE. A revisão da Meta normalmente sai em 15 a 30 minutos. Anúncios rejeitados aparecem por anúncio via ad.get('effective_status').

Relatório diário. Um script meta_daily_report.py roda às 7:00 da manhã horário de Berlim via cron. Ele puxa insights, formata gasto / CTR / CPM / conversões em uma mensagem do Telegram e pausa automaticamente qualquer anúncio com CTR abaixo de 0,5% após mais de 100 impressões. As primeiras 48 horas geraram 4.200 impressões, 78 cliques (CTR 1,86%) e 12 Quick Scan completados a $1,67 por conversão — sinal suficiente para trocar a otimização de Landing Page Views para OFFSITE_CONVERSIONS contra a Custom Conversion QuickScanComplete no terceiro dia.

Armadilhas para evitar

Algumas coisas vão te queimar. Aprendemos cada uma delas do jeito difícil.

Não hardcodifique tokens no git. Mesmo em repositórios privados. Tokens vazam por logs de CI, forks acidentalmente públicos e commits feitos antes de a visibilidade do repositório mudar. Sempre leia de variáveis de ambiente ou de um arquivo de configuração chmod-600 fora do repositório.

Não pule a permissão Manage Page do Passo 5. Os erros que você recebe parecem ser sobre a conta de anúncios ou sobre o token. Não são. Confira primeiro a permissão do ativo da página sempre que vir um "permission denied" vago na criação de criativos.

Não faça deploy com o app de desenvolvedor ainda em Development Mode. O token funciona para o usuário que o criou, mas falha silenciosamente para qualquer outro contexto de System User. Mude para Live Mode antes de rodar qualquer coisa em um servidor.

Não esqueça do image_hash para criativos de vídeo. Sem ele, toda a criação do anúncio falha com um erro enganoso sobre video_data.

Não pule a CAPI se você planeja escalar. Pixels de navegador perdem de 30 a 50% dos eventos por causa do iOS ATT, bloqueadores de anúncios e prevenção de rastreamento. A Conversions API do lado do servidor recupera a maioria deles — um fim de semana de trabalho que se paga já na primeira semana em que você aumenta o investimento em anúncios.

Perguntas frequentes

Quanto custa configurar a Meta Ads CLI?

A configuração em si é grátis. A Marketing API, os tokens de System User, o Business Manager e todas as ferramentas de desenvolvedor têm custo zero — você só paga pelos anúncios que de fato rodar. Planeje de 4 a 6 horas de configuração na primeira vez e 30 minutos em qualquer vez depois.

Posso rodar várias contas de anúncios através de uma instalação da CLI?

Sim, e essa é uma das principais razões pelas quais agências usam tokens de System User. Adicione cada conta de anúncios como ativo em Business Settings e você pode mirar em qualquer uma delas mudando o ad_account_id na sua configuração ou passando como parâmetro. Um único token de System User pode gerenciar centenas de contas de anúncios em vários Business Managers, desde que as permissões estejam no lugar.

E uma CLI para o Google Ads — a configuração é parecida?

O conceito é parecido, mas a configuração do Google é mais áspera. O Google exige uma aprovação de developer token que pode levar de 7 a 21 dias, refresh tokens de OAuth2 que expiram periodicamente e uma camada adicional de permissões de MCC (Manager Account). O token de System User da Meta é, sinceramente, o mais simples dos dois sistemas. Se você roda as duas plataformas, configure a Meta primeiro para aprender os padrões.

Como rotaciono tokens com segurança se um for comprometido?

Gere um novo token de System User (mesmas permissões, mesma expiração "Never"), atualize sua configuração, teste se o novo token funciona e então revogue o antigo. A Meta deixa você manter vários tokens ativos para o mesmo System User simultaneamente, então você pode trocar sem downtime. Se um token vazar, revogue imediatamente e audite o gasto recente em anúncios pela API em busca de campanhas não autorizadas.

Como a Conversions API (CAPI) se encaixa nessa configuração?

A CAPI é um sistema separado, mas complementar. A Meta Ads CLI gerencia campanhas, ad sets e anúncios. A CAPI envia eventos de conversão do lado do servidor contra os quais esses anúncios otimizam. Os dois usam o mesmo Pixel ID. Eventos da CAPI fluem independentemente de qualquer pixel de navegador — eles são a base de um rastreamento limpo em termos de GDPR, porque nenhum cookie está envolvido e PII é hasheado antes da transmissão. A visão geral de Facebook Ads com agentes de IA cobre como a CAPI se encaixa no stack maior de automação.

A conclusão honesta

A Meta Ads CLI não é mágica. É uma forma disciplinada de remover três coisas do seu fluxo de trabalho: refreshes de token OAuth, logins manuais no Ads Manager e o custo do erro humano de clicar por 14 configurações toda vez que você lança um anúncio. Uma vez rodando, você faz em 90 segundos o que antes levava 30 minutos.

A configuração é chata porque a tooling da Meta é chata. Mas os passos são determinísticos. Siga a configuração em 7 passos exatamente, fique de olho nos 8 erros da tabela e você terá um stack de anúncios em nível de produção até o fim da tarde. Para o quadro maior de como a CLI se conecta a criativos de IA e relatórios diários, veja nossa visão geral sobre Facebook Ads com agentes de IA e as notícias de IA da semana 18, 2026 para o que está mudando no ecossistema de anúncios neste ano.

Uma vez que a CLI esteja no ar, a pergunta vira: que criativos alimentá-la com. Rode sua landing page por um scan grátis de prontidão para IA de 90 segundos em emax.studio — você recebe uma pontuação, uma lista de lacunas de conversão e um briefing de campanha pronto para rodar em menos de dois minutos.

Siga a EMAX Studio: Instagram | YouTube | Facebook