Configurar Token da Meta Ads API

1

Passo 1 de 10

Criar conta de desenvolvedor Meta

Primeiro passo: registrar tua conta no portal de desenvolvedores. Se tu já tem uma conta de desenvolvedor (já mexeu com apps do Facebook antes), pula direto pro Passo 2.

Criando a conta passo a passo

1

Acessa developers.facebook.com no teu navegador

2

Clica em "Iniciar" (ou "Get Started") no canto superior direito. Se tu já tiver logado no Facebook, vai puxar tua conta automaticamente.

3

Aceita os Termos de Uso da plataforma de desenvolvedores da Meta

4

Confirma teu email (vai chegar um email de verificação, clica no link)

5

Se pedir, verifica tua identidade — geralmente pede número de telefone pra confirmar via SMS

💡 Se tu já tem uma conta de desenvolvedor, pula direto pro Passo 2. Não precisa criar outra conta.

2

Passo 2 de 10

Criar App Meta

O App é a "chave mestra" que dá acesso à API. Pensa nisso como credenciais que autorizam a leitura e escrita na tua conta de anúncios.

Criando o app passo a passo

1

No painel de desenvolvedores, clica em "Meus Apps" no menu superior

2

Clica no botão "Criar aplicativo" (botão verde)

3

Na tela de caso de uso, seleciona: "Outro" (ou "Criar e gerenciar anúncios com a API de Marketing" se aparecer essa opção diretamente)

4

Tipo de app: seleciona "Negócios" (Business)

5

Preenche o Nome do App — ex: "Minha Empresa Ads API" (não precisa ser nada especial, é só pra tua organização)

6

Preenche teu email de contato

7

Em "Portfólio de Negócios" (Business Portfolio), seleciona teu Business Manager. Se não tiver, pode deixar em branco por agora.

8

Clica em "Criar aplicativo" e confirma tua senha

⚠️ Anota o App ID e o App Secret! Tu vai precisar deles depois. O App Secret fica em Configurações do App > Básico. Nunca compartilha o App Secret publicamente.

3

Passo 3 de 10

Adicionar produto Marketing API

Agora tu precisa ativar a Marketing API dentro do teu App. É ela que dá acesso aos dados de anúncios, campanhas e audiências.

Habilitando a Marketing API

1

No painel do teu App, vai no menu lateral e clica em "Adicionar Produtos" (ou "Add Products")

2

Procura por "API de Marketing" (ou "Marketing API")

3

Clica em "Configurar" nesse produto

4

Pronto! A Marketing API foi adicionada ao teu App. Agora ela aparece no menu lateral.

Opcionalmente, tu também pode adicionar estes casos de uso extras (recomendado):

Casos de uso extras

1

Volta em "Casos de Uso" no menu lateral

2

Adiciona "Gerenciar mensagens e conteúdo no Instagram" — necessário se tu for criar ads com posts do Instagram

3

Adiciona "Gerenciar tudo na sua Página" — necessário pra dark posts e criativos que usam páginas do Facebook

4

Passo 4 de 10

Ativar modo Live

CRÍTICO: sem isso, teu token não funciona direito. Se teu app ficar em modo "Development", tu não vai conseguir criar dark posts, criativos, nem acessar dados reais das contas de anúncio.

⚠️ ATENÇÃO MÁXIMA! Se teu app ficar em modo "Development", tu não vai conseguir criar dark posts, criativos, nem acessar dados reais das contas de anúncio. Esse passo é obrigatório.

Ativando o modo Live

1

No menu lateral do teu App, vai em "Configurações do App" > "Básico"

2

Preenche os campos obrigatórios: Nome de exibição do app, URL da Política de Privacidade (pode ser qualquer URL válida do teu site), e Ícone do App (imagem 1024x1024px)

3

Salva as alterações

4

No menu lateral, clica em "Publicar" (ou procura o toggle "Modo do App" no topo do painel)

5

Muda de "Em Desenvolvimento" para "Ativo" (Live)

6

Confirma a ativação

⚠️ Depois de ativar o modo Live, tu PRECISA regerar o token. O token gerado em modo Development não funciona no modo Live. Volta no Graph API Explorer (Passo 5) e gera um novo.

5

Passo 5 de 10

Gerar Access Token

