Qué vas a lograr
Al terminar esta guía tendrás tu propio gestor de facturas y boletas. Subes la foto, el PDF o el XML de tu comprobante a una carpeta de Google Drive y, unos minutos después, sus datos aparecen en una hoja de Google Sheets y el archivo queda ordenado por año y mes.
En concreto:
- Una hoja de Google Sheets con proveedor, RUC, fecha y montos de cada comprobante.
- Un archivo ordenado en tu Drive: los comprobantes procesados quedan en carpetas por año y mes.
- Un PDF por cada foto que subas, para tu archivo contable.
- Todo sin pagar nada y sin ingresar una tarjeta.
Funciona con fotos (JPG, PNG y HEIC de iPhone), PDF y los XML de SUNAT.
SOBRE ESTA SOLUCIÓN
La instalación se hace una sola vez y se pega código que ya está escrito: no tienes que programar nada. Ver GitHub y un editor de código puede intimidar, pero son solo unos clics. Después, tu tarea diaria es subir archivos a una carpeta.
Qué necesitas antes de empezar
| Elemento | Opción | Costo |
|---|---|---|
| Una cuenta de Google | accounts.google.com. Si ya tienes Gmail, ya tienes cuenta de Google | $0 |
| Una clave de Gemini (Gemini API Key) | Se crea en la Fase 5 | $0 |
| Un token de ApiPerú | Se crea en la Fase 5 | $0 |
| Total | $0 |
Sobre la cuenta de Google: si ya tienes una cuenta de Gmail (un correo que termina en @gmail.com), esa misma cuenta te da acceso a Google Drive, Google Sheets, Apps Script y Google AI Studio, que son todas las herramientas que usa la guía. No necesitas crear nada más. Si no tienes Gmail, puedes crear una cuenta de Google con cualquier otro correo.
El flujo completo
- 1Crear tu hoja de Google Sheets
- 2Descargar el código desde GitHub
- 3Pegar el código en tu hoja
- 4Instalar el sistema y autorizar el script
- 5Configurar tus llaves (API Keys)
- 6Procesar tus facturas
Después: qué esperar, reglas y límites y una advertencia sobre tus datos.
REGLA DEL TUTORIAL
No se avanza a la siguiente fase sin cerrar la actual. Los controles están marcados con la palabra Control.
FASE 1Crear tu hoja de Google Sheets
- Entra a Google Drive.
- Haz clic en el botón Nuevo (arriba a la izquierda), elige Hojas de cálculo de Google y luego Hoja de cálculo en blanco.
- Arriba a la izquierda, haz clic en «Hoja de cálculo sin título» y ponle de nombre: Gestor Automático de Facturas.
- Deja esa pestaña abierta.

Control: ves una hoja de cálculo en blanco llamada «Gestor Automático de Facturas».
FASE 2Descargar el código desde GitHub
El código del gestor es un único archivo, Codigo.gs, que está en el repositorio de GitHub.
- Abre el repositorio.
- Haz clic en el archivo Codigo.gs.
- Arriba a la derecha de la caja de código, haz clic en el icono de copiar (dos cuadros superpuestos), que está justo a la derecha del botón Raw.
- Con eso el código completo queda copiado: no hace falta abrirlo ni seleccionarlo.


Control: tienes el código copiado en el portapapeles. Es un texto largo que empieza con líneas de código.
FASE 3Pegar el código en tu hoja
- Vuelve a la pestaña de tu hoja de Google Sheets.
- En el menú superior, haz clic en Extensiones y luego en Apps Script.
- Se abrirá el editor de código. Verás un texto por defecto que dice
function myFunction() { ... }. Bórralo todo. - Arriba, haz clic en el nombre Proyecto sin título, escribe Gestor Automático de Facturas y pulsa Cambiar nombre.
- Pega el código que copiaste de GitHub (Ctrl + V, o Cmd + V en Mac).
- Guarda con el icono del disquete o con Ctrl + S (Cmd + S en Mac).
- Cierra la pestaña del editor y vuelve a tu hoja. Recarga la página (F5).



Control: en el menú superior de tu hoja aparece una opción nueva llamada ⚙️ Facturas. Si no aparece, espera unos segundos y recarga otra vez.
FASE 4Instalar el sistema y autorizar el script
- En el menú ⚙️ Facturas, elige 1. Instalar Sistema.
- Aparecerá el mensaje Se requiere autorización. Haz clic en Aceptar.
- Se abrirá una ventana de Google que dice Google no ha verificado esta aplicación. Es normal en los scripts personales.
- En esa ventana, haz clic en Configuración avanzada (abajo a la izquierda). Luego haz clic en Ir a Gestor Automático de Facturas (no seguro).
- Google te mostrará los permisos que pide el script (ver la nota de más abajo). Revísalos, baja hasta el final de la ventana y haz clic en Continuar.
- Aparecerá un mensaje que dice ¡Carpetas creadas con éxito!. Haz clic en Aceptar.







