Como criar automações usando Google Apps Script

Você sabe aquela sensação de ter que repetir a mesma tarefa chata, manual e propensa a erros, dia após dia? Aquela que você pensa: "Não é possível que ninguém tenha automatizado isso ainda?" Pois é, eu vivo isso. E, mais do que isso, vivo resolvendo isso.

Desde buscar dados de uma API, jogar numa planilha, formatar, até disparar um e-mail com um resumo gerado automaticamente, eu já perdi a conta de quantas horas economizei – e quantas vezes salvei meu pescoço – usando o Google Apps Script. É aquela ferramenta que vive ali, escondida, mas que se torna o seu canivete suíço quando o assunto é dar um jeito nas coisas dentro do ecossistema Google, especialmente com o Google Sheets.

Não sou nenhum guru, nem vendi minha alma para a consultoria. Eu sou o cara que quebra a cabeça pra fazer as coisas funcionarem. O que eu vou compartilhar aqui é o que aprendi no campo de batalha, nos erros e acertos diários, transformando processos maçantes em algo que roda sozinho enquanto eu tomo meu café.

O que é Google Apps Script e por que ele te salva?

Pense no Google Apps Script como um JavaScript que vive dentro dos produtos Google. Ele te permite controlar planilhas, documentos, formulários, Gmail e até mesmo se comunicar com APIs externas, tudo de dentro do seu navegador. A grande sacada é que ele te dá acesso programático a essas ferramentas que você já usa todo dia. Para mim, a principal vantagem é a proximidade com o Google Sheets.

Eu sempre usei Python para automações mais pesadas e complexas, especialmente quando envolvia muitos dados ou lógicas mais sofisticadas fora do ambiente Google. Mas, para aquelas tarefas do dia a dia, onde os dados já estão no Sheets ou precisam ir para lá, e onde a equipe já está usando o Google Drive, o Apps Script é imbatível pela simplicidade de deploy e integração. Não preciso me preocupar com ambientes virtuais, dependências ou onde hospedar o script; ele só funciona.

Meu primeiro contato com Apps Script: a dor do relatório manual

Lembro de uma época em que todo final de semana eu tinha que consolidar relatórios de vendas de várias fontes, copiar e colar tudo em uma planilha mestre, fazer uns cálculos básicos e enviar para a diretoria na segunda-feira. Levava umas 3-4 horas só nesse processo repetitivo. Era um inferno. Um belo dia, esgotado de tanto CTRL+C, CTRL+V, decidi que não dava mais.

Foi aí que comecei a fuçar no Apps Script. Meu objetivo era simples: buscar dados de uma API interna, jogar tudo em uma aba do Sheets, depois processar esses dados para gerar um resumo na outra aba e, finalmente, enviar um e-mail com esse resumo. Parecia um bicho de sete cabeças no começo, mas o resultado final foi libertador.

Começando do zero: Onde o código mora?

Para começar, abra sua planilha do Google Sheets. Vá em Extensões > Apps Script. Isso vai abrir um novo ambiente de desenvolvimento no seu navegador, que é onde a mágica acontece. Você verá um arquivo chamado Código.gs (ou algo parecido). É ali que vamos escrever.

A Anatomia de um Script Simples

Um script no Apps Script é uma sequência de funções. Uma função básica se parece com isso:


function minhaPrimeiraAutomacao() {
  Logger.log("Olá, mundo da automação!");
}

O Logger.log() é seu melhor amigo para depuração. É como um print() em Python. Ele escreve mensagens no log de execução, que você pode ver na área de "Execuções" do seu projeto Apps Script.

Interagindo com o Google Sheets: Lendo e Escrevendo Dados

O Apps Script brilha quando o assunto é interagir com as planilhas. A classe SpreadsheetApp é o ponto de entrada para tudo isso.


function lerEEscreverNaPlanilha() {
  var spreadsheet = SpreadsheetApp.getActiveSpreadsheet(); // Pega a planilha ativa
  var sheet = spreadsheet.getActiveSheet(); // Pega a aba ativa

  // Exemplo 1: Ler um valor de uma célula específica (A1)
  var valorCelulaA1 = sheet.getRange("A1").getValue();
  Logger.log("Valor da célula A1: " + valorCelulaA1);

  // Exemplo 2: Escrever um valor em uma célula específica (B1)
  sheet.getRange("B1").setValue("Automação Funcionando!");

  // Exemplo 3: Ler um intervalo de células (A2:B5)
  var dados = sheet.getRange("A2:B5").getValues(); // Retorna um array 2D
  Logger.log("Dados do intervalo A2:B5: " + JSON.stringify(dados));

  // Exemplo 4: Escrever múltiplos valores de uma vez (a partir de C2)
  var novosDados = [
    ["Nome", "Idade"],
    ["João", 30],
    ["Maria", 25]
  ];
  sheet.getRange(2, 3, novosDados.length, novosDados[0].length).setValues(novosDados);
  // O range acima significa: linha 2, coluna 3 (C), número de linhas, número de colunas
}

