Bloque Excel Load

El bloque Excel Load permite leer y cargar datos desde archivos Excel (XLSX, XLS) en tu proceso de automatización. Este bloque extrae datos de una hoja específica y los almacena en una lista para su posterior procesamiento.

Descripción General

Este bloque es esencial para procesos que necesitan leer información desde archivos Excel, como:

• Procesamiento de listas de clientes
• Importación de datos de facturación
• Lectura de inventarios
• Carga de datos maestros
• Extracción de reportes

Caso de uso común

El bloque Excel Load es ideal para iniciar procesos de automatización que procesan datos masivos desde hojas de cálculo, permitiendo iterar sobre cada fila del archivo.

Parámetros

1. Ruta al archivo (file_path)

Nombre de variable: file_path Tipos permitidos: secret, data

Ruta completa o relativa al archivo Excel que se desea leer.

Descripción: Especifica la ubicación del archivo Excel en tu sistema local. Puede ser una ruta absoluta o relativa al directorio de trabajo del robot.

Ejemplos:

# Ruta absoluta (Windows)
file_path = "C:\\Users\\usuario\\Documents\\facturas.xlsx"

# Ruta absoluta (Linux/Mac)
file_path = "/home/usuario/documentos/facturas.xlsx"

# Ruta relativa
file_path = "./data/clientes.xlsx"
file_path = "input/pedidos.xlsx"

Importante

En Windows, usa barras invertidas dobles (\\) o barras normales (/) en las rutas. Evita usar barras invertidas simples que pueden causar errores.

Consideraciones:

• El archivo debe existir y ser accesible
• El robot debe tener permisos de lectura sobre el archivo
• Soporta formatos: .xlsx, .xls, .xlsm
• Puede almacenarse en data o como secret si contiene información sensible

---

2. Hoja del Excel (sheet)

Nombre de variable: sheet Tipos permitidos: data

Nombre de la hoja de Excel desde la cual se extraerán los datos.

Descripción: Especifica qué hoja del archivo Excel se debe leer. El nombre debe coincidir exactamente con el nombre de la hoja en el archivo.

Ejemplos:

# Nombre de hoja común
sheet = "Hoja1"
sheet = "Sheet1"

# Nombres personalizados
sheet = "Clientes"
sheet = "Facturas_Enero"
sheet = "Datos_2024"

Consideraciones:

• El nombre es sensible a mayúsculas/minúsculas
• No incluyas espacios al inicio o final del nombre
• Si el nombre contiene espacios, usa el nombre exacto: "Mis Datos"
• Si la hoja no existe, el bloque generará un error

Consejo

Si no conoces el nombre exacto de la hoja, abre el archivo Excel y verifica el nombre en la pestaña inferior. También puedes usar el nombre por defecto “Hoja1” o “Sheet1” si no se ha renombrado.

---

3. Columnas (column_keys)

Nombre de variable: column_keys Tipos permitidos: list

Lista con los nombres de las columnas que se desean extraer del archivo Excel.

Descripción: Define qué columnas del archivo Excel se leerán y almacenarán. Solo se extraerán las columnas especificadas, ignorando el resto.

Formato: Lista de strings con los nombres exactos de las columnas (primera fila del Excel).

Ejemplos:

# Ejemplo básico - facturas
column_keys = ["NumeroFactura", "Cliente", "Importe", "Fecha"]

# Ejemplo - clientes
column_keys = ["Nombre", "Email", "Telefono", "Empresa"]

# Ejemplo - productos
column_keys = ["SKU", "Descripcion", "Precio", "Stock", "Categoria"]

# Ejemplo - empleados
column_keys = ["ID_Empleado", "Nombre_Completo", "Departamento", "Salario"]

Consideraciones:

• Los nombres deben coincidir exactamente con los encabezados de las columnas en Excel (primera fila)
• Es sensible a mayúsculas/minúsculas
• Si una columna no existe, se generará un error
• Puedes especificar columnas en cualquier orden
• El orden especificado se mantendrá en los datos cargados

Mejores prácticas

• Usa nombres de columna descriptivos y sin espacios en tus archivos Excel
• Evita caracteres especiales en los nombres de columnas
• Si tus columnas tienen espacios, úsalos exactamente: ["Nombre Completo", "Fecha de Nacimiento"]

---

4. Lista de resultado (result_list)

Nombre de variable: result_list Tipos permitidos: list

Lista donde se almacenarán los datos extraídos del archivo Excel.

Descripción: Variable de salida que contendrá todos los registros leídos. Cada fila del Excel se convierte en un diccionario dentro de la lista.

