Acesso à API do Google Ads em 2026: projetos do Cloud substituem os Developer Tokens

Desde 9 de setembro de 2026, o acesso à API do Google Ads é concedido por projeto do Google Cloud, e não mais por Developer Token. O que mudou, como configurar o acesso hoje e o que o guia de configuração de junho de 2026 ainda tem de correto.

O que mudou em 9 de setembro de 2026

Nosso guia de junho de 2026 sobre configuração, autenticação e operações de leitura e escrita da API do Google Ads foi construído em torno do Developer Token: solicitá-lo no API Center de uma conta de Gestor, pedir ali o acesso Basic e enviar o token em cada chamada. Três meses depois, essa base mudou. A própria documentação do Google afirma agora com clareza: "Developer tokens were sunset on September 9, 2026."

A decisão de acesso em si não desapareceu – ela mudou de lugar. O nível de acesso à API é agora determinado pelo projeto do Google Cloud usado para gerar as credenciais OAuth, e os acessos existentes foram migrados automaticamente para projetos do Cloud. As solicitações não são mais feitas no API Center: o Google pede que os desenvolvedores não solicitem ali um Developer Token e peçam o acesso na página Google Ads API Overview do Google Cloud Console. As solicitações Basic que ainda estavam pendentes no API Center foram encerradas e precisam ser reenviadas pelo Cloud Console.

O guia de junho permanece online como foi publicado, com uma nota datada no topo. Este acompanhamento descreve o que é diferente hoje e remete ao guia onde o material anterior ainda se aplica.

Os níveis de acesso agora pertencem ao projeto do Cloud

Os níveis são os conhecidos, com um acréscimo. Os limites abaixo vêm da documentação do Google sobre níveis de acesso, em outubro de 2026:

Nível de acesso	Contas de produção	Operações diárias
Test	Não, apenas contas de teste	15.000
Explorer	Sim	2.880 em contas de produção
Basic	Sim	15.000
Standard	Sim	Sem limite geral (serviços individuais ainda podem ser limitados)

O Explorer é a porta de entrada prática. Segundo o Google, uma solicitação feita pelo Cloud Console é analisada automaticamente e, na maioria dos casos, elevada ao acesso Explorer – suficiente para relatórios internos e automação moderada em suas próprias contas. Basic e Standard ainda exigem uma análise, e ambos têm agora um novo pré-requisito: a verificação de marca do projeto do Google Cloud. O Standard envolve ainda uma auditoria manual.

O problema é que a verificação de marca é fácil de ignorar quando a configuração técnica já funciona. Um script com acesso Explorer se comportará corretamente até atingir o limite diário; por isso, planeje a verificação antes de o volume chegar, não depois.

Configurando o acesso hoje

A sequência é mais curta do que antes, porque o projeto do Cloud é agora o único lugar em que o acesso é decidido:

Crie um projeto do Google Cloud ou escolha aquele que será o titular da sua integração com o Google Ads. Não é necessário faturamento para isso.
Ative a API do Google Ads na Biblioteca de APIs do projeto.
Crie as credenciais nesse mesmo projeto – um cliente OAuth para acesso baseado em usuário ou uma conta de serviço com chave JSON.
Solicite o acesso na página Google Ads API Overview do Cloud Console e conclua a verificação de marca se precisar do acesso Basic ou Standard.

O que importa aqui é a etapa 3. Como o acesso acompanha o projeto que emitiu as credenciais OAuth, credenciais de um segundo projeto, sem relação com o primeiro, não herdam o nível de acesso solicitado. Equipes que criaram clientes de teste em projetos separados ao longo dos anos devem consolidá-los antes de contar com acesso de produção.

Os detalhes de OAuth do guia de junho – o escopo adwords, o acesso offline para obter um refresh token, os motivos pelos quais um refresh token deixa de funcionar – permanecem inalterados e continuam válidos.

Autenticação e configuração

O Developer Token agora é opcional na prática. O Google informa que é possível continuar enviando-o nos cabeçalhos das requisições, mas os servidores o ignoram, e espera-se que uma futura versão principal da API o rejeite. A versão 32.0.0 da biblioteca oficial para Python removeu a verificação que exigia um token na configuração.

Um google-ads.yaml mínimo para OAuth baseado em usuário fica, portanto, assim:

client_id: YOUR_CLIENT_ID.apps.googleusercontent.com
client_secret: YOUR_CLIENT_SECRET
refresh_token: YOUR_REFRESH_TOKEN
login_customer_id: "1234567890"
use_proto_plus: true

Para uma conta de serviço, json_key_file_path substitui as três chaves OAuth, opcionalmente combinada com impersonated_email. Toda chave também pode ser definida como variável de ambiente com o prefixo GOOGLE_ADS_, por exemplo GOOGLE_ADS_JSON_KEY_FILE_PATH – a escolha mais sensata em servidores, onde os arquivos de configuração tendem a acabar em backups e repositórios.

login_customer_id mantém o significado anterior. Ao acessar uma conta de cliente por meio de uma conta de Gestor, ele indica essa conta de Gestor (somente dígitos, sem hífens). Sem ele, essas chamadas falham com USER_PERMISSION_DENIED.

Versões e a biblioteca Python

A fixação de versão merece mais atenção do que costuma receber. O guia de junho usava version="v22", e essa versão não está mais disponível: a versão 33.0.0 da biblioteca Python google-ads removeu a v21 e a v22. Em outubro de 2026, a versão atual da API é a v26 (lançada em 14 de outubro de 2026), e a biblioteca 34.0.0 adiciona suporte a ela.

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage("google-ads.yaml", version="v26")

Fixar a versão explicitamente continua sendo o padrão correto. Na prática, um cliente sem versão fixada muda de comportamento silenciosamente na próxima atualização da biblioteca, e o Google desativa versões da API segundo um cronograma publicado – uma versão fixada ao menos transforma essa desativação em uma mudança planejada, em vez de uma surpresa.

A declaração de publicidade política da UE

Um requisito pegou muitas integrações existentes de surpresa: o campo contains_eu_political_advertising do recurso Campaign. Nas versões da API anteriores à v26, toda nova campanha precisa declará-lo. Desde 1º de abril de 2026, as chamadas mutate falham com EU_POLITICAL_ADVERTISING_DECLARATION_REQUIRED quando uma conta ainda contém campanhas sem declaração. A versão 26 flexibiliza a regra: o campo passa a ser opcional para campanhas que não segmentam a UE de forma positiva.

Declará-lo explicitamente custa uma linha e mantém o código de criação de campanhas válido em todas as versões:

campaign.contains_eu_political_advertising = (
    client.enums.EuPoliticalAdvertisingStatusEnum.DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING
)

O que continua valendo do guia de junho

A maior parte do passo a passo anterior trata de trabalhar com a API, e não de obter acesso a ela, e essa parte envelheceu bem. As consultas de leitura GAQL, o padrão validate_only para testar operações de escrita com segurança, o tratamento explícito de update_mask e a separação entre conta de Gestor, projeto do Cloud e conta de destino se aplicam como descritos. O que deixou de valer é o caminho de acesso: o API Center, a solicitação do Developer Token e o diagrama de arquitetura baseado em token.

Uma boa integração – script interno ou ferramenta voltada a clientes – trata o acesso como configuração pertencente a um projeto do Cloud claramente identificado. Essa já era uma prática sensata antes de setembro de 2026. Desde então, é a forma como o Google define o acesso.