Dica de ouro: Sempre que precisar ler ou escrever muitos dados, prefira usar getValues() e setValues() com arrays 2D. Acessar célula por célula com getValue() e setValue() dentro de um loop é MUITO lento e pode estourar o limite de tempo de execução.

Consumindo APIs Externas: Buscando Informações do Mundo

Aqui é onde a coisa fica interessante. Quase toda a informação que você precisa hoje em dia pode ser acessada via API. O Apps Script tem uma classe chamada UrlFetchApp para isso.

Digamos que você precisa puxar a cotação do dólar ou algum dado de um sistema de terceiros. Eu uso muito isso para integrar com sistemas de CRM, ERP ou até mesmo APIs que criei em Python para tarefas específicas.


function puxarDadosDeAPI() {
  var url = "https://api.exchangerate-api.com/v4/latest/USD"; // Exemplo de API pública (você pode substituir pela sua)
  try {
    var response = UrlFetchApp.fetch(url);
    var json = JSON.parse(response.getContentText()); // Converte a resposta JSON para um objeto JavaScript

    var cotacaoDolarReal = json.rates.BRL; // Exemplo: pegando a taxa BRL
    Logger.log("Cotação do Dólar para Real: " + cotacaoDolarReal);

    // Agora, joga isso na sua planilha
    var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName("Cotações"); // Pega uma aba específica
    if (!sheet) {
      sheet = SpreadsheetApp.getActiveSpreadsheet().insertSheet("Cotações"); // Cria se não existir
      sheet.getRange("A1").setValue("Moeda");
      sheet.getRange("B1").setValue("Taxa");
    }
    sheet.getRange("A2").setValue("USD/BRL");
    sheet.getRange("B2").setValue(cotacaoDolarReal);

  } catch (e) {
    Logger.log("Erro ao puxar dados da API: " + e.toString());
    // Aqui você pode adicionar lógica para notificar, por exemplo, enviar um e-mail de erro.
  }
}

Problema que já tive: As APIs nem sempre respondem como você espera. Já peguei APIs que retornavam um JSON mal formatado, ou que mudavam o formato do dia para a noite sem aviso. Sempre adicione blocos try...catch e verifique a estrutura do JSON antes de tentar acessá-la diretamente. Use Logger.log(json) para inspecionar a resposta.

Automatizando com Gatilhos (Triggers): Fazendo as coisas rodarem sozinhas

A verdadeira mágica da automação acontece com os gatilhos. Eles permitem que seu script rode automaticamente em resposta a eventos (como abrir a planilha, editar uma célula) ou em um horário programado.

Para configurar um gatilho:

No editor do Apps Script, clique no ícone do relógio (Gatilhos) na barra lateral esquerda.
Clique em Adicionar Gatilho.
Você vai configurar:
- Escolha qual função executar: Selecione a função que você quer que rode (ex: puxarDadosDeAPI).
- Escolha qual implantação do projeto deve ser executada: Normalmente Head.
- Selecione a fonte do evento: Pode ser "Baseado no tempo" (para rodar a cada hora, dia, etc.) ou "Na abertura" (para rodar quando a planilha é aberta), "Ao editar" (quando uma célula é alterada), entre outros.
- Selecione o tipo de evento: Depende da fonte. Se for "Baseado no tempo", você pode escolher "Intervalo de horas" (ex: a cada 1 hora).
Salve. Na primeira vez, ele pedirá autorização. É normal.

Eu uso gatilhos baseados em tempo para atualizar relatórios de cotações financeiras a cada hora, ou para consolidar dados de vendas todo dia à meia-noite. É sensacional.

Um toque de IA (via API): Gerando textos ou categorizando dados

Como eu prometi não desviar do Apps Script, vamos focar em como você *interage* com IA *através* de APIs externas, sem que o Apps Script precise ser inteligente por si só. Eu tenho um script em Python rodando em um servidor (pode ser AWS Lambda, Google Cloud Functions, ou até uma máquina virtual simples) que expõe uma API. Esse script Python usa modelos de LLM (como OpenAI ou Gemini) para fazer coisas como resumir textos, categorizar produtos ou gerar pequenas descrições.

