Como sincronizamos as palavras-chave ativas do Google Ads com a planilha de planejamento usando Google Ads API, Zapier MCP e IA

O problema: a planilha de planejamento não refletia mais a conta

Em contas de Google Ads com várias campanhas de aquisição, é comum o planejamento viver em uma planilha. Cada aba representa uma campanha, cada bloco representa um grupo de anúncios, e cada grupo tem seus títulos, descrições e a lista de palavras-chave.

Com o tempo, a conta e a planilha se separam. Palavras são pausadas, outras são adicionadas direto no painel, correspondências mudam e grupos novos surgem. O documento que deveria ser a fonte de verdade vira um retrato de meses atrás.

Neste case, a conta de uma plataforma de cursos gratuitos para educadores tinha 7 campanhas de Search e 22 grupos de anúncios ativos. A planilha de planejamento era usada pelo cliente para aprovar anúncios e acompanhar a estrutura.

O pedido foi direto: atualizar somente as palavras-chave da planilha para que ela refletisse o que estava ativo no Google Ads, sem mexer em mais nada.

O projeto teve duas fases:

1. Primeira fase: uma atualização pontual a partir de um CSV exportado.

2. Segunda fase: uma rotina recorrente, sem CSV, executada por um único prompt.

Este case documenta as duas, com foco na versão final.

Diagnóstico: o tamanho da divergência

Antes de escrever qualquer coisa, cruzamos a planilha com a conta. O resultado mostrou que a divergência não era pontual:

• Das 379 palavras listadas na planilha, apenas 201 batiam exatamente com a conta (mesma palavra, mesmo grupo, mesma correspondência).

• 119 existiam na conta, mas com outro tipo de correspondência. Na maioria dos casos, as exatas previstas no planejamento tinham subido como frase.

• 45 não existiam mais no grupo e 14 estavam pausadas.

• Um grupo inteiro havia sido criado como cópia de um grupo vizinho, com as palavras erradas, e a lista planejada nunca foi subida.

• Dois blocos da planilha tinham a lista de outro grupo colada por engano.

O cruzamento também revelou problemas na própria conta:

• termos de marca distribuídos em três grupos diferentes;

• 56 palavras duplicadas entre grupos, competindo no mesmo leilão;

• um título de anúncio cadastrado como palavra-chave.

Fase 1: a primeira versão, com CSV

Na primeira execução, a extração foi feita com o relatório de palavras-chave da Rede de Pesquisa exportado em CSV. O processamento em Python (pandas) tratou três particularidades do export:

• Cabeçalho e totais: linhas de cabeçalho e de totais agregados.

• Formato numérico brasileiro: ponto como separador de milhar e vírgula decimal.

• Marcação no texto: a marcação de correspondência já vem no próprio texto da palavra (aspas e colchetes). Ela precisa ser removida antes de reformatar.

O critério de "palavra ativa" foi status Ativado dentro de um grupo não pausado. Uma palavra ativada dentro de um grupo pausado não aciona nada e, por isso, fica de fora.

A versão funcionou, mas tinha dois pontos fracos para uma rotina:

• Export manual: dependia de alguém exportar o CSV a cada atualização.

• Campanhas pausadas: o relatório não traz o status da campanha, então campanhas pausadas exigiam tratamento à parte.

Fase 2: arquitetura final, sem CSV

A versão recorrente tem quatro camadas:

1. Extração: uma code action no Zapier MCP consulta a Google Ads API e devolve as palavras ativas em formato compacto.

2. Mapeamento: leitura da planilha pela Google Sheets API para localizar a célula exata do bloco "Palavras" de cada grupo.

3. Escrita: chamada única ao método values:batchUpdate da Google Sheets API.

4. Validação: releitura das faixas alteradas e relatório de divergências.

A IA atua como agente de execução. Ela chama as ferramentas, cruza os dados, monta o payload e valida o resultado. As regras da rotina ficam registradas na memória do projeto, então basta um prompt para rodar.

Por que o Zapier MCP

O conector nativo do Google Drive permite ler e criar arquivos, mas não editar células de uma planilha existente. Criar uma planilha nova quebraria o link que o cliente já usava.

O Zapier MCP resolve as duas pontas com as conexões OAuth da própria conta Zapier:

• Google Sheets: as ações "Make API GET Request" e "Make API Mutating Request" acessam a API diretamente.

• Google Ads: uma code action customizada faz a extração.

Não é preciso criar Zaps, gerar credenciais nem manter servidor.

👉 Zapier MCP

Etapa 1: extração pela Google Ads API

A primeira tentativa foi chamar a API do Google Ads direto pela ação genérica de requisição. Funcionou, mas com um problema prático.

