Developer token do Google Ads: do zero ao acesso básico

O prompt abaixo condensa este tutorial inteiro — incluindo as quatro armadilhas — em instruções para um agente de IA (Claude Code ou similar, de preferência com acesso a navegador e terminal) executar o processo com você. Preencha o bloco "MEUS DADOS" antes de enviar. Este cobre a Fase 1 (pedir o token); quando a aprovação chegar, use o prompt master da Fase 2.

Você é meu operador técnico para obter um developer token do Google Ads
com ACESSO BÁSICO aprovado, pronto para eu usar a Google Ads API
(leitura via MCP oficial). Execute o roteiro abaixo comigo, em ordem,
validando cada etapa antes da seguinte.

## MEUS DADOS (preenchi antes de te enviar)
- Empresa/agência: ___________
- Site da empresa (público): ___________
- E-mail de contato monitorado: ___________
- Já tenho MCC (conta de administrador)? [não | sim, ID: ___-___-____]
- Customer ID da(s) conta(s) de cliente a vincular: ___________
- Projeto Google Cloud existente? [não | sim, project ID: ___________]
- Meu site fica atrás de Cloudflare? [sim | não | não sei]

## REGRAS INVIOLÁVEIS
1. Antes de ENVIAR qualquer formulário ao Google, criar conta, vincular
   conta ou publicar página: me mostre tudo preenchido e peça meu OK.
2. Consistência é critério de aprovação: empresa, site e uso pretendido
   devem ser IDÊNTICOS na Central de API, no formulário de acesso básico
   e na verificação de marca.
3. Nunca responda política do Google de memória — confira a doc oficial
   (developers.google.com/google-ads/api) antes de me orientar.
4. Se tiver acesso a navegador, execute você; senão, me guie tela a tela
   com instruções exatas do que clicar.

## ROTEIRO
0. MCC: se eu não tenho, me guie a criar em
   ads.google.com/home/tools/manager-accounts (grátis, sem cartão).
   AVISO: fuso e moeda são imutáveis — Brasil: America/Sao_Paulo, BRL.
   A MCC é conta NOVA, separada da minha conta de anunciante.
1. Token: na MCC → Adm. → Central de API: preencher "Detalhes do
   desenvolvedor" com MEUS DADOS; anotar o token de 22 caracteres
   (nasce nível "Conta de teste").
2. Vínculo: MCC → Contas → Vincular conta existente → customer ID do
   cliente → enviar; aceitar do lado do cliente em Adm. → Acesso e
   segurança → aba Administradores → Aceitar → Permitir acesso.
   (Pode pedir confirmação de identidade/passkey — normal.)
3. Google Cloud: criar/usar projeto; habilitar googleads.googleapis.com;
   criar OAuth client tipo "App para computador".
4. Acesso básico: Central de API → Nível de acesso → Solicitar acesso
   básico → formulário new_token_application. ATENÇÃO: só existe em
   INGLÊS (trocar idioma). Gerar antes um design doc de 1 página
   (.pdf/.doc — propósito, arquitetura, GoogleAdsService.Search
   read-only, OAuth, política de dados) — a pergunta 8 exige upload.
   Respostas coerentes com ferramenta interna read-only: audience =
   Internal users only; third-party tool = No; App Conversion Tracking
   = No; capabilities = SÓ Reporting. Me mostrar tudo antes de enviar.
5. Associação token↔projeto (pré-requisito da verificação de marca):
   UMA chamada GET
   https://googleads.googleapis.com/vXX/customers:listAccessibleCustomers
   com Bearer de credencial DO projeto + header developer-token.
   Descubra a versão vigente (vXX). O método é GET (POST dá 404).
   A chamada PODE FALHAR (ex.: NOT_ADS_USER) — a associação conta
   mesmo assim (doc oficial).
6. Verificação de marca (console.cloud.google.com/auth):
   a. Público-alvo: tipo Externo + status Em produção (obrigatório
      para esta análise, mesmo app interno).
   b. Branding: nome do app; homepage DEDICADA e PÚBLICA que explique
      a finalidade do app com h1 IGUAL ao nome do app (criar landing
      simples se preciso); política de privacidade publicada e linkada
      (sem ela o botão "Verificar marca" nem habilita); domínio
      autorizado = domínio das páginas.
   c. Verificar marca (~5 min). SE FALHAR com "página protegida por
      login" + "não explica finalidade" + "nome não corresponde",
      mesmo com a página perfeita: verifique se o HTML servido contém
      /cdn-cgi/challenge-platform/ — é o Bot Fight Mode do Cloudflare
      desafiando o robô do Google. Me peça para desligar em
      dash.cloudflare.com → zona → Security → Bot Fight Mode,
      e re-verifique.
   d. PUBLICAR o branding após verificar — expira em 7 dias.