Formato de salida:

# Estructura de result_list
result_list = [
    {
        "NombreColumna1": "valor1",
        "NombreColumna2": "valor2",
        "NombreColumna3": "valor3"
    },
    {
        "NombreColumna1": "valor4",
        "NombreColumna2": "valor5",
        "NombreColumna3": "valor6"
    }
    # ... más filas
]

Ejemplo real - Facturas:

# Archivo Excel con columnas: NumeroFactura, Cliente, Importe, Fecha
result_list = [
    {
        "NumeroFactura": "F-2024-001",
        "Cliente": "Empresa ABC",
        "Importe": "1500.00",
        "Fecha": "2024-01-15"
    },
    {
        "NumeroFactura": "F-2024-002",
        "Cliente": "Empresa XYZ",
        "Importe": "2300.50",
        "Fecha": "2024-01-16"
    }
]

Uso posterior:

# Acceder a los datos cargados
total_registros = len(result_list)
primera_factura = result_list[0]
numero_primera = primera_factura["NumeroFactura"]

# Iterar sobre los registros
for registro in result_list:
    numero = registro["NumeroFactura"]
    cliente = registro["Cliente"]
    importe = registro["Importe"]
    # Procesar cada registro...

Importante

Todos los valores se cargan como strings (texto). Si necesitas realizar operaciones numéricas, deberás convertir los valores:

importe_numerico = float(registro["Importe"])

---

Configuración del Bloque

Configuración Básica

block_type: excel_load
parameters:
  file_path: "C:\\datos\\facturas.xlsx"
  sheet: "Facturas"
  column_keys: ["NumeroFactura", "Cliente", "Importe", "Estado"]
  result_list: facturas_cargadas

Configuración con Variables

block_type: excel_load
parameters:
  file_path: ${ruta_archivo}  # Variable definida previamente
  sheet: ${nombre_hoja}
  column_keys: ${columnas_a_leer}
  result_list: datos_excel

---

Casos de Uso

Caso 1: Procesamiento de Facturas

Escenario: Leer facturas pendientes desde un Excel y procesarlas una por una.

Configuración:

block_type: excel_load
parameters:
  file_path: "C:\\facturas\\pendientes_enero.xlsx"
  sheet: "Facturas"
  column_keys: ["NumeroFactura", "Proveedor", "Importe", "Vencimiento"]
  result_list: facturas_pendientes

Resultado:

• Se cargan todas las facturas en facturas_pendientes
• Cada factura es un diccionario con las 4 columnas especificadas
• Listos para procesar en bloques iteradores posteriores

---

Caso 2: Importación de Clientes

Escenario: Cargar lista de clientes nuevos para dar de alta en un sistema CRM.

Configuración:

block_type: excel_load
parameters:
  file_path: "./input/clientes_nuevos.xlsx"
  sheet: "Sheet1"
  column_keys: ["Nombre", "Email", "Telefono", "Empresa", "Ciudad"]
  result_list: clientes_a_procesar

Uso posterior:

# En bloque Python posterior
for cliente in clientes_a_procesar:
    nombre = cliente["Nombre"]
    email = cliente["Email"]
    telefono = cliente["Telefono"]

    # Dar de alta en CRM
    resultado = crear_cliente_crm(nombre, email, telefono)

---

Caso 3: Actualización Masiva de Inventario

Escenario: Leer actualizaciones de stock desde Excel y aplicarlas al sistema de inventario.

Configuración:

block_type: excel_load
parameters:
  file_path: "\\\\servidor\\compartido\\inventario_actualizado.xlsx"
  sheet: "Stock"
  column_keys: ["SKU", "NuevoStock", "Ubicacion", "FechaActualizacion"]
  result_list: actualizaciones_stock

Ventajas:

• Soporta rutas de red (UNC paths)
• Permite procesar miles de actualizaciones
• Mantiene trazabilidad con fecha de actualización

---

Caso 4: Lectura de Datos Maestros

Escenario: Cargar catálogo de productos para validación en otros procesos.

Configuración:

block_type: excel_load
parameters:
  file_path: "./master_data/catalogo_productos.xlsx"
  sheet: "Productos"
  column_keys: ["CodigoProducto", "Descripcion", "PrecioVenta", "Categoria", "Activo"]
  result_list: catalogo_productos

Uso:

# Crear diccionario para búsqueda rápida
catalogo_dict = {
    producto["CodigoProducto"]: producto
    for producto in catalogo_productos
}

# Validar si un producto existe
if codigo in catalogo_dict:
    precio = catalogo_dict[codigo]["PrecioVenta"]