O Apps Script, então, atua como o "controlador". Ele pega os dados da sua planilha, envia para essa API (que faz o processamento com IA), e traz o resultado de volta para a planilha.


function categorizarTextosComIA() {
  var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName("Produtos");
  var lastRow = sheet.getLastRow();
  var textosParaCategorizar = sheet.getRange("A2:A" + lastRow).getValues(); // Coluna A tem descrições
  var categoriasRetornadas = [];

  var apiEndpoint = "https://minha-api-de-ia.com/categorizar"; // Sua API externa
  var apiKey = "SUA_CHAVE_API_SECRETA"; // Cuidado para não expor chaves sensíveis!

  for (var i = 0; i < textosParaCategorizar.length; i++) {
    var texto = textosParaCategorizar[i][0];
    if (texto && texto.length > 0) {
      try {
        var options = {
          "method": "post",
          "contentType": "application/json",
          "headers": {
            "Authorization": "Bearer " + apiKey
          },
          "payload": JSON.stringify({ "texto": texto })
        };
        var response = UrlFetchApp.fetch(apiEndpoint, options);
        var result = JSON.parse(response.getContentText());
        categoriasRetornadas.push([result.categoria || "N/A"]); // Supondo que a API retorna { "categoria": "..." }
      } catch (e) {
        Logger.log("Erro ao categorizar texto '" + texto + "': " + e.toString());
        categoriasRetornadas.push(["Erro na API"]);
      }
    } else {
      categoriasRetornadas.push([""]); // Se a célula estiver vazia
    }
  }

  // Escreve as categorias de volta na coluna B, começando da linha 2
  sheet.getRange(2, 2, categoriasRetornadas.length, 1).setValues(categoriasRetornadas);
}

Aqui, o Apps Script é o orquestrador. Ele não "faz IA", mas ele "usa IA" ao integrar-se com serviços que fazem. Isso é extremamente poderoso para tarefas como:

Resumir centenas de feedback de clientes em uma planilha.
Classificar e-mails recebidos para direcionamento automático.
Gerar títulos ou descrições para produtos a partir de palavras-chave.

Comparativo: Jeito Manual vs. Jeito Automatizado

Processo Manual/Demorado	Processo Automatizado (Apps Script)
Abrir 5 relatórios CSV, copiar e colar dados em uma planilha mestra. Formatar colunas, remover duplicatas.	Script com `UrlFetchApp` busca dados de endpoints, usa `SpreadsheetApp` para inserir em uma aba, `Array.prototype.filter()` para remover duplicatas e `Range.setNumberFormat()` para formatar.
Passar 2 horas compilando e-mails semanais com as principais métricas da planilha.	Script lê as células de métricas, formata o corpo do e-mail com `GmailApp.sendEmail()` ou `MailApp.sendEmail()`, e envia automaticamente em um dia e horário programado (via gatilho).
Atualizar manualmente as cotações de moedas em uma planilha financeira todos os dias.	Script usa `UrlFetchApp` para buscar dados de uma API de câmbio, atualiza as células relevantes na planilha e é executado a cada 4 horas por um gatilho baseado no tempo.
Copiar manualmente descrições de produtos para uma ferramenta externa de IA para gerar títulos, e depois colar os títulos de volta.	Script pega a coluna de descrições, envia para uma API externa (que utiliza LLM), e insere os títulos gerados de volta na planilha, tudo com um clique ou um gatilho.
Validar se todos os IDs de um sistema estão na planilha, checando um por um.	Script compara duas colunas, identifica os IDs faltantes ou duplicados e destaca as células com `Range.setBackground()`.

O Que Dá Errado: A Vida Real de Quem Automa

Ah, os problemas... Eles fazem parte do dia a dia. Aqui estão algumas pedras no caminho que eu já encontrei e que você provavelmente vai encontrar também:

