CASO DE ESTUDIO · PYTHON · PLAYWRIGHT · AUTOMATIZACIÓN

Ruffo

Automatizar un flujo documental real sin detenerse ante incidencias.

Ruffo es un prototipo de aplicación para macOS que controla una automatización documental real. Conecta Gmail, navegación web, descarga y lectura de PDFs, búsqueda en un portal interno, carga de documentos y validación de estados, incorporando recuperación automática ante errores de servidor y sesiones caducadas.
Python · Playwright · Browser Automation · PDF Processing · macOS.

Ficha del proyecto

Tipo de proyecto
Automatización documental · Aplicación de escritorio
Entorno Google Chrome real · Sesiones autenticadas
Mi participación
Arquitectura · Python · Automatización web · Recuperación de incidencias · UI
Base tecnológica
Python · Tkinter · Playwright
pypdf · Chrome DevTools Protocol
Áreas de trabajo
Gmail · PDFs · Multi-cuenta · Portales · Estados · Logs
Ruffo · Aplicación de escritorio y motor de automatización en pruebas reales.
EL RETO

Un flujo manual con varios sistemas, estados e incidencias.

El proceso depende de varias aplicaciones abiertas y autenticadas. Un correo inicia el trabajo, una sede externa entrega el documento y un portal interno recibe el PDF. El reto era automatizar esa secuencia sin reprocesar correos, sin cambiar estados incorrectamente y sin detener todo el sistema cuando una web falla.

El flujo que debía coordinar

• Detectar únicamente correos «Solicitud Respondida» no leídos.

• Extraer el identificador completo de la solicitud.

• Descargar «Nota simple» o «Nota de localización» en PDF.

• Buscar la solicitud en el portal interno y cargar el documento.

• Procesar solo estados válidos y evitar duplicados.

• Recuperarse de errores de red, sesión y servidor sin detener Ruffo.

MI INTERVENCIÓN

Convertí el flujo en un motor supervisado desde una aplicación.

Desarrollé una interfaz de escritorio en Python/Tkinter y un motor de automatización con Playwright. La aplicación prepara el entorno, administra Chrome, muestra estado, cuenta actual, solicitud, último resultado, logs y acceso a los PDFs, mientras el motor ejecuta el proceso y reporta eventos.
01

Chrome real mediante CDP

Ruffo comprueba Chrome DevTools Protocol en el puerto 9222. Si Chrome controlado no está disponible, lo abre automáticamente con una instancia y perfil propios, espera hasta que CDP responda y solo entonces inicia el agente.
02

Gmail y rotación de cuentas

El motor trabaja con múltiples cuentas Gmail autenticadas y busca exclusivamente mensajes no leídos del remitente y asunto esperados. La rotación permite continuar con la siguiente cuenta cuando una queda sin pendientes o presenta una incidencia.
03

PDF como vía alternativa

Si el identificador del correo devuelve cero resultados reales en el portal, Ruffo lee el PDF con pypdf. Busca el identificador oficial de la solicitud y documentos como NIE, DNI, NIF, CIF, TIE o pasaporte dentro de la sección de titularidad, evitando confundir datos de otras personas mencionadas en el documento.
04

Seguridad de estado

Ruffo no cambia estados del portal. Solo carga el PDF cuando el registro ya está en En trámite. Si encuentra una solicitud Procesada o un estado distinto, la omite y continúa con la siguiente.
UN EJEMPLO TÉCNICO

Distinguir «no existe» de «el servidor está caído».

Una parte crítica era evitar que un error 500, 502, 503, 504, timeout o problema de red se interpretara como «ID no encontrado». Ruffo clasifica primero el estado técnico del portal y solo acepta un resultado cero cuando la página está sana y la búsqueda se ha ejecutado correctamente.
Ante errores técnicos realiza tres reintentos rápidos con esperas de 5, 10 y 20 segundos. Si el servicio sigue caído, continúa intentando cada 60 segundos. Cuando detecta una sesión caducada mantiene Ruffo activo y comprueba periódicamente hasta que el usuario vuelva a iniciar sesión.

Tres reglas que protegen el proceso

0 resultados reales
Solo se acepta si el portal está operativo y respondió correctamente.
Estado del registro
Nunca cambia estados; procesa únicamente si ya está «En trámite».
Botones dentro de frames
También busca «Subir y enviar» dentro de frames antes de declarar una incidencia.
RESILIENCIA Y OPERACIÓN

La automatización no debía detenerse ante el primer problema.

El objetivo no era simplemente automatizar clics, sino mantener el proceso funcionando durante una jornada real. Por eso Ruffo registra incidencias, limpia pestañas, conserva sesiones, rota cuentas y diferencia errores recuperables de casos que deben quedar documentados y continuar.
RECUPERACIÓN

Servidor y sesión

El motor detecta errores técnicos del portal, recarga y reintenta la misma solicitud. Una sesión caducada no mata el proceso: Ruffo espera la intervención de login y continúa cuando el portal vuelve a estar disponible.
TRAZABILIDAD

Logs e incidencias

La aplicación dispone de registros de actividad, archivos separados para fallos e incidencias y eventos estructurados que actualizan la interfaz con estados como solicitud no encontrada, recuperación del portal, sesión caducada o proceso completado.
AUTONOMÍA

Sin API de IA para ejecutar el flujo

El motor usa Playwright, pypdf y reglas deterministas. El código revisado declara explícitamente que no utiliza Claude, Anthropic ni browser-use y que no consume tokens para ejecutar la automatización.
FORMA DE TRABAJO

Automatizar sin perder control.

El proyecto fue evolucionando a partir de incidencias encontradas durante pruebas reales. Cada ajuste busca que Ruffo pueda continuar, informar qué ocurrió y evitar acciones peligrosas cuando no puede confirmar el estado del sistema.
01

Detectar

Identificar correo, solicitud, estado del portal y condiciones técnicas antes de actuar.
02

Procesar

Automatizar navegación, descarga, lectura de PDF, búsqueda y carga del documento.
03

Validar

Comprobar estado, resultados de búsqueda y disponibilidad real de controles antes de continuar.
04

Recuperar

Registrar la incidencia, reintentar cuando corresponde y pasar al siguiente caso sin detener todo Ruffo.
ESTADO DEL PROYECTO

Un prototipo de automatización preparado para pruebas reales.

La versión revisada es Ruffo v0.5.2.1. Integra aplicación de escritorio, motor Playwright, perfil propio de Chrome, rotación de cuentas, lectura de PDFs, control de estados y recuperación ante incidencias. Los archivos internos se guardan bajo Application Support de macOS en lugar de depender de una carpeta manual en el Escritorio.
El propio README lo define correctamente como una versión de pruebas reales, todavía no como una versión comercial firmada. Este caso demuestra mi capacidad para convertir un flujo administrativo complejo en una automatización supervisada, resiliente y orientada a operación continua.

Tecnologías utilizadas

Aplicación
Python · Tkinter
macOS
Automatización
Playwright · AsyncIO
Chrome DevTools Protocol
Documentos y flujo
pypdf · Gmail · PDFs
Portales web · Multi-cuenta
Operación
Shell scripts · Logs
Reintentos · Perfil Chrome persistente

Más proyectos y casos de estudio

Scroll al inicio