---

Validaciones y Controles

Validaciones Automáticas

El bloque Excel Load realiza las siguientes validaciones:

1. Existencia del archivo: Verifica que el archivo existe en la ruta especificada
2. Formato válido: Confirma que el archivo es un Excel válido (.xlsx, .xls, .xlsm)
3. Existencia de la hoja: Valida que la hoja especificada existe en el archivo
4. Existencia de columnas: Verifica que todas las columnas especificadas existen en la hoja
5. Permisos de lectura: Confirma que el robot tiene acceso de lectura al archivo

Errores Comunes

Error	Causa	Solución
File not found	El archivo no existe en la ruta especificada	Verifica la ruta y existencia del archivo
Sheet not found	La hoja no existe en el archivo	Revisa el nombre exacto de la hoja (mayúsculas)
Column not found	Una columna especificada no existe	Verifica los nombres de las columnas en la primera fila
Permission denied	Sin permisos de lectura	Verifica permisos del archivo o ejecútalo como administrador
File in use	Archivo abierto en otra aplicación	Cierra el Excel antes de ejecutar el proceso
Corrupted file	Archivo Excel corrupto o dañado	Repara el archivo o usa una copia de respaldo

---

Mejores Prácticas

1. Preparación del Archivo Excel

✅ Recomendado:

| NumeroFactura | Cliente      | Importe | Estado    |
|---------------|--------------|---------|-----------|
| F-001         | Empresa A    | 1500.00 | Pendiente |
| F-002         | Empresa B    | 2300.50 | Pagada    |

❌ Evitar:

• Filas vacías al principio
• Múltiples filas de encabezados
• Celdas combinadas en los encabezados
• Formato de tabla de Excel (usar rango normal)
• Espacios en blanco antes/después de los nombres de columna

2. Nombres de Columnas

✅ Buenos nombres:

• NumeroFactura
• FechaProceso
• ImporteTotal
• ID_Cliente

❌ Nombres problemáticos:

• Número de Factura (espacios)
• Fecha/Proceso (caracteres especiales)
• Total $ (símbolos)
• Columnas sin nombre

3. Gestión de Rutas

# ✅ Bueno: Usar variables de entorno o configuración
file_path = "${carpeta_entrada}/facturas.xlsx"

# ✅ Bueno: Rutas relativas para portabilidad
file_path = "./data/input/facturas.xlsx"

# ⚠️ Precaución: Rutas absolutas (menos portable)
file_path = "C:\\MiProyecto\\data\\facturas.xlsx"

# ✅ Bueno: Rutas de red
file_path = "\\\\servidor\\compartido\\facturas.xlsx"

4. Manejo de Datos Cargados

# ✅ Verificar que se cargaron datos
if len(result_list) == 0:
    log.warning("No se encontraron datos en el archivo Excel")
    # Manejar caso sin datos
else:
    log.info(f"Se cargaron {len(result_list)} registros")

# ✅ Validar estructura esperada
primer_registro = result_list[0]
if "NumeroFactura" not in primer_registro:
    log.error("Falta columna NumeroFactura")

# ✅ Convertir tipos de datos
for registro in result_list:
    registro["Importe"] = float(registro["Importe"])
    registro["Fecha"] = parse_date(registro["Fecha"])

5. Rendimiento

Para archivos grandes (>1000 filas):

• ✅ Considera dividir el archivo en lotes más pequeños
• ✅ Usa solo las columnas necesarias en column_keys
• ✅ Implementa logging para monitorear el progreso
• ⚠️ Ten en cuenta el uso de memoria

Para archivos muy grandes (>10000 filas):

• Considera usar bloques especializados de procesamiento por lotes
• Evalúa si es necesario cargar todo en memoria
• Implementa procesamiento por chunks si está disponible

---

Ejemplos Completos

Ejemplo 1: Proceso Completo de Facturación

# Bloque 1: Cargar facturas
- block_type: excel_load
  parameters:
    file_path: "./input/facturas_mes.xlsx"
    sheet: "Facturas"
    column_keys: ["NumeroFactura", "Cliente", "NIF", "Importe", "Fecha"]
    result_list: facturas_a_procesar

# Bloque 2: Iterar sobre facturas (configurado en la plataforma)