O token de acesso é o que permite a API te identificar. Vamos gerar ele pelo Graph API Explorer do Meta.

Gerando o token

1

Acessa o Graph API Explorer: developers.facebook.com/tools/explorer

2

No dropdown "Meta App" (canto superior direito), seleciona o App que tu criou no Passo 2

3

Clica em "Add a Permission" (ou "Adicionar Permissão") e adiciona as permissões da tabela abaixo

Permissão	Pra que serve	Status
`ads_management`	Criar, editar e gerenciar anúncios	Obrigatório
`ads_read`	Ler dados de campanhas e insights	Obrigatório
`business_management`	Acessar contas de anúncio do Business Manager	Obrigatório
`pages_read_engagement`	Ler dados de engajamento das páginas	Obrigatório
`pages_show_list`	Listar páginas conectadas	Obrigatório
`instagram_basic`	Acessar perfil do Instagram conectado	Obrigatório
`instagram_manage_insights`	Ler métricas do Instagram	Recomendado
`pages_manage_engagement`	Gerenciar comentários e mensagens	Recomendado

Depois de marcar as permissões

4

Clica no botão "Generate Access Token" (ou "Gerar Token de Acesso")

5

Uma janela popup vai abrir pedindo pra tu autorizar o app. Seleciona TODAS as páginas e contas de anúncio que tu quer dar acesso. Clica em "Continuar" em todas as etapas.

6

O token aparece no campo "Access Token" do Explorer. Copia e salva em algum lugar seguro.

⚠️ CUIDADO: esse token de usuário dura só 1 a 2 horas! Depois disso, ele expira e para de funcionar. Vai pro Passo 6 imediatamente pra estender a validade, ou pro Passo 7 pra um token que nunca expira.

6

Passo 6 de 10

Token de longa duração (60 dias)

Estender o token de 1 hora pra 60 dias. Tu pode fazer isso pelo Depurador de Token (mais fácil) ou via API (pra quem curte terminal).

Opção A: Pelo Depurador de Token (mais fácil)

Via Depurador

1

Acessa o Depurador de Token: developers.facebook.com/tools/debug/accesstoken

2

Cola o token que tu gerou no Passo 5 no campo de input

3

Clica em "Depurar" (Debug)

4

Verifica se as permissões estão corretas na lista que aparece

5

Clica no botão "Estender Token de Acesso" (Extend Access Token) que aparece embaixo

6

Copia o novo token estendido — esse vale por ~60 dias

Opção B: Via API (pra quem curte terminal)

Terminal

% curl "https://graph.facebook.com/v21.0/oauth/access_token?grant_type=fb_exchange_token&client_id=TEU_APP_ID&client_secret=TEU_APP_SECRET&fb_exchange_token=TOKEN_CURTO_DO_PASSO_5"

💡 O App ID e o App Secret ficam em Configurações do App > Básico no painel do teu App. O App Secret fica oculto — clica em "Mostrar" pra ver.

⚠️ Esse token de 60 dias ainda expira. Se tu quer um token que nunca expira, vai pro Passo 7 (System User).

7

Passo 7 de 10

Token permanente (System User)

Token que NÃO expira — ideal pra automações e scripts. Se tu vai usar a API de forma automatizada, o System User é a melhor opção.

✅ Recomendação: Se tu vai usar a API de forma automatizada (scripts, skills, bots), o System User é a melhor opção. O token não expira e é mais seguro que um token de usuário.

Criando o System User

1

Acessa o Business Manager: business.facebook.com/settings

2

No menu lateral, vai em "Usuários" > "Usuários do sistema" (System Users)

3

Clica em "Adicionar" pra criar um novo usuário do sistema

4

Escolhe um nome (ex: "API Ads Automação") e o cargo: seleciona "Admin" pra acesso total

5

Clica em "Criar usuário do sistema"

6

Clica em "Adicionar ativos" no usuário criado: adiciona as Contas de anúncio (com controle total), Páginas do Facebook e Perfis do Instagram conectados

7

Depois de vincular os ativos, clica em "Gerar novo token"

8

Seleciona o App que tu criou no Passo 2

9

Marca as mesmas permissões do Passo 5 (ads_management, ads_read, business_management, etc.)

10

Clica em "Gerar token"

