Tutorial de Google Apps Script e Gemini API: extração inteligente de dados

Digitação manual é inimiga da produtividade. Se o seu time depende de extrair dados de e-mails operacionais, como notas fiscais, confirmações de reserva ou formulários de feedback de clientes, você provavelmente conhece o pesadelo dos métodos tradicionais de parsing. 

Historicamente, desenvolvedores usavam expressões regulares (Regex) para capturar detalhes como número da fatura ou valor de cobrança. Mas Regex é extremamente frágil: no momento em que um fornecedor muda o template do e-mail ou adiciona uma quebra de linha aleatória, todo o parser quebra silenciosamente.

Neste tutorial, vou mostrar como criar um pipeline totalmente automatizado e sem interface que resolve esse problema usando IA generativa. Vamos escrever um script leve que lê mensagens não lidas do Gmail, envia o texto não estruturado para a Gemini API para extração inteligente e registra o JSON perfeitamente estruturado direto em uma planilha do Google Sheets.

Pré-requisitos:

• Uma conta Google
• Noções básicas de JavaScript (Google Apps Script)
• Uma chave da Gemini API

O que é Google Apps Script?

Google Apps Script é uma plataforma de desenvolvimento rápido baseada em JavaScript, na nuvem, que permite automatizar, personalizar e estender aplicativos do Google Workspace como Google Docs, Sheets, Slides e muito mais. 

Como a plataforma roda diretamente nos servidores do Google, não há necessidade de instalar software, configurar ambientes locais ou gerenciar infraestrutura. 

Apps Script dá a desenvolvedores e low-code developers a capacidade de interagir programaticamente com ferramentas do Google Workspace como Docs, Sheets, Slides, Drive e outras. Você pode criar e executar automações por meio de menus personalizados, cliques de botão ou agendamentos baseados em tempo, ou ainda usar o serviço para criar e publicar add-ons no Google Workspace Marketplace.

Como o Google Apps Script funciona

O Google Apps Script abstrai o trabalho pesado de configuração de backend e autenticação de APIs, permitindo que você foque diretamente em lógica e dados. Ele faz isso com vários recursos:

• Editor nativo na nuvem: você escreve, depura e publica seu código JavaScript totalmente em um IDE web dentro do seu navegador.
• Serviços integrados: em vez de brigar com OAuth e chamadas complexas de API, você usa objetos globais prontos para uso (como SpreadsheetApp, MailApp ou DriveApp) para interagir nativamente com serviços Google.
• Triggers orientados a eventos: scripts podem ser executados manualmente via botões de menu personalizados ou agendados para rodar automaticamente usando triggers baseados em tempo (por exemplo, toda meia-noite) e triggers orientados a eventos (por exemplo, quando um usuário envia um Google Form).

A arquitetura do Google Apps Script: pipeline de Gmail para Sheets

Antes de escrever o script, vamos mapear como os dados fluem por esse pipeline. A arquitetura depende de quatro componentes distintos trabalhando em conjunto:

• Gmail (fonte): o processo começa consultando sua caixa de entrada usando operadores de busca padrão (como is:unread label:invoices). O script isola as conversas corretas e extrai tanto o corpo em texto simples quanto quaisquer arquivos PDF anexados.
• Apps Script (processamento): atua como a camada de orquestração. Ele itera pelas conversas não lidas, formata anexos em dados base64 e gerencia a lógica de relatórios de erro e processamento em lote.
• Gemini API (motor de transformação): o Apps Script envia um payload multimodal (o texto do e-mail mais os PDFs) para o modelo Gemini 2.5 Flash. Ao passar um schema rigoroso de resposta em JSON na chamada da API, forçamos o modelo a extrair valores exatos como fornecedor, valor total e moeda, em vez de gerar texto conversacional.
• Google Sheets (destino): quando o Gemini retorna o JSON estruturado, o Apps Script faz o parse dos resultados, agrupa tudo em um único array e insere os dados em lote na próxima linha vazia da sua planilha ativa usando setValues().

Por que usar Google Apps Script como camada de computação neste projeto? 

O principal benefício é eliminar completamente a sobrecarga de infraestrutura. Não há provisionamento de servidor e você não precisa configurar contêineres Docker nem fluxos complicados de OAuth só para ler seus e-mails ou escrever em uma planilha. 

Como o Apps Script se integra nativamente a serviços como GmailApp e SpreadsheetApp, o Google cuida da autenticação internamente. Você simplesmente escreve o código e conecta os endpoints.

Passo 1: prepare seu ambiente do Google Apps Script

Antes de escrever qualquer código, vamos preparar as dependências externas. Isso envolve garantir acesso à Gemini API, criar a planilha de destino e configurar sua caixa de entrada do Gmail para marcar corretamente as notas fiscais recebidas.