# Bloque 3: Procesar cada factura (Python)
- block_type: python
  code: |
    factura = current_item  # Factura actual de la iteración

    # Validar datos
    if not factura["NIF"]:
        log.force_ko(f"Factura {factura['NumeroFactura']}: NIF vacío")

    # Procesar en sistema externo
    try:
        resultado = enviar_a_face(
            numero=factura["NumeroFactura"],
            cliente=factura["Cliente"],
            nif=factura["NIF"],
            importe=float(factura["Importe"])
        )
        log.result("ok", f"Factura {factura['NumeroFactura']} procesada")
    except Exception as e:
        log.result("error", f"Error en factura {factura['NumeroFactura']}: {str(e)}")

Ejemplo 2: Validación y Enriquecimiento de Datos

# Cargar datos de clientes
- block_type: excel_load
  parameters:
    file_path: "./clientes_nuevos.xlsx"
    sheet: "Hoja1"
    column_keys: ["Nombre", "Email", "Telefono", "Ciudad"]
    result_list: clientes_raw

# Validar y enriquecer
- block_type: python
  code: |
    clientes_validos = []
    clientes_invalidos = []

    for cliente in clientes_raw:
        # Validar email
        if "@" not in cliente["Email"]:
            clientes_invalidos.append({
                **cliente,
                "motivo": "Email inválido"
            })
            continue

        # Validar teléfono
        telefono_limpio = cliente["Telefono"].replace(" ", "").replace("-", "")
        if len(telefono_limpio) < 9:
            clientes_invalidos.append({
                **cliente,
                "motivo": "Teléfono inválido"
            })
            continue

        # Enriquecer datos
        cliente_procesado = {
            **cliente,
            "Telefono": telefono_limpio,
            "Email": cliente["Email"].lower().strip(),
            "FechaCarga": datetime.now().strftime("%Y-%m-%d")
        }
        clientes_validos.append(cliente_procesado)

    # Guardar para siguiente bloque
    data.set("clientes_validos", clientes_validos)
    data.set("clientes_invalidos", clientes_invalidos)

    log.info(f"Válidos: {len(clientes_validos)}, Inválidos: {len(clientes_invalidos)}")

---

Integración con Otros Bloques

Con Bloque Iterador

El bloque Excel Load se usa típicamente seguido de un bloque iterador:

[Excel Load] → [Iterator] → [Process Each Item]

Flujo:

1. Excel Load carga todos los datos en una lista
2. Iterator toma la lista y ejecuta los bloques siguientes por cada elemento
3. Cada iteración procesa un registro del Excel

Con Bloques de Validación

[Excel Load] → [Python Validation] → [Filter] → [Process Valid Items]

Con Bloques de Escritura

[Excel Load] → [Process] → [Excel Write] → [Report]

Ejemplo: Leer datos, procesarlos, y escribir resultados en otro Excel.

---

Troubleshooting

Problema: “No se encuentran datos”

Síntomas: result_list está vacío

Causas posibles:

• La hoja está vacía
• Solo hay encabezados sin datos
• Los nombres de columna no coinciden

Soluciones:

1. Verifica que la hoja tiene datos además de los encabezados
2. Abre el Excel y confirma que hay filas con información
3. Revisa que los nombres en column_keys coinciden exactamente

Problema: “Columna no encontrada”

Síntomas: Error indicando que una columna no existe

Soluciones:

1. Abre el Excel y verifica el nombre exacto en la primera fila
2. Verifica mayúsculas/minúsculas
3. Comprueba que no hay espacios extra: "Nombre " vs "Nombre"
4. Si la columna tiene espacios, inclúyelos: "Número de Factura"

Problema: “Archivo en uso”

Síntomas: No se puede leer el archivo

Soluciones:

1. Cierra el archivo Excel si está abierto
2. Cierra otras aplicaciones que puedan tener el archivo abierto
3. Verifica que otro proceso no esté usando el archivo
4. En último caso, reinicia el robot

Problema: Caracteres especiales mal leídos

Síntomas: Acentos o ñ se ven incorrectos

Soluciones:

1. Guarda el Excel como .xlsx (no .xls)
2. Verifica la codificación del archivo
3. Usa Excel moderno para crear el archivo
4. Evita copiar/pegar desde otras fuentes con codificación diferente

---

¿Necesitas más ayuda?

Si esta guía no resolvió tu problema o encontraste algún error en la documentación:

• Soporte técnico: help@heptora.com
• Describe claramente el problema que encontraste
• Incluye capturas de pantalla si es posible
• Indica qué pasos de la documentación seguiste

Nuestro equipo de soporte te ayudará a resolver cualquier problema.

Recursos Relacionados

• Bloque Excel Write - Escribir datos en archivos Excel
• Bloques de Automatización - Guía general de bloques
• Lenguaje Heptora - Referencia del lenguaje
• Python en Heptora - Uso de Python en bloques personalizados