Tutorial de Google Apps Script y la API de Gemini: extracción inteligente de datos

La introducción manual de datos es el enemigo de la productividad. Si tu equipo depende de extraer datos de correos operativos, como facturas, confirmaciones de reserva o formularios de feedback de clientes, seguro que te suena la pesadilla de los métodos tradicionales de parseo. 

Hasta ahora, los desarrolladores han recurrido a las expresiones regulares (Regex) para extraer detalles como números de factura o importes. Pero Regex es tremendamente frágil: en cuanto un proveedor cambia la plantilla del correo o mete un salto de línea inesperado, todo el parser se rompe sin avisar.

En este tutorial te enseño a construir una canalización totalmente automatizada y sin interfaz que resuelve este problema con IA generativa. Escribiremos un script ligero que lea los mensajes no leídos de Gmail, envíe el texto no estructurado a la API de Gemini para una extracción inteligente y registre el JSON perfectamente estructurado directamente en una hoja de Google.

Requisitos previos:

• Una cuenta de Google
• Conocimientos básicos de JavaScript (Google Apps Script)
• Una clave de la API de Gemini

¿Qué es Google Apps Script?

Google Apps Script es una plataforma de desarrollo rápido basada en JavaScript y en la nube que te permite automatizar, personalizar y ampliar aplicaciones de Google Workspace como Google Docs, Sheets, Slides y más. 

Como la plataforma se ejecuta directamente en los servidores de Google, no necesitas instalar software, configurar entornos locales ni gestionar infraestructura. 

Apps Script ofrece a desarrolladores y perfiles low-code la posibilidad de interactuar por programación con herramientas de Google Workspace como Docs, Sheets, Slides, Drive y más. Puedes crear y ejecutar automatizaciones mediante menús personalizados, botones o programaciones temporales, o usar el servicio para crear y publicar complementos en Google Workspace Marketplace.

Cómo funciona Google Apps Script

Google Apps Script abstrae la complejidad de la configuración backend y la autenticación con APIs para que te centres en la lógica y los datos. Lo consigue con varias funciones:

• Editor nativo en la nube: escribes, depuras y despliegas tu código JavaScript íntegramente en un IDE web dentro del navegador.
• Servicios integrados: en lugar de pelearte con OAuth y llamadas API complejas, usas objetos globales listos para usar (como SpreadsheetApp, MailApp o DriveApp) para interactuar de forma nativa con los servicios de Google.
• Disparadores basados en eventos: los scripts pueden ejecutarse manualmente desde menús personalizados o programarse para que se ejecuten de forma automática con disparadores temporales (p. ej., cada medianoche) y disparadores por evento (p. ej., cuando alguien envía un formulario de Google).

Arquitectura de Google Apps Script: canalización de Gmail a Sheets

Antes de escribir el script, mapeemos cómo fluye la información en esta canalización. La arquitectura se apoya en cuatro componentes que trabajan en conjunto:

• Gmail (origen): el proceso comienza consultando tu bandeja con operadores de búsqueda estándar (como is:unread label:invoices). El script aísla los hilos correctos y extrae tanto el cuerpo en texto plano como los PDFs adjuntos.
• Apps Script (capa de cómputo): actúa como capa de orquestación. Itera por los hilos no leídos, formatea los adjuntos a base64 y gestiona la lógica de informes de error y procesamiento por lotes.
• API de Gemini (motor de transformación): Apps Script envía una carga multimodal (texto del correo más los PDFs) al modelo Gemini 2.5 Flash. Al pasar un esquema de respuesta JSON estricto en la llamada, obligamos al modelo a extraer valores exactos como proveedor, importe total y moneda, en lugar de generar texto conversacional.
• Google Sheets (destino): cuando Gemini devuelve el JSON estructurado, Apps Script analiza los resultados, los agrupa en un único array e inserta los datos en bloque en la siguiente fila vacía de tu hoja activa con setValues().

¿Por qué usar Google Apps Script como capa de cómputo en este proyecto? 

La principal ventaja es eliminar por completo la sobrecarga de infraestructura. No hay que aprovisionar servidores ni configurar contenedores Docker o flujos de OAuth complicados solo para leer tus correos o escribir en una hoja de cálculo. 

Como Apps Script se integra de forma nativa con servicios como GmailApp y SpreadsheetApp, Google gestiona la autenticación internamente. Tú solo escribes el código y conectas los endpoints.

Paso 1: prepara tu entorno de Google Apps Script

Antes de escribir una línea, vamos a preparar las dependencias externas. Esto implica conseguir acceso a la API de Gemini, crear la hoja de destino y configurar Gmail para etiquetar correctamente las facturas entrantes.

Generar la clave de la API de Gemini

Para impulsar nuestra extracción inteligente de datos, necesitamos acceso a la API de Gemini.