Gerando a chave da Gemini API

Para alimentar nossa extração inteligente de dados, precisamos de acesso à Gemini API.

1. Acesse Google AI Studio e faça login com sua conta Google.
2. No menu de navegação à esquerda, clique em Get API key.
3. Clique no botão Create API key. Você pode criar essa chave em um projeto existente do Google Cloud ou deixar o AI Studio criar um novo para você.
4. Copie a string gerada. 

Boa prática de segurança: não perca essa chave e, mais importante, não a deixe hardcoded em texto plano no seu código. Deixe-a na área de transferência ou em um bloco de notas seguro por enquanto; vamos armazená-la com segurança dentro do ambiente do Apps Script no próximo passo.

Preparando a planilha e protegendo a chave

Precisamos de um lugar para armazenar os dados extraídos. Esta planilha também será a base de lançamento do nosso script de automação.

1. Configure os cabeçalhos do "banco de dados" Crie uma nova planilha em branco no Google Sheets. Na primeira linha, crie as seguintes colunas para corresponder ao schema JSON que vamos definir no script:

• Date
• Vendor
• Invoice Number
• Total Amount
• Currency
• Items Summary
• Email Link

Congele a primeira linha para manter os cabeçalhos visíveis conforme os dados crescem.

2. Acesse o Apps Script e armazene a chave da API Agora que a planilha existe, podemos abrir o editor do Apps Script diretamente dela. Isso vincula automaticamente nosso código a essa planilha específica.

1. Na sua planilha, clique em Extensions > Apps Script no menu superior.
2. Quando o editor abrir, olhe a barra lateral esquerda e clique no ícone de engrenagem para abrir Project Settings.

3. Role até o final para encontrar a seção Script Properties.
4. Clique em Add script property.
5. Em Property, digite exatamente GEMINI_API_KEY.
6. Em Value, cole a chave da API que você copiou do AI Studio.
7. Clique em Save script properties.

O código que vamos escrever mais adiante buscará esse valor com segurança em tempo de execução, sem expor suas credenciais.

Passo 2: escreva o código do Google Apps Script

No editor do Apps Script, apague qualquer código padrão. Vamos construir nosso mecanismo de automação bloco a bloco.

1. Configuração e criação da interface

Começamos definindo um objeto global de configuração. Essa é uma boa prática de clean code que agrupa todas as variáveis fixas em um só lugar, para que você só precise editar esse bloco superior.

Também adicionamos a função onOpen(). Esse trigger nativo do Apps Script cria automaticamente um menu personalizado na sua planilha do Google, permitindo que usuários não técnicos rodem o script manualmente sem abrir o editor de código.

const CONFIG = {
 searchQuery: "is:unread label:invoices",
 model: "gemini-2.5-flash",
 adminEmail: Session.getActiveUser().getEmail() // Automatically emails the script owner if it crashes
};

/**
* Creates a custom menu in Google Sheets so non-technical users can run the script manually.
*/
function onOpen() {
 const ui = SpreadsheetApp.getUi();
 ui.createMenu('🤖 AI Automations')
   .addItem('Fetch New Invoices', 'processInvoices')
   .addToUi();
}

2. A configuração da orquestração

A função processInvoices() atua como o orquestrador principal. Ela começa buscando com segurança sua chave de API nas Script Properties que configuramos. 

Em seguida, usa o serviço integrado GmailApp para consultar sua caixa de entrada.

Ao chamar GmailApp.search(CONFIG.searchQuery), o script recupera um array de conversas de e-mail que batem com nossa regra is:unread label:invoices. 

Se encontrar resultados, ele percorre cada conversa, pega a mensagem mais recente, extrai o corpo em texto simples e isola quaisquer PDFs anexados.