A resposta é muito verbosa. Cada palavra vem com cerca de 450 caracteres de metadados (resourceName de campanha, grupo e critério). Com 300 palavras, cada consulta passava de 130 KB. A ordenação por impressões exigia uma segunda consulta do mesmo tamanho.

A solução foi criar uma code action no app Google Ads do Zapier, chamada ftv_keywords_ativas. Ela roda duas consultas GAQL, junta os resultados e devolve uma linha por palavra.

Consulta 1 (palavras ativas):

SELECT campaign.name, ad_group.name, ad_group.id,
       ad_group_criterion.criterion_id,
       ad_group_criterion.keyword.text,
       ad_group_criterion.keyword.match_type
FROM ad_group_criterion
WHERE campaign.status = 'ENABLED'
  AND ad_group.status = 'ENABLED'
  AND ad_group_criterion.status = 'ENABLED'
  AND ad_group_criterion.negative = FALSE
  AND ad_group_criterion.type = 'KEYWORD'
  AND campaign.advertising_channel_type = 'SEARCH'

SELECT campaign.name, ad_group.name, ad_group.id,
       ad_group_criterion.criterion_id,
       ad_group_criterion.keyword.text,
       ad_group_criterion.keyword.match_type
FROM ad_group_criterion
WHERE campaign.status = 'ENABLED'
  AND ad_group.status = 'ENABLED'
  AND ad_group_criterion.status = 'ENABLED'
  AND ad_group_criterion.negative = FALSE
  AND ad_group_criterion.type = 'KEYWORD'
  AND campaign.advertising_channel_type = 'SEARCH'

SELECT campaign.name, ad_group.name, ad_group.id,
       ad_group_criterion.criterion_id,
       ad_group_criterion.keyword.text,
       ad_group_criterion.keyword.match_type
FROM ad_group_criterion
WHERE campaign.status = 'ENABLED'
  AND ad_group.status = 'ENABLED'
  AND ad_group_criterion.status = 'ENABLED'
  AND ad_group_criterion.negative = FALSE
  AND ad_group_criterion.type = 'KEYWORD'
  AND campaign.advertising_channel_type = 'SEARCH'

Consulta 2 (impressões para ordenação): keyword_view com metrics.impressions, filtrado por segments.date desde o início da conta e agregado por grupo + critério. Palavras sem linha na segunda consulta recebem zero impressões.

A saída da code action é texto separado por tabulação: campanha, grupo, palavra já formatada e impressões. Na formatação, ampla fica sem marcação, frase entre aspas e exata entre colchetes.

Resultado: uma chamada, cerca de 11 segundos, 298 palavras em 22 grupos. O conjunto bateu exatamente com o cruzamento feito na fase 1 via CSV.

Detalhe de acesso: MCC x conta direta

A consulta usando o header login-customer-id da MCC foi negada, porque o login conectado no Zapier não tinha permissão na MCC pela API. A mesma consulta direto no ID da conta funcionou.

Para rotinas de leitura em uma conta específica, o acesso direto é suficiente e evita mexer em permissões de MCC.

Etapa 2: mapeamento das células na planilha

A planilha não é uma tabela. Ela é um formulário repetido em blocos, e cada bloco segue a mesma sequência:

• Campanha

• Grupo

• Anúncio

• Link

• 15 títulos

• 4 descrições

• "Palavras"

• lista

Há exceções:

• grupos com dois anúncios, que compartilham um único bloco de palavras no fim;

• blocos com uma palavra por linha;

• um grupo sem bloco de palavras.

Por isso, a cada execução a planilha é relida pela API, aba por aba, para confirmar a linha de cada bloco. Posições de execuções anteriores nunca são reaproveitadas, porque alguém pode ter inserido linhas ou anúncios desde a última rodada.

GET https://sheets.googleapis.com/v4/spreadsheets/{ID}/values/'{ABA}'!B1:D300?majorDimension=COLUMNS

GET https://sheets.googleapis.com/v4/spreadsheets/{ID}/values/'{ABA}'!B1:D300?majorDimension=COLUMNS

GET https://sheets.googleapis.com/v4/spreadsheets/{ID}/values/'{ABA}'!B1:D300?majorDimension=COLUMNS

Etapa 3: escrita com uma única chamada

Com o mapa de células confirmado, todo o conteúdo vai em uma única chamada values:batchUpdate. Na execução de referência, foram 23 intervalos, 41 células e 7 abas.

{
  "valueInputOption": "RAW",
  "data": [
    {
      "range": "'{ABA_CAMPANHA}'!B70:B75",
      "values": [["palavra ampla\n\"palavra de frase\"\n[palavra exata]"], [""], [""], [""], [""], [""]]
    }
  ]
}