1. Ve a Google AI Studio e inicia sesión con tu cuenta de Google.
2. En el menú lateral izquierdo, haz clic en Get API key.
3. Pulsa el botón Create API key. Puedes crear la clave en un proyecto existente de Google Cloud o dejar que AI Studio cree uno nuevo.
4. Copia la cadena generada. 

Mejor práctica de seguridad: no pierdas esta clave y, sobre todo, no la hardcodees en texto plano en tu código. Déjala en el portapapeles o en un bloc seguro por ahora; en el siguiente paso la guardaremos de forma segura en nuestro entorno de Apps Script.

Preparar la hoja de Google y proteger la clave

Necesitamos un lugar donde almacenar los datos extraídos. Esta hoja también será el punto de lanzamiento de nuestro script de automatización.

1. Configura las cabeceras de la base de datos Crea una hoja de cálculo de Google en blanco. En la primera fila, crea estas columnas para que coincidan con el esquema JSON que definiremos en el script:

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

Fija la fila superior para mantener las cabeceras visibles a medida que crezcan los datos.

2. Accede a Apps Script y guarda la clave de la API Con la hoja creada, abriremos el editor de Apps Script desde ella. Así vinculamos el código a esta hoja concreta.

1. En tu hoja, ve a Extensiones > Apps Script en el menú superior.
2. Cuando se abra el editor, mira la barra lateral izquierda y haz clic en el icono del engranaje para abrir Project Settings.

3. Desplázate hasta abajo para encontrar la sección Script Properties.
4. Haz clic en Add script property.
5. En Property, escribe exactamente GEMINI_API_KEY.
6. En Value, pega la clave que copiaste de AI Studio.
7. Haz clic en Save script properties.

El código que escribiremos más adelante obtendrá este valor de forma segura en tiempo de ejecución sin exponer tus credenciales.

Paso 2: escribe el código de Google Apps Script

Desde el editor de Apps Script, borra cualquier código por defecto. Vamos a construir el motor de automatización bloque a bloque.

1. Configuración y UI

Empezamos definiendo un objeto global de configuración. Es una buena práctica de clean code que agrupa todas las variables hardcodeadas en un único lugar, para que solo tengas que editar este bloque superior.

También añadimos una función onOpen(). Este disparador integrado de Apps Script crea automáticamente un menú personalizado en tu hoja para que personas no técnicas puedan ejecutar el script manualmente sin abrir el editor.

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. La orquestación

La función processInvoices() actúa como orquestador principal. Empieza recuperando de forma segura tu clave de API desde las Script Properties que configuramos antes. 

Después usa el servicio integrado GmailApp para consultar la bandeja de entrada.

Al llamar a GmailApp.search(CONFIG.searchQuery), el script recupera un array de hilos que coinciden con la regla is:unread label:invoices. 

Si encuentra coincidencias, recorre cada hilo, toma el último mensaje, extrae el cuerpo en texto plano y aísla cualquier PDF adjunto.

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. Procesar emails y PDFs multimodales

Al iterar por los hilos, tomamos el mensaje más reciente. Sin embargo, las facturas rara vez llegan como texto plano; casi siempre vienen adjuntas en PDF. 

Gracias a Gemini 2.5 Flash, que es multimodal de forma nativa, nuestro script recorre latestMessage.getAttachments(), captura los PDFs, los convierte a una cadena Base64 y se los pasa directamente a la API como inlineData. 

Gemini "lee" el PDF de forma visual y extrae los datos con la misma facilidad que del 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. Inserción por lotes y gestión de errores

Para optimizar el rendimiento, no escribimos en la hoja fila a fila. 

En su lugar, acumulamos el JSON extraído en un array (batchData) y lo escribimos todo de una vez al final con setValues().

Fíjate en el bloque try...catch. 

Si Gemini alucina o falla en un correo concreto, el script no se cae del todo. Captura el error con elegancia y usa MailApp.sendEmail() para avisar al administrador al instante, garantizando una alta observabilidad.

 // 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 último, el script llama a thread.markRead() en cada correo procesado. Así te aseguras de que en la siguiente ejecución los ignore y solo busque nuevos.

5. Función auxiliar de la API de Gemini (modo JSON)

Al llamar a LLMs, muchos desarrolladores usan ingeniería de prompts del tipo "Devuelve un bloque JSON". Sin embargo, los modelos a menudo responden con relleno conversacional (por ejemplo, "Claro, aquí tienes tus datos: [JSON]"), lo que hace que fallen los parsers posteriores.

Al establecer responseMimeType: "application/json" y proporcionar un responseSchema estricto, forzamos a la API REST de Gemini a responder únicamente con un objeto JSON garantizado que contiene exactamente nuestras cabeceras de columna de la hoja.

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);
}

Paso 3: automatiza tu canalización de Google Apps Script

El código solo aporta valor si te hace la vida más fácil. 

Google Apps Script ofrece potentes entornos de ejecución que van desde botones interactivos en la interfaz hasta trabajos en segundo plano totalmente desatendidos.

Método 1: disparar desde la interfaz de la hoja