function processInvoices() {
  const apiKey = PropertiesService.getScriptProperties().getProperty("GEMINI_API_KEY");
  if (!apiKey) {
    throw new Error("GEMINI_API_KEY is missing! Please set it in Script Properties.");
  }

  const threads = GmailApp.search(CONFIG.searchQuery);
  if (threads.length === 0) return;

  const sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
  const batchData = [];
  const processedThreads = [];

3. Processando e-mails e PDFs multimodais

Ao percorrermos as conversas, pegamos a mensagem mais recente. Porém, notas fiscais raramente vêm em texto simples; quase sempre estão anexadas como PDF. 

Aproveitando o Gemini 2.5 Flash, que é multimodal por natureza, nosso script percorre latestMessage.getAttachments(), localiza PDFs, converte-os em string Base64 e os envia diretamente no payload da API como inlineData. 

O Gemini "lê" o PDF visualmente e extrai os dados com a mesma facilidade com que lê texto.

for (let i = 0; i < threads.length; i++) {
   const thread = threads[i];
   const latestMessage = thread.getMessages().pop();
  
   const emailBody = latestMessage.getPlainBody();
   const emailDate = latestMessage.getDate();
   const emailLink = https://mail.google.com/mail/u/0/#inbox/${thread.getId()};
   const attachments = latestMessage.getAttachments();
   try {
     const geminiParts = [];
     geminiParts.push({ text: "Extract invoice details from this email and any attached documents:\n\n" + emailBody });
    
     // Add PDF attachments as base64 to the prompt
     for (const attachment of attachments) {
       if (attachment.getContentType() === "application/pdf") {
         geminiParts.push({
           inlineData: {
             mimeType: "application/pdf",
             data: Utilities.base64Encode(attachment.getBytes())
           }
         });
       }
     }
     // Invoke Gemini API
     const extractedData = callGeminiAPI(apiKey, geminiParts);

4. Inserção em lote e tratamento de erros

Para otimizar o desempenho, não escrevemos na planilha linha por linha. 

Em vez disso, empilhamos o JSON extraído em um array (batchData) e gravamos tudo de uma vez no final usando setValues().

Note o bloco try...catch. 

Se o Gemini alucinar ou falhar em um e-mail específico, o script não trava por completo. Em vez disso, captura o erro com elegância e usa MailApp.sendEmail() para alertar o administrador imediatamente, garantindo alta observabilidade.

 // Push to batch array instead of writing one-by-one
     batchData.push([
       emailDate,
       extractedData.vendor || "Unknown Vendor",
       extractedData.invoiceNumber || "N/A",
       extractedData.totalAmount || 0.00,
       extractedData.currency || "USD",
       extractedData.itemsSummary || "N/A",
       emailLink
     ]);
     processedThreads.push(thread);
   } catch (error) {
     MailApp.sendEmail(CONFIG.adminEmail, "🚨 Invoice Pipeline Error", error.toString());
   }
 }
 // Batch Write to Sheets
 if (batchData.length > 0) {
   const lastRow = Math.max(sheet.getLastRow(), 1);
   sheet.getRange(lastRow + 1, 1, batchData.length, batchData[0].length).setValues(batchData);
 }
 // Mark all processed threads as read so they aren't parsed again
 processedThreads.forEach(t => t.markRead());
}

Por fim, o script chama thread.markRead() em cada e-mail processado. Isso garante que, na próxima execução, ele ignore completamente essas mensagens e busque apenas novas.

5. Função auxiliar da Gemini API (modo JSON)

Ao chamar LLMs, desenvolvedores costumam usar prompt engineering como "Devolva um bloco JSON". Porém, os modelos frequentemente respondem com preenchimento conversacional (ex.: "Claro, aqui estão seus dados: [JSON]"), o que faz parsers a jusante quebrarem.

Ao definir responseMimeType: "application/json" e fornecer um responseSchema rigoroso, forçamos a Gemini REST API a responder apenas com um objeto JSON garantido contendo exatamente nossos cabeçalhos de coluna da planilha.

function callGeminiAPI(apiKey, partsArray) {
 const url = https://generativelanguage.googleapis.com/v1beta/models/${CONFIG.model}:generateContent?key=${apiKey};
  const responseSchema = {
   type: "OBJECT",
   properties: {
     vendor: { type: "STRING" },
     invoiceNumber: { type: "STRING" },
     totalAmount: { type: "NUMBER" },
     currency: { type: "STRING" },
     itemsSummary: { type: "STRING" }
   },
   required: ["vendor", "totalAmount"]
 };
  const payload = {
   contents: [{ parts: partsArray }],
   generationConfig: {
     responseMimeType: "application/json",
     responseSchema: responseSchema
   }
 };
  const options = {
   method: "POST",
   contentType: "application/json",
   payload: JSON.stringify(payload),
   muteHttpExceptions: true
 };
  const response = UrlFetchApp.fetch(url, options);
 const jsonResponse = JSON.parse(response.getContentText());
  return JSON.parse(jsonResponse.candidates[0].content.parts[0].text);
}

Passo 3: automatize seu pipeline do Google Apps Script

Código só vale a pena se facilitar sua vida. 

O Google Apps Script oferece ambientes poderosos de execução, que vão de botões interativos na interface a jobs em segundo plano totalmente headless.

Método 1: disparando pela interface da planilha

Se você está criando essa ferramenta para um time financeiro não técnico, é provável que ninguém queira abrir o editor do Apps Script só para processar as notas de hoje. 