11

COPIA O TOKEN AGORA! Ele só aparece uma vez. Depois que tu fechar a janela, não tem como ver de novo (teria que gerar outro).

⚠️ O token do System User só aparece UMA VEZ. Se tu não copiar, perdeu. Vai ter que gerar outro. Cola num lugar seguro IMEDIATAMENTE (gerenciador de senhas, .env, etc).

8

Passo 8 de 10

Vincular páginas e contas ao App

Garantir que teu App tem acesso a tudo que precisa. Páginas não vinculadas = erro na API.

Verificando os vínculos

1

Vai em business.facebook.com/settings

2

No menu lateral, vai em "Contas" > "Páginas"

3

Verifica se as Páginas do Facebook que tu usa nos anúncios estão listadas. Se não tiver, clica em "Adicionar" > "Adicionar uma Página"

4

Agora vai em "Contas" > "Contas de anúncio" e verifica se estão vinculadas ao Business Portfolio

5

Se tu criou um System User (Passo 7), volta em "Usuários do sistema" e confirma que o usuário tem acesso a essas páginas e contas de anúncio

⚠️ Páginas não vinculadas = erro na API. Se tu tentar criar um anúncio usando uma página que não tá no teu Business Portfolio ou no teu App, a API vai retornar erro. Sempre verifica se a página tá vinculada.

9

Passo 9 de 10

Testar conexão

Confirmar que tudo tá funcionando antes de seguir. Abre teu terminal e faz essas chamadas:

Teste 1: Verificar identidade do token

Terminal

% curl "https://graph.facebook.com/v21.0/me?access_token=TEU_TOKEN"

{"id":"123456","name":"Teu Nome"}

Teste 2: Listar contas de anúncio

Terminal

% curl "https://graph.facebook.com/v21.0/me/adaccounts?access_token=TEU_TOKEN"

Deve retornar um array data com as contas (ex: act_123456789). Anota o ID da conta que tu vai usar.

Teste 3: Verificar permissões do token

Terminal

% curl "https://graph.facebook.com/v21.0/me/permissions?access_token=TEU_TOKEN"

✅ Se os 3 testes passaram, tá tudo certo! Teu token tá funcionando e tem acesso às contas de anúncio.

⚠️ Se deu erro? Causas comuns:
— Error validating access token — Token expirou. Gera um novo (Passo 5/6/7)
— OAuthException — App ainda em modo Development (Passo 4)
— Unsupported get request — Permissões faltando. Volta no Graph API Explorer e adiciona

10

Passo 10 de 10

Salvar no .env

Agora que tu tem tudo funcionando, salva as credenciais no arquivo .env da skill:

Arquivo: ~/.claude/skills/meta-ads-ratos/.env

.env

# Meta Ads Ratos — Configuração

# Os scripts leem este arquivo automaticamente.

# NÃO precisa adicionar ao ~/.zshrc.

# OBRIGATÓRIO: Token de acesso da Meta

META_ADS_TOKEN="EAAxxxxxx_teu_token_aqui"

# OBRIGATÓRIO: App ID do app Meta que gerou o token

META_APP_ID="905545132380980"

# OPCIONAL: Conta de anúncio padrão

META_AD_ACCOUNT_ID="act_123456789"

💡 Os scripts leem o .env automaticamente. Não precisa fazer source no terminal. O token fica isolado dentro da skill e não vaza pra outras sessões.

⚠️ Se tu usou o token de 60 dias (Passo 6): Anota no calendário pra renovar daqui ~55 dias. Quando vencer, repete os Passos 5 e 6.

Se tu usou o System User (Passo 7): O token não expira. Relaxa.

Resumo das credenciais

Credencial	Onde encontrar	Exemplo
App ID	Configurações do App > Básico	`905545132380980`
App Secret	Configurações do App > Básico (clica "Mostrar")	`abc123def456ghi789`
Access Token	Graph API Explorer ou System User	`EAAxxxxxxxx...`
Ad Account ID	me/adaccounts ou Business Settings	`act_123456789`

🎉 Pronto! Tá tudo configurado. Agora tu pode usar os comandos do Ads Ratos pra gerenciar tuas campanhas via API. Roda /meta-ads-ratos setup pra validar a configuração e cadastrar teus clientes.