Si estás creando esta herramienta para un equipo de contabilidad no técnico, probablemente no quiera abrir el editor de Apps Script solo para procesar las facturas del día. 

Como incluimos la función onOpen(), Apps Script vincula automáticamente un menú personalizado en la interfaz de Google Sheets cada vez que se abre la hoja.

1. Vuelve a tu hoja y recarga la página.
2. Espera unos segundos y mira la barra superior. Verás un nuevo desplegable llamado 🤖 AI Automations.
3. Haz clic y selecciona Fetch New Invoices.

4. La primera vez, Google te pedirá autorizar el script (para leer tu Gmail y enviar correos en tu nombre). Una vez autorizado, se ejecutará en tiempo real. ¡Podrás ver cómo el JSON extraído va rellenando las filas ante tus ojos!

Método 2: automatización sin interfaz con disparadores temporales

Si quieres una automatización de configúralo y olvídate de verdad, puedes usar los Time-Driven Triggers nativos para ejecutar la canalización de forma autónoma en segundo plano.

1. En el editor de Apps Script, haz clic en Triggers (icono de reloj) en la barra lateral izquierda.

2. Haz clic en Add Trigger en la esquina inferior derecha.

3. Selecciona la función processInvoices.
4. Cambia el origen del evento a Time-driven y programa una ejecución por horas (p. ej., cada 6 horas).
5. Haz clic en Guardar.

Tu canalización de IA sin interfaz ya es completamente autónoma.

Aunque tu ordenador esté apagado, los servidores de Google se activarán cada seis horas, escanearán tu bandeja, parsearán las facturas con Gemini, registrarán los datos en Sheets y volverán a “dormir”. 

Puedes monitorizar el éxito o fallo de estas ejecuciones en segundo plano desde la pestaña Executions del editor de Apps Script para ver los logs.

Paso 4: prueba la extracción de datos con IA

Con el código listo, toca probarlo para asegurarnos de que la canalización funciona como esperamos.

Veamos dos escenarios prácticos para comprobar cómo la API de Gemini maneja distintos formatos y qué aspecto tienen las respuestas reales.

Prueba 1: extracción desde un correo en texto plano

Primero, probaremos con una factura incrustada directamente en el cuerpo del correo.

1. Envíate un correo con el asunto "Invoice INV-2023-88493".
2. En el cuerpo, escribe texto no estructurado como: "Hi Team, please pay Acme Corp $450.00 USD for the Q3 software license."
3. Aplica la etiqueta invoices al correo y asegúrate de que siga sin leer.

4. Ejecuta el script desde el menú personalizado.

En segundo plano, Gemini recibe este texto no estructurado y se ajusta estrictamente a nuestro esquema JSON. 

En lugar de responder con relleno conversacional, devuelve una carga en bruto. 

Como la respuesta es JSON perfectamente estructurado, nuestro array batchData.push() lee sin problemas extractedData.totalAmount e inserta 6550 directamente en la hoja de Google sin necesidad de lógica Regex compleja.

Prueba 2: extracción desde un PDF adjunto

Ahora probemos la verdadera potencia de Gemini 2.5 Flash pasándole un documento PDF.

1. Genera o descarga una factura PDF de ejemplo (por ejemplo, de $20,700.00 de ProTech Cloud Services).
2. Envíate el PDF por correo. ¡Puedes dejar el cuerpo del correo completamente en blanco!
3. Aplica la etiqueta invoices y márcalo como no leído.

4. Ejecuta el script. La canalización detectará el adjunto, lo convertirá a Base64 y Gemini leerá visualmente el documento para extraer el proveedor y el total.

Aquí es donde la arquitectura demuestra su valor. 

No has tenido que escribir lógica OCR (reconocimiento óptico de caracteres), gestionar una librería de parseo de PDF aparte ni crear expresiones regulares para encontrar el total. 

El LLM ha manejado los datos visuales no estructurados de forma nativa.

Conclusión

Automatizar flujos de trabajo empresariales no requiere gestionar infraestructuras pesadas ni pelearte con bucles de autorización complejos. 

Combinando Google Apps Script con la API de Gemini, hemos creado una canalización de datos inteligente y sin servidor que se ejecuta íntegramente en la nube que ya usas a diario.

La fortaleza de esta arquitectura está en su sencillez. En lugar de aprovisionar servidores, configurar webhooks o gestionar ficheros de credenciales seguros en un servidor externo, Apps Script se encarga de contexto, autenticación y ejecución de forma nativa. 

Mientras tanto, Gemini elimina la necesidad de expresiones regulares frágiles o software OCR costoso, y convierte correos desordenados y PDFs no estructurados en filas de base de datos predecibles con una sola llamada a la API.

Si quieres llevar tus habilidades más lejos y explorar qué más puedes construir con acceso programático a LLMs, te recomiendo el Introduction to APIs in Python de DataCamp o profundizar en el diseño de flujos inteligentes con el curso de AI Agent Fundamentals .