Como incluímos a função onOpen() no código, o Apps Script adiciona automaticamente um menu personalizado direto na interface do Google Sheets toda vez que a planilha é aberta.

1. Volte para a sua planilha e atualize a página.
2. Espere alguns segundos e olhe a barra de menus superior. Você verá um novo dropdown chamado 🤖 AI Automations.
3. Clique e selecione Fetch New Invoices.

4. Na primeira execução, o Google vai pedir que você autorize o script (para ler seu Gmail e enviar e-mails em seu nome). Depois de autorizado, o script roda em tempo real. Você pode ver os dados JSON extraídos preenchendo as linhas diante dos seus olhos!

Método 2: automação headless com triggers baseados em tempo

Se você quer uma automação de configurar e esquecer de verdade, use os Time-Driven Triggers nativos para rodar o pipeline de forma autônoma em segundo plano.

1. No editor do Apps Script, clique em Triggers (ícone do relógio) na barra lateral esquerda.

2. Clique em Add Trigger no canto inferior direito.

3. Defina a função como processInvoices.
4. Altere a origem do evento para Time-driven e configure para rodar em um timer por hora (por exemplo, a cada 6 horas).
5. Clique em Save.

Seu pipeline de IA headless agora está totalmente autônomo.

Mesmo que seu computador esteja desligado, os servidores do Google vão despertar a cada seis horas, escanear sua caixa de entrada, processar as notas pelo Gemini, registrar os dados no Sheets e voltar a dormir. 

Você pode monitorar o sucesso ou falha dessas execuções em segundo plano clicando na aba Executions no editor do Apps Script para ver os logs.

Passo 4: testando a extração de dados com IA

Agora que o código está pronto, precisamos testá-lo para garantir que o pipeline de extração funciona como esperado.

Vamos ver dois cenários práticos para entender como a Gemini API lida com formatos diferentes e como são as respostas reais.

Teste 1: extração de e-mail em texto simples

Primeiro, vamos testar uma fatura embutida diretamente no corpo do e-mail.

1. Envie um e-mail para você mesmo com o assunto "Invoice INV-2023-88493".
2. No corpo, escreva um texto não estruturado como: "Oi, time. Por favor, paguem à Acme Corp $450,00 USD pela licença de software do Q3."
3. Aplique o rótulo invoices ao e-mail e garanta que ele permaneça não lido.

4. Execute o script pelo menu personalizado.

Nos bastidores, o Gemini recebe esse texto não estruturado e segue estritamente nosso schema JSON. 

Em vez de responder com preenchimento conversacional, ele retorna um payload bruto. 

Como a resposta é um JSON perfeitamente estruturado, nosso array batchData.push() lê sem esforço extractedData.totalAmount e registra 6550 direto no Google Sheets, sem necessidade de lógica Regex complexa.

Teste 2: extraindo de um anexo em PDF

Agora, vamos testar o verdadeiro poder do Gemini 2.5 Flash enviando um documento PDF.

1. Gere ou baixe um PDF de nota fiscal de exemplo (por exemplo, de $20.700,00 da ProTech Cloud Services).
2. Envie o PDF para você por e-mail. O corpo pode ficar totalmente em branco!
3. Aplique o rótulo invoices e marque como não lido.

4. Execute o script. O pipeline vai detectar o anexo, convertê-lo para Base64 e o Gemini fará a leitura visual do documento para extrair o fornecedor e o valor total.

É aqui que a arquitetura mostra seu valor. 

Você não precisou escrever lógica de OCR (reconhecimento óptico de caracteres) personalizada, gerenciar uma biblioteca separada de parsing de PDF ou criar regex para encontrar o valor total. 

O LLM lidou nativamente com os dados visuais não estruturados.

Conclusão

Automatizar fluxos de trabalho de negócio não exige gerenciar infraestrutura pesada ou travar com loops complexos de autorização. 

Ao combinar Google Apps Script com a Gemini API, construímos um pipeline de dados inteligente e serverless que roda inteiramente no ecossistema em nuvem que você já usa no dia a dia.

A força dessa arquitetura está na simplicidade. Em vez de provisionar servidores, configurar webhooks ou gerenciar arquivos de credenciais em um servidor externo, o Apps Script trata de contexto, autenticação e execução de forma nativa. 

Enquanto isso, o Gemini elimina a necessidade de regex frágeis ou software de OCR caro, transformando corpos de e-mail bagunçados e PDFs não estruturados em linhas previsíveis de banco de dados com uma única chamada de API.

Para levar suas habilidades adiante e explorar o que mais você pode construir com acesso programático a LLMs, recomendo conferir o Introduction to APIs in Python da DataCamp ou se aprofundar no desenho de fluxos inteligentes com o curso AI Agent Fundamentals .