Autorização é um inferno na primeira vez (e às vezes depois): Quando você roda um script que acessa seus dados ou serviços Google pela primeira vez (ou quando adiciona novas permissões), ele vai pedir autorização. O processo pode ser meio confuso, com avisos de "aplicativo não verificado". É normal. Você precisa ir em "Configurações avançadas" e "Acessar [nome do seu projeto]". Isso é uma medida de segurança do Google. Se você não está usando sua conta pessoal, mas uma conta corporativa, às vezes o administrador precisa liberar algumas coisas.
Limites de execução e cotas: Apps Script tem limites de tempo de execução (geralmente 6 minutos para scripts normais, mais para add-ons) e cotas diárias para chamadas de API (UrlFetchApp, MailApp, etc.). Já tive scripts que rodavam por 5 minutos e "morriam" antes de terminar. A solução? Otimizar o código (usar setValues para blocos grandes, não célula a célula), dividir a tarefa em várias execuções menores ou, em casos extremos, migrar para Python em um servidor dedicado.
APIs que mudam (e quebram seu script): Sua automação depende de uma API externa? Prepare-se. APIs mudam. Campos são renomeados, endpoints são alterados, autenticações são atualizadas. Do nada, seu script para de funcionar. A solução é ter um bom tratamento de erros (try...catch) e monitoramento (checar os logs de execução regularmente). Uma boa prática é isolar as chamadas de API em funções separadas.
Indexação de arrays vs. números de linhas/colunas: Uma confusão clássica. Em JavaScript (e, portanto, Apps Script), arrays são base 0. Ou seja, o primeiro elemento é array[0]. Mas no Google Sheets, a linha 1 é a 1, a coluna A é a 1. Quando você usa getRange(linha, coluna), ele espera 1-based. Quando você recebe um array de getValues(), ele é 0-based. Já perdi um bom tempo por causa disso, pegando o dado errado ou escrevendo no lugar errado.
Depuração (debugging) limitada: O editor do Apps Script tem um depurador, mas ele não é tão robusto quanto os IDEs de Python ou outras linguagens. Muitas vezes, você vai depender pesadamente do Logger.log() para entender o que está acontecendo. Salve-se o trabalho e use Logger.log(JSON.stringify(suaVariavel)) para ver o conteúdo de objetos complexos.
Lentidão inexplicável: Às vezes, seu script funciona, mas demora uma eternidade. Geralmente, é por causa de muitas chamadas individuais ao Google Sheets (getValue(), setValue() em loops). Ou chamadas de API sem controle (sem cache, fazendo a mesma chamada 100 vezes). Otimize, otimize, otimize. Pense em como você faria em Python para ser eficiente com I/O.
Gerenciamento de credenciais: Se sua API exige uma chave secreta, onde você a guarda? Não coloque direto no código! O Apps Script tem um serviço de propriedades (PropertiesService) que permite armazenar chaves e outros valores de forma segura, sem expô-los no código-fonte. Isso é fundamental para a segurança.

FAQ: Perguntas dos Batalhadores Diários

P1: Posso rodar scripts Apps Script localmente, como faço com Python?

R: Não diretamente. Apps Script é um ambiente de nuvem e roda nos servidores do Google. Você escreve e testa ele no navegador. Para rodar algo "local", você precisaria de uma configuração bem mais complexa, talvez expondo um endpoint HTTP local para o Apps Script consumir, mas isso desvirtua o propósito. Se a necessidade é essa, Python é a ferramenta ideal.

P2: Qual a melhor forma de compartilhar um script com outras pessoas sem expor o código?

R: A maneira mais simples é transformar seu script em um suplemento (add-on) se for algo genérico. Se for para um grupo específico, você pode compartilhar a planilha onde o script está "anexado" e garantir que todos tenham as permissões corretas para executá-lo. O código fica no projeto do Apps Script associado à planilha. Não tem como "compilar" para um executável como em outras linguagens.

P3: Como faço para um script disparar um alerta se algo der errado (ex: API não respondeu)?

R: Use o bloco try...catch como mostrei. Dentro do catch, você pode usar MailApp.sendEmail() para enviar um e-mail para você (ou para uma lista de e-mails) com a mensagem de erro. Configure um filtro no seu e-mail para esses alertas, assim você não perde tempo checando logs, só reage quando algo realmente quebra.

Conclusão

No final das contas, o Google Apps Script é uma ferramenta brutalmente prática. Não é a linguagem mais moderna, nem a mais elegante, mas ela resolve problemas reais e tira um peso enorme dos ombros de quem lida com planilhas e processos manuais no dia a dia. Já me salvou incontáveis horas, evitou erros bestas e me permitiu focar no que realmente importava.

Vai dar problema? Vai. Você vai xingar? Com certeza. Mas a sensação de ver aquela automação rodando sozinha, sem sua intervenção, é impagável. É o tipo de coisa que te faz pensar: "Como eu vivia sem isso antes?". Então, se você se identificou com a dor da repetição, a solução pode estar a poucos cliques em Extensões > Apps Script.

A Mente Vetorial

Pesquisar este blog