POR QUÉ APARECE EL AVISO DE «NO SEGURO»
Google muestra ese aviso con cualquier script que no pasó su proceso de verificación, y este es un script personal que corre dentro de tu cuenta. Aun así, estás dando permisos amplios: ver, crear y eliminar archivos de tu Drive, de tus hojas de cálculo y de tus presentaciones, conectarse a servicios externos y ejecutarse cuando no estás presente (por eso revisa tu carpeta cada 15 minutos). El de Presentaciones sirve para algo concreto: el script crea una presentación temporal para convertir tus fotos en PDF. Por todo esto conviene instalarlo solo desde el repositorio de esta guía.
Control: en tu Google Drive existe la carpeta Facturas y Boletas Perú, con tres subcarpetas: 01 Entrada, 02 Procesados y 03 Revisar.

El instalador también crea dos pestañas nuevas en tu hoja: Registro_Facturas, donde se anotan los comprobantes, y Observaciones, donde se guardan los avisos de cada uno.

FASE 5Configurar tus llaves (API Keys)
El gestor necesita dos llaves gratuitas: una de Gemini, que lee tus comprobantes, y un token de ApiPerú. Primero las consigues y luego las pegas en el panel del gestor.
5.1 — Crear tu clave de Gemini
- Entra a Google AI Studio con tu cuenta de Google.
- Acepta los términos si es la primera vez que entras.
- Haz clic en Crear clave de API (arriba a la derecha; en inglés, Create API key).
- En la ventana que se abre, ponle un nombre a la clave (por ejemplo, Gemini API Key), elige un proyecto de la lista y haz clic en Crear clave.
- Copia la clave y guárdala por un momento. Es personal: no la compartas.


SOBRE LOS NOMBRES DE LOS MENÚS
Los nombres de los menús de Google cambian de vez en cuando. Si algo no coincide, busca la opción con un nombre parecido.
5.2 — Crear tu token de ApiPerú
ApiPerú es el servicio que consulta los datos del RUC (por ejemplo, el nombre del proveedor). Su plan gratuito alcanza para este uso.
- Entra a apiperu.dev y haz clic en Registrarse.
- Completa tu nombre, tu correo y una contraseña, y haz clic en Registrarme.
- En el panel, elige Api Tokens en el menú de la izquierda y haz clic en Crear primer Api token.
- Ponle un nombre (por ejemplo, Facturas y Boletas) y haz clic en Crear Api token.
- Aparecerá el token una sola vez. Haz clic en Copiar Api token y guárdalo por un momento. Es personal: no lo compartas.




5.3 — Pegar las llaves en el gestor
- En tu hoja, haz clic en ⚙️ Facturas y elige 2. Configurar API Keys.
- Se abrirá una ventana a la derecha de la pantalla.
- Pega tu clave de Gemini en el primer campo y tu token de ApiPerú en el segundo. Si aún no las tienes, usa los enlaces que aparecen en esa misma ventana.
- Haz clic en Guardar y Activar Robot.


Control: en el panel aparece ¡Guardado con éxito! y, enseguida, un mensaje que dice ¡Robot activado con éxito!.
Con esto terminó la instalación. A partir de aquí no necesitas volver a GitHub ni al código, salvo que algo cambie.
FASE 6Procesar tus facturas
Esta es tu tarea del día a día.
- Entra a tu Google Drive y abre la carpeta Facturas y Boletas Perú.
- Abre la subcarpeta 01 Entrada.
- Arrastra y suelta tus fotos de facturas (JPG, PNG o HEIC de iPhone), tus archivos PDF o los XML de SUNAT.
- Cierra Drive. El sistema revisa la carpeta solo, cada 15 minutos, en segundo plano.
Control: pasados unos 15 minutos, tus archivos ya no están en 01 Entrada y aparece una fila nueva por cada uno en la hoja Registro_Facturas.
Ejemplo real con una boleta en PDF
Así se ve el proceso completo con una boleta electrónica en PDF. En la captura de la boleta se taparon el nombre del cliente, su DNI y el nombre del vendedor.





