Google Ads API — Autenticação

Pré-requisitos

Verifique antes de começar

Requisito	Detalhes
Conta Google Ads	MCC ou conta individual. Crie MCC em ads.google.com
Onboarding concluído	Onboarding — VS Code, Python, workspace prontos

1. Obter Token de Desenvolvedor

Identifica sua aplicação junto ao Google

Google Ads → Ferramentas → Central de API
Solicite Acesso Básico (gratuito)
Copie o Token de Desenvolvedor

⏳

A aprovação pode levar dias/semanas. Enquanto aguarda, use a Conta de Teste (sandbox) na Central de API — acesso imediato.

Conta de Teste vs Acesso Básico

Funcionalidade	Conta de Teste	Acesso Básico
Aprovação	Imediata (sandbox)	Dias/semanas (revisão Google)
Leitura de dados	Sim — lê métricas reais das contas do MCC	Sim — acesso completo
Criar/editar campanhas	Bloqueado — somente leitura	Sim — mutate operations liberadas
Veicular anúncios	Não — nenhuma alteração real	Sim — operações reais
Rate limit	1.000 ops/dia	15.000 ops/dia
Relatórios e GAQL	Dados reais (leitura)	Dados reais (leitura + escrita)
Uso ideal	Diagnósticos, relatórios, testar queries	Produção — gerenciar contas de clientes

💡

A Conta de Teste já lê dados reais — perfeita para diagnósticos e relatórios. Quando o token for aprovado, basta trocar o developer_token no YAML para desbloquear escrita (criar campanhas, editar lances, etc).

2a. Criar Projeto no Google Cloud

Ativar Google Ads API

console.cloud.google.com → Novo Projeto
Nome: Claude Code Google Ads
APIs e Serviços → Biblioteca → pesquise "Google Ads API" → Ativar

2b. Tela de Consentimento OAuth

Permitir seu app acessar Google Ads

APIs e Serviços → Tela de Consentimento OAuth
Tipo: Externo
Preencha nome do app + email de suporte
Escopos: adicione https://www.googleapis.com/auth/adwords
Usuários de Teste: adicione seu email Google

2c. Criar Credenciais OAuth 2.0

Client ID + Client Secret

APIs e Serviços → Credenciais → Criar → ID do Cliente OAuth 2.0
Tipo: Aplicativo de desktop
Copie o Client ID e Client Secret

3a. Gerar Refresh Token

Executar script OAuth

Execute o script que já veio no workspace:

terminal

pip install google-auth-oauthlib
python credentials/get_google_refresh_token.py

Antes de rodar, edite o arquivo e coloque seu Client ID e Client Secret.

💡

Vai abrir o navegador. Faça login com o Google que tem acesso ao Ads. Se aparecer "app não verificado", clique Avançado → Acessar.

3b. Criar google-ads.yaml

Arquivo de credenciais

Edite credentials/google-ads.yaml com seus dados:

yaml

developer_token:    "SEU_TOKEN_DE_DESENVOLVEDOR"
client_id:          "SEU_CLIENT_ID.apps.googleusercontent.com"
client_secret:      "SEU_CLIENT_SECRET"
refresh_token:      "SEU_REFRESH_TOKEN"
login_customer_id: "SEU_MCC_ID"   # somente números, sem traços
use_proto_plus:     True

🔒

NUNCA compartilhe este arquivo. Ele dá acesso total a sua conta Google Ads.

Solução de Problemas

Problema	Solução
Token não aprovado	Aprovação manual do Google (dias/semanas). Use Conta de Teste enquanto aguarda.
RefreshError / token expirado	Rode `get_google_refresh_token.py` novamente e atualize o YAML.
"App não verificado"	Normal para seu próprio app. Clique Avançado → Acessar.
REST API erro 501	Use a biblioteca `google-ads` (gRPC). REST não e suportado.
Cliente não encontrado	Verifique `login_customer_id` no YAML (MCC, sem traços).
Permissão negada	Email do OAuth precisa ter acesso de Admin/Padrão na conta.

Referência Rápida

# Arquivos de credenciais credentials/google-ads.yaml ← NUNCA commitar credentials/get_google_refresh_token.py ← gera refresh token # Conexao padrão from google.ads.googleads.client import GoogleAdsClient client = GoogleAdsClient.load_from_storage("credentials/google-ads.yaml") # GAQL: campanhas ultimos 30 dias SELECT campaign.name, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions FROM campaign WHERE segments.date DURING LAST_30_DAYS

Próximo passo

Volte ao VS Code e execute /configurar-ambiente — o Claude vai validar a conexão automaticamente.