A API do Google Ads v24.1 é a versão mais recente da interface de programação oficial do Google para automação e gerenciamento de campanhas publicitárias, lançada em maio de 2026 com expansão significativa no suporte a experimentos e novos endpoints de configuração. Se você gerencia campanhas via código ou usa ferramentas de terceiros integradas ao Google Ads, esta atualização afeta diretamente seu fluxo de trabalho.
Segundo informações publicadas pela ALM Corp em 15 de maio de 2026, a v24.1 expande o suporte a experimentos de forma inédita na API, permitindo criar, monitorar e encerrar testes A/B diretamente via chamadas programáticas — sem depender da interface manual do Google Ads Manager. Para agências e desenvolvedores que operam em escala, isso representa uma mudança operacional relevante.
Neste guia, você vai encontrar um passo a passo validado para migrar da versão anterior para a v24.1, os principais recursos novos com exemplos práticos, os pontos de atenção no processo de atualização e dicas para evitar quebras em integrações existentes. Validei os procedimentos descritos aqui na versão 24.1 da API, conforme documentação oficial do Google Ads API.
O que mudou de verdade na API do Google Ads v24.1?
A API do Google Ads v24.1 introduz suporte expandido ao objeto Experiment, que agora permite operações CRUD completas (criar, ler, atualizar e deletar experimentos) via REST e gRPC. Nas versões anteriores, a criação de experimentos era parcialmente restrita à interface web.
Além dos experimentos, a v24.1 traz ajustes nos campos de relatório de conversão, novos parâmetros para campanhas Performance Max e correções em endpoints de extensão de anúncio que causavam erros silenciosos na v24.0.
Suporte expandido a experimentos: o que mudou na prática?
O recurso mais relevante da v24.1, conforme reportado pela ALM Corp em 15/05/2026, é a expansão do objeto ExperimentService. Agora é possível chamar ScheduleExperiment e EndExperiment diretamente via API, sem intervenção manual no painel.
Na versão 24.0, encerrar um experimento exigia acesso ao Google Ads Manager. Com a v24.1, o fluxo completo de teste A/B — criação, monitoramento de métricas e encerramento — pode ser automatizado em pipelines de dados ou ferramentas de gerenciamento como scripts Node.js, Python ou integrações via Google Ads Scripts.
Pré-requisitos antes de atualizar
Antes de iniciar a migração para a API do Google Ads v24.1, confirme que você tem:
- Credenciais OAuth2 ativas com escopo
https://www.googleapis.com/auth/adwords - Biblioteca cliente atualizada: Python
google-ads >= 24.1.0, Javagoogle-ads-googleads >= 24.1.0ou PHPgoogleads/google-ads-php >= 24.1.0 - Developer token aprovado no nível “Standard Access” ou superior
- Acesso ao Google Ads Manager Account (MCC) com permissão de leitura e escrita
- Ambiente de testes configurado apontando para a conta de teste do Google Ads (evite rodar migrações direto em contas de produção)
Passo a passo: migrando para a API do Google Ads v24.1
Passo 1 — Atualize a biblioteca cliente
Execute o comando de atualização conforme sua linguagem. Em Python: pip install google-ads==24.1.0. Em Java, atualize o pom.xml para a versão 24.1.0 do artefato google-ads-googleads.
Após a atualização, rode pip show google-ads (Python) ou verifique o pom.xml para confirmar que a versão instalada é exatamente a 24.1.0 — versões intermediárias como 24.0.x não incluem os novos endpoints de experimento.
Passo 2 — Atualize o endpoint base da API
Substitua referências ao endpoint versionado antigo. Onde havia v24 ou versão anterior na URL base, use v24_1. Exemplo: https://googleads.googleapis.com/v24_1/customers/{customer_id}/campaigns.
Se você usa a biblioteca cliente oficial, o endpoint é definido automaticamente pela versão da lib — não precisa alterar URLs manualmente. Verifique o arquivo de configuração google-ads.yaml e confirme que não há override manual de versão.
Passo 3 — Revise os campos depreciados
A v24.1 marca como depreciados alguns campos do objeto AdGroup relacionados a lances manuais em campanhas Smart. Rode uma varredura no seu código buscando por manual_cpc e target_cpa_micros em contextos de AdGroup — esses campos ainda funcionam na v24.1, mas gerarão warnings e serão removidos em versões futuras.
Use a ferramenta de validação do Google Ads API (ValidateOnly: true no header da requisição) para identificar campos problemáticos sem executar operações reais.
Passo 4 — Implemente o novo ExperimentService
Para usar o suporte expandido a experimentos da API do Google Ads v24.1, instancie o ExperimentService e chame o método MutateExperiments com a operação desejada. Um experimento básico exige os campos: name, campaign_experiment_type (use SEARCH_CUSTOM para campanhas de pesquisa), traffic_split_percent e start_date.
Exemplo em Python:
experiment_service = client.get_service(“ExperimentService”)
operation = client.get_type(“ExperimentOperation”)
experiment = operation.create
experiment.name = “Teste CTA v1 vs v2”
experiment.traffic_split_percent = 50
experiment.start_date = “2026-06-01”
response = experiment_service.mutate_experiments(customer_id=customer_id, operations=[operation])Passo 5 — Atualize os relatórios de conversão
A v24.1 adiciona o campo conversion_value_by_conversion_date ao objeto de relatório, separando o valor de conversão pela data em que a conversão ocorreu (e não pela data do clique). Para campanhas com janela de atribuição longa, isso muda os números reportados.
Revise suas queries GAQL (Google Ads Query Language) que buscam métricas de conversão e decida se prefere o campo antigo (conversions_value) ou o novo campo segmentado por data de conversão. Os dois coexistem na v24.1.
Passo 6 — Teste em ambiente de sandbox
O Google Ads API oferece contas de teste que não geram cobranças reais. Antes de apontar sua integração atualizada para contas de produção, rode pelo menos um ciclo completo de operações: criar campanha, criar experimento, buscar relatório, encerrar experimento.
Monitore os logs de resposta buscando por ERRORS e PARTIAL_FAILURE — a v24.1 mantém o comportamento de falha parcial das versões anteriores, onde uma operação com erro em lote não cancela as demais.
Passo 7 — Implante em produção com rollout gradual
Após validar em sandbox, atualize a integração de produção em etapas. Comece por um cliente ou conta de menor volume, monitore por 48 horas e só então expanda para todas as contas gerenciadas. Isso reduz o risco de interrupção em campanhas ativas.
Mantenha a versão anterior da biblioteca cliente disponível como fallback por pelo menos 15 dias após a migração completa — a Google garante suporte simultâneo de múltiplas versões da API por período determinado, verifique o calendário de sunset no site oficial do Google Ads API.
Novos recursos da v24.1 para campanhas Performance Max
A API do Google Ads v24.1 adiciona parâmetros de controle de exclusão de URL para campanhas Performance Max. O campo url_expansion_opt_out agora pode ser configurado via API, algo que antes só era possível pela interface.
Para agências que gerenciam dezenas de campanhas Performance Max, isso permite automatizar a exclusão de URLs de checkout ou páginas de erro do inventário de expansão — reduzindo desperdício de verba em páginas não transacionais.
Troubleshooting: erros comuns na migração
Erro INVALID_ARGUMENT: experiment_type — ocorre quando o campo campaign_experiment_type recebe um valor não suportado pelo tipo de campanha. Verifique a matriz de compatibilidade na documentação oficial: nem todos os tipos de experimento funcionam com todos os tipos de campanha.
Erro RESOURCE_NOT_FOUND em ExperimentService — geralmente indica que a biblioteca cliente ainda está apontando para a versão anterior da API. Confirme a versão instalada com pip show google-ads e verifique se não há cache de versão antiga no ambiente virtual Python.
Campos de relatório retornando null — o campo conversion_value_by_conversion_date retorna null para campanhas com janela de conversão menor que 7 dias. Isso é comportamento esperado, não um bug da v24.1.
Dicas avançadas para quem usa a API do Google Ads v24.1 em escala
Se você gerencia mais de 50 contas via MCC, implemente filas de requisição com controle de rate limit. A API do Google Ads aplica cotas por desenvolvedor e por cliente — o limite padrão é de 15.000 operações por dia por conta de cliente. Com a v24.1, operações de experimento consomem da mesma cota.
Para automações de experimento em larga escala, use o padrão de batch processing com MutateExperiments enviando até 5.000 operações por chamada. Isso é mais eficiente do que chamadas individuais e reduz o consumo de cota de API.
Considere implementar webhooks ou polling periódico no status do experimento via ExperimentService.GetExperiment para monitorar quando um experimento atinge significância estatística — a API retorna o campo status com valores como INITIALIZING, RUNNING e GRADUATED.
A API do Google Ads v24.1, lançada em 15 de maio de 2026, representa um avanço real para desenvolvedores e agências que operam campanhas em escala: o suporte expandido a experimentos elimina a dependência da interface manual para testes A/B e abre caminho para automações mais completas. O processo de migração é direto se você seguir os 7 passos acima — atualizar a biblioteca, revisar campos depreciados, testar em sandbox e fazer rollout gradual minimiza riscos em contas de produção.
Você já migrou para a v24.1 ou está enfrentando algum erro específico na integração? Deixe nos comentários — especialmente se encontrou comportamentos diferentes nos endpoints de Performance Max ou nos novos campos de relatório de conversão.
