siigo-pyme-excel

Skill para invocar el CLI ExcelSIIGO.exe que SIIGO S.A.S. distribuye con su software contable SIIGO Pyme (Colombia). Permite automatizar la importación y exportación de datos entre SIIGO Pyme (on-premise) y archivos Excel sin que el modelo tenga que memorizar la sintaxis del CLI.

Plataforma soportada: solo Windows (el CLI es PE32 nativo). En Linux
o macOS se requiere Wine o ejecución remota por RDP/PSExec.

SIIGO Pyme ≠ SIIGO Nube: este skill es para la versión escritorio
con EXCELSIIGO.exe. Para SIIGO Nube (API REST) usar otro skill.

1. Prerrequisitos

Antes de invocar el skill verifica que existan:

1. SIIGO Pyme instalado y con la empresa creada.
2. EXCELSIIGO.exe accesible. Por defecto el wrapper lo busca en

C:\Siigo\EXCELSIIGO.exe. Configurable vía SIIGO_EXE.

1. filepath.txt junto al EXCELSIIGO.exe (lo crea SIIGO al instalar).

El wrapper lo lee automáticamente para validar que la empresa solicitada coincide con la ruta declarada. Ver references/filepath-txt.md. Importante: la ruta declarada suele ser Z:\SIIWI0n\, NO C:\SIIWI0n\. Usa bash scripts/excel-siigo.sh list para ver la ruta detectada.

1. Usuario SIIGO con permisos sobre la empresa (clave de 8 caracteres).
2. Licencia SIIGO activa (la verificación la hace internamente el CLI

vía Actualizador.exe y CtrlSIIGOLic.gnt).

1. Carpeta LOGS escribible. Por defecto los logs van al mismo

directorio que el archivo de salida (--salida); también puedes configurar SIIGO_LOGS o pasar --logs al wrapper.

1. Espacio en disco suficiente para los .xlsx generados.

Dependencias Python (para el wrapper Python y procesamiento posterior)

Los scripts Python (excel-siigo.py, parse-filepath.py, parse-log.py, build-xlsx-template.py) requieren:

• Python 3.8+ (probado con 3.11 y 3.14)
• openpyxl ≥ 3.0 — para leer/escribir los .xlsx generados

pip install openpyxl
# o, en sistemas con PEP 668 (Ubuntu, etc.):
pip install --break-system-packages openpyxl

Si el usuario quiere procesar los .xlsx (filtrar, agregar, mesclar, convertir) más allá de lo que el CLI genera, también puede ser útil:

pip install pandas openpyxl  # procesamiento tabular avanzado

Dependencias de runtime (wrappers)

• Bash wrapper (scripts/excel-siigo.sh): requiere bash 4+ y

cmd.exe en PATH (Windows nativo, Git Bash, WSL). NO funciona en macOS sin cmd.exe.

• Python wrapper (scripts/excel-siigo.py): multiplataforma puro.

Funciona en Windows, macOS, Linux (con Wine si se invoca el .exe).

• PowerShell wrapper (scripts/excel-siigo.ps1): requiere PowerShell

5+ (incluido en Windows 10/11). Por defecto, Windows bloquea scripts .ps1 sin firmar; ejecuta primero: ``powershell Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned ``

Permisos de ejecución

En Linux/macOS/WSL los scripts necesitan bit de ejecución. Si acabas de clonar el repo y los scripts no corren, haz:

chmod +x scripts/*.sh scripts/*.py

En Windows el bit de ejecución no aplica, pero Git Bash puede requerir que los scripts estén en PATH para invocarlos sin ./scripts/.

Lo que el skill NO incluye (y debe estar ya en el sistema)

• EXCELSIIGO.exe — binario propietario de SIIGO Pyme. NO se

distribuye con el skill. Cada usuario lo tiene instalado en su propio Windows (típicamente C:\Siigo\EXCELSIIGO.exe).

• filepath.txt — archivo de configuración de SIIGO que apunta a la

empresa. Se crea al instalar SIIGO Pyme. NO se distribuye.

• Una instancia de SIIGO Pyme con la empresa creada y licencia activa.

El CLI no funciona sin esto.

• Credenciales de usuario SIIGO (8 caracteres). El usuario las

tiene; el skill NO las almacena por seguridad (§7).

Si el agente que invoca el skill NO tiene EXCELSIIGO.exe instalado ni la licencia, debe advertir al usuario que el skill no puede generar los .xlsx (sólo procesar los que ya generó antes en otra sesión).

Ejecuta primero el validador para detectar estos prerequisitos:

bash scripts/check-prereqs.sh

1.1 Validación de empresa contra filepath.txt

Antes de ejecutar cualquier GET/PUSH, el wrapper valida que la empresa solicitada (SIIGO_EMPRESA) coincide con la ruta declarada en el filepath.txt que acompaña al EXCELSIIGO.exe. Si no coincide, la ejecución se bloquea con un mensaje claro indicando a qué empresa apunta esa instalación, y recordando que filepath.txt solo referencia UNA empresa — para encontrar otras hay que buscar en otras rutas SIIWI* o en otras instalaciones de SIIGO.

Ejemplo de bloqueo (pides Z:\SIIWI99\, el EXCELSIIGO.exe apunta a Z:\SIIWI01\):

╔════════════════════════════════════════════════════════════════════╗
║  ADVERTENCIA: la empresa solicitada NO coincide con filepath.txt  ║
╚════════════════════════════════════════════════════════════════════╝

SIIGO_EMPRESA:  Z:\SIIWI99\

Empresa declarada en el filepath.txt de este EXCELSIIGO.exe:
  Esta instalación de EXCELSIIGO.exe apunta a:
    - id=01  ruta=Z:\SIIWI01\  unc=\\127.0.0.1\inmunotek

RECORDATORIO: filepath.txt NO lista todas las empresas — solo apunta
a UNA (la de esta instalación). Las demás pueden existir en otras
rutas SIIWI02, SIIWI03, ... o en otras unidades. Para descubrirlas:
  - Listar carpetas C:\SIIWInn\ (o Z:\SIIWInn\ si la unidad está montada)
  - Buscar otros EXCELSIIGO.exe: C:\Siigo2\, C:\Siigo3\, ...
  - Cada instalación tiene SU PROPIO filepath.txt apuntando a SU empresa

Si necesitas saltarte la validación (porque tu instalación tiene un layout no estándar), pasa --force:

bash scripts/excel-siigo.sh getter --fini 0 --ffin 99999999 \
    --salida C:/temp/t.xlsx --force --yes

Inspeccionar el filepath.txt manualmente:

python scripts/parse-filepath.py --exe C:/Siigo/EXCELSIIGO.exe

Más detalles en references/filepath-txt.md.

2. Configuración

Variables de entorno reconocidas por los wrappers:

⚠️ Seguridad: nunca hardcodees SIIGO_CLAVE en scripts. El wrapper
enmascara la clave en cualquier log que emita.

3. Uso rápido (comandos copy-paste)

Asume que estás en la raíz del skill y que SIIGO_* ya están exportadas.

3.1 Listar funciones disponibles

bash scripts/excel-siigo.sh list

3.2 Extraer (GET*) plantillas vacías (sólo encabezados)

Útil para conocer las columnas que SIIGO espera antes de un PUSH*:

bash scripts/excel-siigo.sh template GETTER
# Genera: assets/templates/GETTER_template.xlsx

3.3 Extraer movimiento contable de un periodo

bash scripts/excel-siigo.sh getmov \
    --fini 0501 --ffin 0531 \
    --tipo F --comp 001 002 \
    --nro 00000000001 99999999999 \
    --salida C:/SIIWI01/MovimientoContable.xlsx

3.4 Importar terceros a SIIGO

bash scripts/excel-siigo.sh pushter \
    --entrada C:/SIIWI01/Terceros.xlsx \
    --errores C:/SIIWI01/LOGS/ErrorTer.xlsx

Operación destructiva: el wrapper pedirá confirmación interactiva
salvo que pases --yes. Úsalo sólo cuando estés seguro.

3.5 Extraer saldos de bodega

bash scripts/excel-siigo.sh getbod \
    --prod 0010001000001 9999999999999 \
    --bodega 0001 9999 --mes 12 \
    --salida C:/SIIWI01/SaldosPorBodega.xlsx

3.6 Extraer informe (balance de comprobación por tercero)

bash scripts/excel-siigo.sh getinf \
    --tipo B --tercero 1 9999999999999 \
    --mes 03 12 \
    --salida C:/SIIWI01/BALANCEPORTERCEROS.xls

4. Catálogo rápido de funciones (las 12 más usadas)

Catálogo completo (46 funciones) en references/functions-catalog.md.

5. Forma del resultado (contrato JSON)

Todos los wrappers imprimen en stdout un JSON con esta forma:

{
  "ok": true,
  "exit_code": 0,
  "funcion": "GETMOV",
  "log_path": "C:\\SIIWI01\\LOGS\\ExcelSiigo.log",
  "log_lines": 42,
  "log_errors": [],
  "duration_ms": 1823,
  "output_file": "C:\\SIIWI01\\MovimientoContable.xlsx",
  "tail": "..."
}

En caso de error:

{
  "ok": false,
  "exit_code": 2,
  "funcion": "GETMOV",
  "log_path": "C:\\SIIWI01\\LOGS\\ExcelSiigo.log",
  "log_errors": ["070 Empresa no se encuentra instalada"],
  "duration_ms": 412,
  "tail": "070 Empresa no se encuentra instalada"
}

6. Errores típicos (resumen)

Tabla completa y procedimientos de recuperación en references/errors.md.

7. Seguridad y confirmación de operaciones destructivas

Cualquier función PUSH* (importa datos al SIIGO):

• Modifica la base de la empresa.
• Por defecto el wrapper pide confirmación interactiva (--yes para

saltarla).

• Si la variable de entorno SIIGOAUTOCONFIRM=1 está activa, salta la

confirmación (útil para pipelines CI/CD; no recomendado en producción).

• El .LOG se conserva siempre y se puede auditar con parse-log.py.

8. Codificación y rutas con caracteres especiales

• El manual oficial (C:\Siigo\ExcelSIIGO-Ayuda.LOG) está en Windows-1252.

Los acentos aparecen como A�o, Funci�n, etc. El skill normaliza todo a UTF-8.

• Las rutas con espacios o tildes (ej. C:\Mi Empresa 2025\) deben

pasarse siempre entre comillas dobles en Bash. El wrapper lo hace automáticamente.

Más detalles en references/encoding.md.

9.1 Limitación: EXCELSIIGO.exe es un binario GUI

EXCELSIIGO.exe es un ejecutable GUI de Windows (PE32 GUI, no consola). Eso significa que:

• ✅ Funciona correctamente en sesiones Windows interactivas (CMD,

PowerShell, doble-clic, RDP).

• ✅ Funciona en tareas programadas que corren bajo la cuenta del

usuario con sesión abierta.

• ❌ NO funciona en shells headless (CI/CD sin display, SSH puro,

WSL sin X server, sesiones de chat remotas) — el binario muere silenciosamente al intentar inicializar la GUI: rc=0, sin log, sin XLSX de salida.

• ❌ NO funciona con nohup o detached sin un display server.

Síntomas típicos del problema:

• excel-siigo.sh devuelve ok: true, exit_code: 0 pero no se genera

ni el .log ni el .xlsx de salida.

• El archivo .log queda en 0 bytes.
• El .xlsx nunca aparece en la ruta solicitada.

Diagnóstico:

file "C:/Siigo/EXCELSIIGO.exe"
# Debe decir: PE32 executable for MS Windows ... (GUI), Intel i386
# Si dice (console) en vez de (GUI), esta limitación no aplica.

Workaround (cuando se necesita automatización real): lanzar el comando desde una tarea programada de Windows que corra bajo SYSTEM o el usuario con escritorio, y consumir el .xlsx resultante. NO es viable automatizar EXCELSIIGO.exe desde shells sin GUI.

Si el agente que invoca el skill está en un shell headless, debe advertir al usuario que el comando fallará silenciosamente y sugerirle ejecutarlo en su propia sesión Windows.

9. Cuándo NO usar este skill

• SIIGO Nube (API REST). Usar el conector HTTP correspondiente.
• SIIGO Empresarial (versión enterprise). El CLI es distinto; este

skill está orientado a Pyme.

• Lectura directa de la base de datos SIIGO (Access/SQL Anywhere). El

CLI es la vía soportada.

• macOS/Linux sin Wine. No soportado oficialmente.
• Shells headless o automatizaciones sin sesión interactiva (CI, WSL

sin X server, sesiones SSH puras, este chat). Ver §9.1 abajo.

10. Mantenimiento

Cuando SIIGO publique una nueva versión de EXCELSIIGO.exe:

1. Ejecuta EXCELSIIGO.exe sin empresa → captura el manual actualizado.
2. Sustituye references/excel-siigo-help.md con la nueva versión.
3. Actualiza references/functions-catalog.md si hay funciones nuevas o

params que cambiaron.

1. Compara con git diff antes de commitear.
2. Taggea nueva versión (v0.2.0, etc.).

11. Estructura del repositorio

siigo-pyme-excel/
├── SKILL.md
├── README.md
├── LICENSE
├── references/        # docs cargables bajo demanda
├── scripts/           # wrappers ejecutables
├── assets/templates/  # plantillas .xlsx generadas dinámicamente
└── docs/              # SDD y notas de diseño

12. Referencias internas

• references/excel-siigo-help.md — copia completa del manual oficial.
• references/functions-catalog.md — las 46 funciones documentadas.
• references/errors.md — códigos de error y recuperación.
• references/encoding.md — Windows-1252, comillas, rutas largas.
• references/siigo-pyme-concepts.md — glosario de términos SIIGO.
• references/filepath-txt.md — cómo el CLI localiza la empresa (filepath.txt).
• docs/SDD-EXPLORE.md y docs/SDD-PROPOSE.md — diseño del skill.

13. Persistencia y reutilización de outputs

Importante: una vez generado un .xlsx por el CLI, el archivo es completamente independiente de SIIGO. NO hace falta volver a ejecutar el .exe para trabajar con los datos — se puede usar Excel, Python, pandas, Power Query, etc. directamente sobre el archivo.

Esta sección documenta cómo el agente (skill) y el usuario pueden cooperar para que los .xlsx generados sean reutilizables entre sesiones, sin tener que regenerarlos cada vez.

13.1 Carpeta persistente recomendada

El wrapper por defecto escribe el .xlsx en la ruta que el usuario pasa con --salida. Si esa ruta es temporal (C:\\temp\\... o similar), el archivo se puede perder al reiniciar el sistema o limpiar Temp.

Recomendación: usar una carpeta dedicada para outputs SIIGO, por ejemplo:

C:\SIIGO_Reportes\             # raíz
├── empresa_01\
│   ├── 2026\
│   │   ├── 01_enero\
│   │   ├── 02_febrero\       # ej. Movimiento_2026_ene_feb.xlsx
│   │   ├── ...
│   │   └── 12_diciembre\
│   ├── Terceros\             # ej. Terceros_empresa1.xlsx
│   ├── Saldos\
│   └── Inventarios\
└── empresa_02\
    └── ...

Convención recomendada: <empresa>/<año>/<mesocategoría>/. Esto:

• Permite versionar (un .xlsx por mes no se sobreescribe).
• Facilita referencias cruzadas entre reportes (un GETMOV de enero

tiene relación con un GETTER de enero).

• Hace fácil automatizar mesclas (merge entre meses para acumulado

anual, vlookup contra Terceros para enriquecer con NIT/dirección).

13.2 Comportamiento del agente con archivos generados

Después de generar un .xlsx, el agente debe:

1. Registrar el archivo en su memoria de trabajo de la sesión actual.

Si el agente tiene memory o session_search, guardar: - Ruta absoluta del .xlsx - Función SIIGO usada (GETMOV, GETTER, etc.) - Rango de fechas / filtros aplicados - Timestamp de generación - Tamaño y número de filas/columnas

1. NO regenerarlo en futuras sesiones a menos que el usuario lo pida.

Si el usuario pide "el listado de terceros que generaste ayer", el agente debe: - Buscar primero si el archivo ya existe en la carpeta persistente. - Si existe y la fecha es razonable, leerlo directamente con openpyxl y responder con datos del archivo. - Solo regenerar si el archivo no existe, está obsoleto, o el usuario lo pide explícitamente.

1. Sugerir la carpeta persistente la primera vez que el usuario

genera un archivo, si no la ha configurado. Ejemplo de respuesta:

``` Generé C:\temp\Terceros_2026.xlsx con 982 terceros.

⚠️ Esta carpeta es temporal. ¿Quieres que la mueva a una carpeta persistente como C:\SIIGOReportes\empresa01\Terceros\? Si me dices "sí", puedo: - Mover el archivo a la nueva ubicación - Recordar esa ruta para futuras sesiones - Hacer backups automáticos antes de regenerar ```

13.3 Procesamiento posterior (el caso de uso común)

Una vez generado un .xlsx, el caso de uso más frecuente es procesarlo sin tocar SIIGO. Esto puede ser:

• Filtrar: por cuenta, tercero, fecha, tipo doc, valor, etc.
• Agregar: totales por mes, por cuenta, por tercero.
• Mesclar: con otros .xlsx generados (ej. Terceros + GETMOV para

enriquecer con NIT/dirección/ciudad).

• Validar: contra PUC, contra saldos esperados, contra presupuesto.
• Convertir: a CSV/JSON/SQL para importar a otro sistema.

El agente DEBE ofrecerse主动 a hacer esto cuando el usuario genera un .xlsx. Frases disparadoras en la respuesta:

• "¿Quieres que filtre/limpie/agregue/mescle esto con...?"
• "¿A qué carpeta quieres moverlo para no perderlo?"
• "¿Quieres que te genere un reporte derivado (ej. balance por

tercero, total por cuenta, top 10 proveedores)?"

13.4 Convención de nombres sugerida

Para que el agente y el usuario se entiendan al referirse a archivos:

<funcion>_<empresa>_<periodo>_<fecha_generacion>.xlsx

Ejemplos:

• GETMOVempresa012026-01-012026-02-2920260803.xlsx
• GETTERempresa01full_20260803.xlsx
• GETSALempresa012026-Q1_20260803.xlsx
• GETBODempresa012026-12_20260803.xlsx

El wrapper NO fuerza esta convención (el usuario elige --salida), pero es útil para reportes automáticos y para que el agente pueda inferir qué archivos son "viejos" o "ya generados".

13.5 Tabla de outputs por sesión (memoria del agente)

Si el agente tiene acceso a memoria persistente o a una nota de sesión, recomendarle guardar una tabla como:

Esto evita regenerar archivos y permite al agente cruzar información entre reportes.