Proyecto principal · IA aplicada

FacturasGPT5

Automatización documental con IA y OpenAI API para convertir facturas PDF en datos estructurados, revisables y listos para analizar.

Descargar código

Contexto del proyecto

Problema planteado

El reto era automatizar la extracción de información desde facturas eléctricas en PDF, un formato poco homogéneo y difícil de procesar de forma tradicional. Cada comercializadora puede presentar los datos con estructuras distintas, nombres de campos diferentes, tablas variables y secciones distribuidas en varias páginas.

El objetivo del proyecto fue transformar esa documentación en una salida estructurada, revisable y útil para análisis comercial: CUPS, titular, tarifa, periodo facturado, potencias contratadas, consumos por periodo, precios de energía, precios de potencia y otros datos relevantes para preparar o comparar ofertas.

En lugar de limitarme a extraer texto plano o aplicar reglas rígidas, diseñé un flujo basado en IA generativa capaz de interpretar documentos con formatos variables y convertirlos en datos tabulares listos para trabajar.

Flujo de pensamiento

La decisión clave fue no pedir al modelo que pasara directamente de un PDF complejo a una tabla final. Ese enfoque puede ser poco trazable, difícil de revisar y propenso a errores cuando el documento cambia de formato.

Por eso diseñé una arquitectura en dos fases. Primero, el sistema realiza una extracción amplia del contenido visible de la factura, priorizando no perder información útil. Después, una segunda fase convierte esa capa textual intermedia en un JSON plano con campos fijos y reglas específicas de facturación eléctrica española.

Esta separación permite revisar cada etapa por separado, detectar errores antes de la consolidación final y mantener mayor control sobre la salida. El JSON individual de cada factura funciona como fuente de verdad antes de generar el CSV final.

Además, el sistema incorpora fallback visual: si el PDF no contiene texto embebido útil, sus páginas se convierten en imágenes y se procesan mediante un modelo con capacidades visuales.

Pipeline y arquitectura

Flujo visual

Explicación técnica

FacturasGPT5 funciona como un pipeline en Python para procesar facturas eléctricas en PDF y convertirlas en datos estructurados. El sistema combina procesamiento documental, llamadas a modelos de lenguaje, prompts especializados, generación de JSON y exportación final a CSV compatible con Excel.

La primera fase intenta extraer texto embebido del PDF. Si el contenido textual es suficiente, se envía al modelo junto con un prompt diseñado para maximizar la cobertura de información relevante. Si el texto extraído es insuficiente, el sistema activa un fallback multimodal: convierte las páginas del PDF en imágenes y las procesa mediante visión para recuperar la información visible.

La segunda fase toma el texto intermedio generado por la IA y lo transforma en un JSON plano con campos fijos. Esta fase utiliza reglas específicas para facturación eléctrica española, incluyendo la distinción entre titular y comercializadora, normalización de tarifas 2.0TD y 3.0TD, extracción de periodos P1-P6 y tratamiento de campos ausentes.

Finalmente, cada JSON se guarda de forma individual como resultado estructurado por factura. A partir de esos JSON, el sistema genera un CSV final con codificación y separador compatibles con Excel en España.

Pasos técnicos

Entrada: el usuario coloca las facturas eléctricas en PDF dentro de una carpeta de entrada. El sistema está preparado para procesar documentos con estructuras variables, incluyendo facturas 2.0TD, 3.0TD y otros formatos habituales del mercado eléctrico español.
Extracción: el sistema intenta leer el texto embebido del PDF. Si la extracción tradicional no devuelve contenido suficiente, se activa un fallback visual que convierte el documento en imágenes y permite recuperar la información visible mediante IA multimodal.
Capa intermedia: la primera pasada genera un volcado textual amplio y revisable. Esta capa conserva nombres, importes, unidades, periodos, identificadores y datos comerciales relevantes sin forzar todavía una estructura tabular definitiva.
Normalización: una segunda pasada convierte el texto intermedio en un JSON plano con campos fijos. El prompt aplica reglas específicas para evitar confusiones entre titular y comercializadora, normalizar tarifas y extraer correctamente potencias, consumos y precios por periodo.
Consolidación: cada factura genera su propio JSON individual, que actúa como fuente de verdad. Después, el sistema consolida todos los JSON disponibles y genera un CSV final compatible con Excel, preparado para análisis, revisión y reporting.

Decisiones técnicas clave

Pipeline en dos fases

Separé la extracción de información y la normalización estructurada para mejorar la trazabilidad, facilitar la revisión y reducir errores frente a una conversión directa de PDF a tabla.

Fallback multimodal

El sistema no depende únicamente del texto embebido en el PDF. Si la extracción textual no es suficiente, convierte el documento en imágenes y utiliza visión para recuperar la información visible.

JSON por factura como fuente de verdad

Cada documento genera un JSON individual antes de crear el CSV final. Esto permite auditar resultados, reprocesar salidas y revisar errores sin volver a ejecutar todo el pipeline.

Prompts especializados por fase

La primera pasada prioriza cobertura y fidelidad literal. La segunda aplica reglas estrictas para convertir el contenido en un esquema estable, sin inferir datos no visibles.

Exportación pensada para uso real

El resultado final se genera como CSV compatible con Excel en España, usando separador ; y codificación adecuada para mantener columnas y acentos correctamente.

Implementación y alcance

Mi rol

Diseñé y desarrollé el sistema completo: arquitectura de procesamiento, lógica de extracción, prompts especializados, organización de entradas y salidas, generación de JSON por documento y exportación final a CSV.

También definí las reglas de normalización para adaptar el sistema al dominio de la facturación eléctrica española, priorizando que la salida fuera entendible, revisable y útil para un flujo real de análisis comercial.

El proyecto me permitió trabajar una parte clave de la IA aplicada: transformar documentos no estructurados en datos estructurados mediante un pipeline reproducible, controlado y orientado a negocio.

Stack

IA y modelos

OpenAI API · GPT-5 · GPT-4 Turbo · Vision fallback

Procesamiento documental

Python · pypdf · pdf2image · Pillow

Estructuración de datos

JSON · CSV · Excel · Prompt Engineering

Automatización

CLI · procesamiento por lotes · idempotencia · merge de resultados

Limitaciones del sistema

El sistema está diseñado como una solución de automatización documental asistida por IA, no como una herramienta infalible sin revisión humana. Las facturas eléctricas pueden variar mucho entre comercializadoras, formatos y calidades de PDF, por lo que la revisión de campos críticos sigue siendo recomendable.

Para mejorar la fiabilidad, el proyecto conserva salidas intermedias y JSON individuales por factura, facilitando la auditoría del resultado y el reprocesado en caso de error.

Privacidad de datos

El proyecto puede trabajar con documentos que contengan datos sensibles como titulares, direcciones, CUPS, NIF/CIF o importes. Para su presentación pública se utilizan ejemplos anonimizados o datos ficticios, evitando exponer información personal o contractual real.