7. Espera produtiva: a resposta chega no e-mail de contato em até ~5
   dias úteis (com marca verificada pode sair em <24h). Enquanto isso,
   é possível validar o pipeline numa CONTA DE TESTE (o token atual já
   funciona nela). NÃO pedir acesso Standard: básico = 15.000 ops/dia
   grátis com a API INTEIRA; Standard só muda cota e é negado sem
   histórico de uso que justifique.
## CRITÉRIO DE SUCESSO
(1) aplicação enviada com ticket confirmado; (2) marca verificada E
publicada; (3) pipeline validado numa conta de teste.
Reporte cada um dos três explicitamente ao final. A Fase 2
(pós-aprovação) tem prompt próprio — peça ao usuário quando o e-mail
"Basic Access Approval" chegar.

MCC (My Client Center, hoje chamada oficialmente de conta de administrador) é uma conta de Google Ads que não roda anúncio nenhum. Ela é um painel guarda-chuva: em vez de campanhas, ela contém outras contas. Pense num chaveiro — cada chave é a conta de um cliente, e o chaveiro é seu.

Ela existe por três motivos, e o terceiro é o que interessa aqui:

• Gestão: uma agência administra 1, 10 ou 500 contas de clientes com um login só, sem pedir senha de ninguém
• Visão consolidada: relatórios e alertas de todas as contas num painel único
• API: o developer token só existe dentro de uma MCC — conta comum de anunciante não tem Central de API. Sem MCC, não há token; sem token, não há API

Criando (5 minutos, grátis, sem cartão)

1. Acesse ads.google.com/home/tools/manager-accounts e clique em criar conta de administrador — logado na conta Google que será a dona da operação
2. Dê o nome da sua empresa/agência (é o nome que os clientes verão no convite de vinculação) e responda o uso principal: gerenciar as suas próprias contas ou as contas de outras pessoas — pro token, qualquer um dos dois serve
3. Escolha país, fuso horário e moeda — leia a armadilha abaixo antes
4. Pronto — a MCC nasce vazia. Ela é uma conta separada da sua conta de anunciante comum, com customer ID próprio (formato 000-000-0000)

O developer token pertence a uma conta de administrador (MCC), nunca à conta comum do cliente. Se você é gestor de tráfego, o token é seu — da sua agência — e serve para todos os seus clientes.

1. Entre na MCC → Adm. → Central de API (ads.google.com/aw/apicenter)
2. Preencha os "Detalhes do desenvolvedor": e-mail de contato monitorado, nome da empresa, URL do site, tipo de empresa, uso pretendido
3. O token nasce com 22 caracteres e nível "Conta de teste" — só fala com contas de teste. Para produção, você precisa do passo 04

Sem vínculo, nem o token aprovado enxerga a conta do cliente. Verifique em Contas — se a lista estiver vazia (aconteceu com a gente), o acesso que você tem é pelo seu login pessoal, não pela MCC.

1. Na MCC: Contas → ➕ → Vincular conta existente → digite o customer ID (ex.: 765-956-6988) → Enviar solicitação
2. Na conta do cliente: Adm. → Acesso e segurança → aba Administradores → o pedido aparece em "Pedido de vinculação" → Aceitar → Permitir acesso
3. Se você tem login admin nos dois lados, fecha o ciclo sozinho em 2 minutos

O Google pode pedir confirmação de identidade (passkey/Touch ID) na hora de enviar o pedido — é normal.

A API do Google Ads é consumida através de um projeto do Google Cloud — é ele que fornece o OAuth. O formulário do passo 04 exige o project ID.

1. Crie (ou reaproveite) um projeto e anote o project ID
2. Habilite a Google Ads API: gcloud services enable googleads.googleapis.com --project=SEU_PROJETO (ou pela biblioteca de APIs no console)
3. Crie uma credencial OAuth (tipo "App para computador" serve para uso interno) em Google Auth Platform → Clientes

Na Central de API: Nível de acesso → Solicitar acesso básico. Abre o formulário support.google.com/adspolicy/contact/new_token_application.

Como respondemos (ferramenta interna de relatórios, somente leitura)

Enviou, aparece "The Google Ads API Compliance team has received your ticket". Prazo declarado: até 5 dias úteis.

Pré-requisito da verificação de marca (passo 06): fazer uma chamada de API usando o developer token + uma credencial OAuth do projeto. Detalhe da doc oficial que poupa horas: a chamada pode falhar — o que registra a associação é a tentativa autenticada.