{
  "valueInputOption": "RAW",
  "data": [
    {
      "range": "'{ABA_CAMPANHA}'!B70:B75",
      "values": [["palavra ampla\n\"palavra de frase\"\n[palavra exata]"], [""], [""], [""], [""], [""]]
    }
  ]
}

{
  "valueInputOption": "RAW",
  "data": [
    {
      "range": "'{ABA_CAMPANHA}'!B70:B75",
      "values": [["palavra ampla\n\"palavra de frase\"\n[palavra exata]"], [""], [""], [""], [""], [""]]
    }
  ]
}

👉 Documentação do método values:batchUpdate

Decisões técnicas que fazem diferença

valueInputOption RAW em vez de USER_ENTERED: com USER_ENTERED, o Sheets interpreta o conteúdo como se fosse digitado na interface. Textos podem virar números ou datas, e valores iniciados por sinal de igual viram fórmula. Com RAW, o texto é gravado exatamente como enviado.

Lista em célula única com quebra de linha: nos blocos com uma palavra por linha, a lista nova tinha mais itens que as linhas existentes. Para não inserir linhas e deslocar a aba, a lista inteira vai para a primeira célula e as demais células do bloco são limpas.

Chamada única: o batchUpdate é aplicado como uma operação só. Isso evita que a planilha fique em estado intermediário.

Escopo fechado: títulos, descrições, contadores de caracteres, links, rateio e sitelinks nunca entram no payload.

Ordem por impressões: cada lista é ordenada por impressões acumuladas. Assim, quem lê o planejamento vê primeiro os termos que movimentam o grupo.

Etapa 4: validação e relatório de divergências

Depois da escrita, as faixas alteradas são relidas para confirmar dois pontos:

• o conteúdo está na célula correta;

• as células vizinhas continuam intactas.

Antes da escrita, a rotina também compara conta e planilha e reporta:

• grupos ativos na conta sem bloco na planilha;

• blocos na planilha cujo grupo não tem mais palavras ativas;

• nomes de campanha ou grupo divergentes entre os dois lados.

Nesses casos, a rotina não cria estrutura sozinha. Ela avisa e espera decisão.

O que muda quando a conta muda

• Novo anúncio em um grupo existente: nada muda. Palavras-chave são do grupo, não do anúncio.

• Palavras novas, pausadas ou removidas em grupos existentes: é exatamente o que a rotina atualiza.

• Grupo novo com bloco já criado na planilha: entra automaticamente, desde que o nome do grupo na planilha seja igual ao da conta.

• Grupo novo sem bloco na planilha: a rotina avisa. A estrutura do bloco é criada por quem mantém o planejamento.

• Grupo ou campanha renomeados: aparecem como divergência no relatório antes da escrita.

O prompt de atualização

Com as regras registradas na memória do projeto, o prompt do dia a dia é curto:

Atualiza as palavras da planilha da FTV

Atualiza as palavras da planilha da FTV

Atualiza as palavras da planilha da FTV

Para quem quer replicar em outro projeto ou em uma conversa sem memória configurada, esta é a versão completa:

Atualize os blocos "Palavras" da planilha {NOME_DA_PLANILHA} (ID {ID_DA_PLANILHA}) com as palavras-chave ativas da conta Google Ads {ID_DA_CONTA}.

Regras:
1. Extraia as palavras pela code action {NOME_DA_CODE_ACTION} do Zapier (app Google Ads). Considere ativa a palavra com campanha, grupo e palavra ativos, sem negativas, apenas campanhas de Search.
2. Releia a planilha pela Google Sheets API (Zapier, conexão {EMAIL_DA_CONEXAO}) e localize, em cada aba, a célula logo abaixo do rótulo "Palavras" de cada grupo. Não reaproveite posições de execuções anteriores.
3. Formato: ampla sem marcação, frase entre aspas, exata entre colchetes. Lista em uma única célula, uma palavra por linha, ordenada por impressões decrescentes. Em blocos com uma palavra por linha, grave a lista na primeira célula e limpe as demais do bloco.
4. Antes de escrever, me mostre as divergências: grupos ativos sem bloco na planilha, blocos sem grupo ativo e nomes divergentes. Não crie estrutura nova sem minha aprovação.
5. Escreva tudo em uma única chamada values:batchUpdate com valueInputOption RAW, alterando somente as células de palavras.
6. Releia as faixas alteradas e confirme o resultado

Atualize os blocos "Palavras" da planilha {NOME_DA_PLANILHA} (ID {ID_DA_PLANILHA}) com as palavras-chave ativas da conta Google Ads {ID_DA_CONTA}.