Cada nivel de la estructura tiene un significado:
- Facturas y Boletas Perú: la carpeta principal del sistema. Todo lo demás vive dentro de ella.
- 01 Entrada: donde tú subes tus comprobantes. El sistema la revisa cada 15 minutos y la deja vacía al terminar.
- 02 Procesados: los comprobantes que ya se leyeron y se registraron en la hoja.
- 2026: dentro de 02 Procesados, una carpeta por año, según el año del comprobante.
- 10-Octubre: dentro del año, una carpeta por mes, también según la fecha del comprobante. Ahí queda tu archivo.
- 03 Revisar: los comprobantes que no se pudieron procesar. Revísalos a mano y vuelve a subirlos.
Qué esperar
Pasados los 15 minutos:
- En tu hoja de Google Sheets: en la pestaña Registro_Facturas verás los datos extraídos (proveedor, RUC, fecha y montos). Si la IA no encontró la base imponible o el IGV, pinta la celda de amarillo para que la revises.
- En tu Drive: los archivos pasan a la carpeta 02 Procesados, ordenados por año y mes.
- El PDF: si subiste una foto, el sistema crea un PDF de esa foto para tu archivo contable. Si subiste un PDF original, solo lo mueve.
- Si algo falla: el archivo va a la carpeta 03 Revisar y en Registro_Facturas aparece una fila roja con el motivo en la columna Estado (por ejemplo, «Revisar: No es factura ni boleta»).
- Avisos: la pestaña Observaciones guarda una línea por cada comprobante con advertencias, como una base o un IGV que no se vio, o un RUC que no tiene 11 dígitos.
Si necesitas tus datos en un archivo de Excel, en Google Sheets elige Archivo, luego Descargar y Microsoft Excel (.xlsx).
Reglas y límites
SOLO COMPROBANTES DEL AÑO ACTUAL
Si subes un comprobante de un año anterior, el sistema lo rechaza y lo envía a la carpeta 03 Revisar. Se hace así para evitar errores contables.
SI FALTA UN DATO, QUEDA EN BLANCO
Si Gemini no encuentra impreso el IGV o la base, el gestor no inventa ni calcula: deja el dato en blanco y pinta la celda de amarillo para que lo completes tú. La única excepción es la lectura del código QR: como el QR no trae la base, el gestor la calcula restando el IGV al total.
SI GEMINI ESTÁ SATURADO (ERROR 503)
El sistema reintenta hasta 3 veces con cada modelo, esperando 10 segundos entre intentos, y si el modelo principal no responde, prueba con el de respaldo. Si los servidores de Google siguen sin responder, mueve el archivo a 03 Revisar. Espera unos minutos y vuelve a subirlo. No es un fallo del gestor, sino de los servidores de Google.
Un archivo muy borroso también termina en 03 Revisar, para que lo revises a mano.
Cómo lee cada tipo de archivo
| Archivo | Cómo se lee | Se envía a servicios externos |
|---|---|---|
| XML de SUNAT | Lee los datos directo del archivo, sin IA | No |
| Foto (JPG, PNG o HEIC) | Primero intenta leer el código QR del comprobante. Si no hay un QR legible, la lee con Gemini. Las fotos HEIC se convierten antes a JPG | useqr.app (QR) y, si hace falta, Gemini |
| Lo lee Gemini directamente, sin probar el QR | Gemini |
- Cada llamada a Gemini espera hasta 90 segundos una respuesta.
- ApiPerú se consulta solo cuando el comprobante trae RUC pero no se leyó el nombre del proveedor, algo habitual al leer el QR. En el panel de ApiPerú, el plan Gratuito mostraba un tope de 100 consultas por ciclo (mensual). Revisa el tuyo, porque los planes pueden cambiar.
- Solo las fotos se convierten a PDF. Los PDF que subes se mueven tal cual a la carpeta del mes.
MODELOS DE GEMINI SUGERIDOS
El código usa dos modelos: gemini-3.1-flash-lite como principal y gemini-3.8-flash como respaldo. Son los modelos que se sugieren y con los que se probó esta solución. Si Google los renombra o los retira, cambia sus nombres en el bloque CONFIG que está al inicio del código en Apps Script (MODELO_PRIMARIO y MODELO_FALLBACK).
Revisa siempre lo que registra. Una IA puede equivocarse al leer un comprobante, así que compara los montos con el original antes de usarlos para tu contabilidad.
Una advertencia sobre tus datos
Para leer tus comprobantes, el gestor envía las imágenes y los archivos a la API de Gemini, envía las fotos a useqr.app (un servicio externo que lee códigos QR) y consulta los RUC en ApiPerú. Eso significa que esos datos salen de tu cuenta de Google hacia esos servicios. No es motivo de alarma, pero conviene que lo sepas antes de subir documentos:
- Las fotos pasan primero por useqr.app, para intentar leer su código QR. Los PDF y los XML no pasan por ese servicio.
- Revisa los términos de uso del plan gratuito de Gemini: en los planes gratuitos, lo que envías puede usarse para mejorar los productos de Google.
- Evita subir comprobantes con datos sensibles que no quieras compartir con terceros.
- No compartas tus llaves con nadie. Si crees que se filtraron, créalas de nuevo.
Si algo no funciona
Ninguna solución es eterna: los servicios cambian sus planes, sus menús y sus límites. Si algo de esta guía dejó de funcionar, avísanos en la comunidad de Telegram y lo corregimos.
Instalas el gestor una vez y después solo subes tus comprobantes a una carpeta. Lo que registra, lo revisas tú.
¿Listo para empezar?
Crea tu hoja de Google Sheets en la Fase 1 y sigue los pasos. Lo instalas una sola vez y después solo subes tus comprobantes a una carpeta.
FRASE DE VIGENCIA
Esto funciona a fecha de noviembre 2026. Si algo cambia o deja de funcionar, visita la comunidad de Telegram. Únete para estar al día.