TOKEN=$(gcloud auth print-access-token \
  --impersonate-service-account=SA@PROJETO.iam.gserviceaccount.com \
  --scopes=https://www.googleapis.com/auth/adwords)

curl -X GET \
  "https://googleads.googleapis.com/v24/customers:listAccessibleCustomers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "developer-token: SEU_TOKEN_22_CHARS"

Receber um erro de negócio (ex.: NOT_ADS_USER) está ótimo — a associação foi registrada. Dois detalhes de sintaxe que custam tempo: o método é GET (POST devolve 404 genérico) e a versão da API muda (v24 em jul/2026).

Com a aplicação pendente, a verificação de marca do projeto acelera a análise (o próprio formulário diz isso). É um checklist em Google Auth Platform:

1. Público-alvo: tipo de usuário Externo + status Em produção (obrigatório para esta análise, mesmo que o app seja interno — a doc do Google Ads é explícita)
2. Branding: nome do app, e-mail de suporte, página inicial, link de política de privacidade (sem ele o botão "Verificar marca" nem habilita) e domínio autorizado igual ao domínio das páginas
3. Clique Verificar marca (roda em ~5 min) e depois Publicar branding — o resultado verificado expira em 7 dias se não publicar

O robô verificador exige que a página inicial:

• Seja pública (sem login, sem gate)
• Explique a finalidade do app
• Tenha o mesmo nome que está no campo "Nome do app"

Solução que passou de primeira: uma landing dedicada do app (ex.: adsreports.suaagencia.com.br) com h1 idêntico ao nome do app, descrição honesta ("ferramenta interna, somente leitura, equipe própria") e link para a política de privacidade — mais uma página de política LGPD, ambas servidas por um worker minúsculo.

• A resposta chega no e-mail de contato da API (Central de API) — mantenha monitorado; ignorar aviso de compliance pode custar o acesso
• Enquanto espera, o token atual já funciona em contas de teste: dá pra montar e validar todo o pipeline (OAuth, GAQL, relatórios) e só trocar o customer ID no dia da aprovação
• Erro "developer token is only approved for use with test accounts" em produção = aprovação ainda não saiu

Básico vs. Standard — não caia nessa

O acesso básico dá 15.000 operações/dia, grátis, com a API inteira — mesmos relatórios, mesmo GAQL, mesmas mutações. Standard só muda a cota (sem teto diário). O e-mail de aprovação avisa: não peça Standard sem histórico de uso que encoste nos 15k/dia — pedidos sem necessidade demonstrada são negados. Pra referência: a rotina de relatórios de um cliente consome algumas centenas de operações/dia.

O e-mail de aprovação chegou. Agora falta transformar o token em acesso funcionando — e aqui mora a última pegadinha do processo.

a. Baixar o JSON do OAuth client

Guarde o arquivo fora de Downloads, com permissão restrita:

mkdir -p ~/.config/google-ads-mcp
mv ~/Downloads/client_secret_*.json ~/.config/google-ads-mcp/client_secret.json
chmod 600 ~/.config/google-ads-mcp/client_secret.json

b. Login ADC com o scope do Google Ads

gcloud auth application-default login \
  --client-id-file="$HOME/.config/google-ads-mcp/client_secret.json" \
  --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform

O navegador vai abrir a tela de consentimento com o nome do seu app (a marca que você verificou no passo 06) e — surpresa esperada — o aviso "O Google não verificou este app". É normal: você verificou a marca, não passou pela auditoria de escopos sensíveis (CASA), que só faz sentido pra apps distribuídos ao público. Como o desenvolvedor é você mesmo: Avançado → "Acessar [seu app] (não seguro)" → Permitir.

c. Testar sem intermediário (30 segundos)

# 1. Suas contas acessíveis (GET, não POST!)
TOKEN=$(gcloud auth application-default print-access-token)
curl -X GET \
  "https://googleads.googleapis.com/v24/customers:listAccessibleCustomers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "developer-token: SEU_TOKEN"

# 2. GAQL de verdade na conta do cliente
curl -X POST \
  "https://googleads.googleapis.com/v24/customers/CUSTOMER_ID/googleAds:searchStream" \
  -H "Authorization: Bearer $TOKEN" \
  -H "developer-token: SEU_TOKEN" \
  -H "login-customer-id: ID_DA_MCC_SEM_HIFENS" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT campaign.id, campaign.name, campaign.status FROM campaign"}'

Detalhes que custam minutos: o header login-customer-id é o ID da MCC, sem hífens (6778631413, não 677-863-1413) — e o customer ID da URL também vai sem hífens.

d. Registrar o MCP oficial no seu agente

Com tudo validado, o servidor MCP oficial vira ferramenta permanente. No Claude Code:

claude mcp add --scope user google-ads \
  -e GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/application_default_credentials.json" \
  -e GOOGLE_PROJECT_ID=SEU_PROJECT_ID \
  -e GOOGLE_ADS_DEVELOPER_TOKEN=SEU_TOKEN \
  -e GOOGLE_ADS_LOGIN_CUSTOMER_ID=ID_DA_MCC_SEM_HIFENS \
  -- pipx run --spec "git+https://github.com/googleads/google-ads-mcp.git" google-ads-mcp

(--scope user = disponível em qualquer pasta e qualquer sessão. Precisa do pipx: brew install pipx.)

Chegou o e-mail "Basic Access Approval"? Cole este prompt no seu agente (Claude Code ou similar, com acesso a terminal) e ele deixa a API funcionando de ponta a ponta. Preencha o bloco "MEUS DADOS" antes de enviar.

Meu developer token do Google Ads acabou de ser APROVADO para acesso
básico (recebi o e-mail "Basic Access Approval"). Você é meu operador
técnico: deixe a Google Ads API funcionando de ponta a ponta na minha
máquina, terminando com o MCP oficial registrado e uma consulta GAQL
real respondendo com dados da conta do meu cliente.

## MEUS DADOS (preenchi antes de te enviar)
- Developer token (22 chars, na Central de API da MCC): ___________
- ID da MCC: ___-___-____
- Customer ID da conta do cliente: ___-___-____
- Project ID do Google Cloud: ___________
- Já baixei o client_secret JSON do OAuth client?
  [sim, caminho: ___________ | não baixei / não sei]

## REGRAS INVIOLÁVEIS
1. Secrets NUNCA no chat: trabalhe com arquivos locais (chmod 600).
2. Login OAuth interativo quem roda sou eu — me entregue o comando
   pronto para colar e me diga exatamente o que aprovar no navegador.
3. Se algo falhar, diagnostique pelo corpo do erro real antes de
   tentar de novo (os erros da Ads API são descritivos).

## ROTEIRO
1. JSON do OAuth client. ARMADILHA: o Google só mostra/baixa o secret
   NO MOMENTO DA CRIAÇÃO — não existe re-download. Se eu não tenho o
   arquivo: me guie em console.cloud.google.com/auth/clients →
   abrir o client (tipo "App para computador"; crie um se não houver)
   → "+ Add secret" → baixar o JSON no diálogo (única chance).
2. Guardar seguro:
   mkdir -p ~/.config/google-ads-mcp
   mv ~/Downloads/client_secret_*.json ~/.config/google-ads-mcp/client_secret.json
   chmod 600 ~/.config/google-ads-mcp/client_secret.json
3. Login ADC (eu rodo):
   gcloud auth application-default login \
     --client-id-file="$HOME/.config/google-ads-mcp/client_secret.json" \
     --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform
   Aviso "O Google não verificou este app" é ESPERADO (marca
   verificada ≠ auditoria de escopos sensíveis): Avançado → Acessar
   (não seguro) → Permitir.
4. Smoke test via curl (descubra antes a versão vigente da API, vXX):
   a. GET https://googleads.googleapis.com/vXX/customers:listAccessibleCustomers
      com Authorization: Bearer $(gcloud auth application-default
      print-access-token) + header developer-token. É GET — POST
      devolve 404 genérico. Deve listar minhas contas.
   b. POST .../vXX/customers/CUSTOMER_ID/googleAds:searchStream com
      header login-customer-id = ID DA MCC SEM HÍFENS (customer ID da
      URL também sem hífens) e body:
      {"query": "SELECT campaign.id, campaign.name, campaign.status FROM campaign"}
5. Registrar o MCP oficial de forma permanente:
   claude mcp add --scope user google-ads \
     -e GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/application_default_credentials.json" \
     -e GOOGLE_PROJECT_ID=MEU_PROJECT_ID \
     -e GOOGLE_ADS_DEVELOPER_TOKEN=MEU_TOKEN \
     -e GOOGLE_ADS_LOGIN_CUSTOMER_ID=ID_MCC_SEM_HIFENS \
     -- pipx run --spec "git+https://github.com/googleads/google-ads-mcp.git" google-ads-mcp
   (Instale pipx antes se faltar: brew install pipx)
6. Pré-aqueça a instalação (pipx run ... baixa na primeira execução)
   e me avise que na PRÓXIMA sessão o servidor "google-ads" estará
   disponível com as tools list_accessible_customers, search (GAQL) e
   get_resource_metadata.

## CRITÉRIO DE SUCESSO (reporte cada um explicitamente)
(1) listAccessibleCustomers listando minhas contas;
(2) GAQL real na conta do cliente retornando campanhas;
(3) MCP "google-ads" registrado no escopo de usuário.

• Formulário de aplicação de acesso básico — o formulário do passo 04 (só em inglês)
• Verificação de marca — guia oficial — a doc do passo 06, incluindo o pré-requisito da chamada de associação
• Developer token e níveis de acesso — o que cada nível (teste, Explorer, básico, standard) permite
• google-ads-mcp — o servidor MCP oficial (read-only) pra usar o token depois de aprovado