Regras:
1. Extraia as palavras pela code action {NOME_DA_CODE_ACTION} do Zapier (app Google Ads). Considere ativa a palavra com campanha, grupo e palavra ativos, sem negativas, apenas campanhas de Search.
2. Releia a planilha pela Google Sheets API (Zapier, conexão {EMAIL_DA_CONEXAO}) e localize, em cada aba, a célula logo abaixo do rótulo "Palavras" de cada grupo. Não reaproveite posições de execuções anteriores.
3. Formato: ampla sem marcação, frase entre aspas, exata entre colchetes. Lista em uma única célula, uma palavra por linha, ordenada por impressões decrescentes. Em blocos com uma palavra por linha, grave a lista na primeira célula e limpe as demais do bloco.
4. Antes de escrever, me mostre as divergências: grupos ativos sem bloco na planilha, blocos sem grupo ativo e nomes divergentes. Não crie estrutura nova sem minha aprovação.
5. Escreva tudo em uma única chamada values:batchUpdate com valueInputOption RAW, alterando somente as células de palavras.
6. Releia as faixas alteradas e confirme o resultado

Atualize os blocos "Palavras" da planilha {NOME_DA_PLANILHA} (ID {ID_DA_PLANILHA}) com as palavras-chave ativas da conta Google Ads {ID_DA_CONTA}.

Regras:
1. Extraia as palavras pela code action {NOME_DA_CODE_ACTION} do Zapier (app Google Ads). Considere ativa a palavra com campanha, grupo e palavra ativos, sem negativas, apenas campanhas de Search.
2. Releia a planilha pela Google Sheets API (Zapier, conexão {EMAIL_DA_CONEXAO}) e localize, em cada aba, a célula logo abaixo do rótulo "Palavras" de cada grupo. Não reaproveite posições de execuções anteriores.
3. Formato: ampla sem marcação, frase entre aspas, exata entre colchetes. Lista em uma única célula, uma palavra por linha, ordenada por impressões decrescentes. Em blocos com uma palavra por linha, grave a lista na primeira célula e limpe as demais do bloco.
4. Antes de escrever, me mostre as divergências: grupos ativos sem bloco na planilha, blocos sem grupo ativo e nomes divergentes. Não crie estrutura nova sem minha aprovação.
5. Escreva tudo em uma única chamada values:batchUpdate com valueInputOption RAW, alterando somente as células de palavras.
6. Releia as faixas alteradas e confirme o resultado

Custo da rotina

No Zapier MCP, cada chamada bem-sucedida consome duas tasks do plano, e chamadas com erro não contam. Cada execução completa usa cerca de 10 chamadas:

• 1 extração;

• leituras da planilha;

• 1 escrita;

• conferência.

Isso dá entre 15 e 20 tasks por rodada. Para uma ou duas atualizações por mês, o plano Free do Zapier (100 tasks mensais) atende com folga. A code action fica salva na conta e não consome nada enquanto não é executada.

Para frequências maiores, a alternativa sem custo recorrente é rodar o mesmo fluxo em um script Python agendado em servidor próprio, com conta de serviço do Google na Sheets API e acesso direto à Google Ads API.

Resultados

• Arquivo original: planilha atualizada no mesmo link, sem cópias.

• Cobertura: 298 palavras ativas refletidas em 22 grupos e 7 abas.

• Escrita: uma única chamada de API, com 41 células alteradas e nenhuma outra informação modificada.

• Rotina: de um processo manual dependente de export, para um prompt de uma linha.

• Problemas estruturais da conta identificados: grupo com palavras de outro tema, marca distribuída em três grupos, grupo com zero impressões por "raramente exibido", 56 duplicidades e um título de anúncio cadastrado como palavra-chave.

Lições do case

Planilha de planejamento sem sincronização vira documentação histórica. Se a conta é editada direto no painel, a planilha precisa de uma rotina de atualização.

O cruzamento vale mais que a atualização. A atualização resolveu o pedido. O cruzamento mostrou onde a estrutura da conta tinha se desviado do planejamento, e isso gerou um plano de correção.

Tire a etapa manual antes de automatizar o resto. O CSV resolveu a primeira vez. A rotina só ficou viável quando a extração passou a vir direto da API.

Resposta compacta é parte da arquitetura. A code action reduziu a extração de duas chamadas com mais de 260 KB para uma chamada com cerca de 20 KB. Isso deixou o fluxo mais rápido, mais barato e menos sujeito a erro.

Agentes de IA funcionam melhor com escopo fechado e aprovação por etapa. O fluxo seguiu planejamento, aprovação, execução linear e validação. Nenhuma escrita foi feita sem o mapa de células confirmado.

Quer aplicar isso na sua conta?

A Ad Rock Digital Mkt trabalha com gestão de Google Ads, automação e integrações com IA para organizações que precisam de estrutura, rastreabilidade e decisões baseadas em dados.