Isaac_Aracena/ir-nicaragua
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
4 Commits 1 Branch 0 Tags
3182a3d4dd0881ec17d9cf991be86fb6f2f2de2f
T
Clone
Open with VS Code Open with VSCodium Open with Intellij IDEA
Download ZIP Download TAR.GZ Download BUNDLE
Isaac_Aracena 3182a3d4dd Actualizar README.md
2026-07-16 00:41:01 +00:00
Cálculo de IR - Nicaragua.json
Actualizar Cálculo de IR - Nicaragua.json
2026-07-15 22:19:09 +00:00
README.md
Actualizar README.md
2026-07-16 00:41:01 +00:00

README.md

Cálculo de IR — Nicaragua

Automatización mensual que procesa las nóminas de primera y segunda quincena, recalcula el Impuesto sobre la Renta de cada empleado, identifica diferencias y genera una memoria de cálculo completa para Administración.

Información general

Campo Detalle
Proyecto Cálculo de IR — Nicaragua
Área Administración / Nómina
Estado Listo para producción
Developer principal Isaac Aracena
Product Owner Máximo Gomez
IT Manager Luis Matos
Fecha de inicio 2026-07-10
Fecha de cierre técnico 2026-07-15
Tipo de iniciativa Automatización operativa mensual
Board de ejecución Kan.bn — IR Nicaragua
Repositorio Gitea — ir-nicaragua
Workflow principal Cálculo de IR - Nicaragua.json
Workflow auxiliar Limpieza de archivos temporales de IR Nicaragua

Objetivo

Problema que resuelve

Administración de Nicaragua utilizaba una memoria de cálculo de Excel para validar el IR mensual, pero debía copiar manualmente la información de cada empleado desde las nóminas de primera y segunda quincena. Aunque el Excel contenía las fórmulas fiscales, la digitación empleado por empleado consumía demasiado tiempo, aumentaba el riesgo de errores y dificultaba revisar oportunamente las diferencias del sistema de nómina.

Solución implementada

El sistema presenta un formulario en n8n donde Administración selecciona el mes y el año, adjunta las dos nóminas en formato .xlsx y ejecuta la validación. El workflow lee automáticamente todas las pestañas operativas, cruza a los empleados, recalcula el IR, genera una memoria completa en Google Sheets y Excel, crea una pestaña exclusiva de diferencias y envía un resumen por correo.

Usuarios y beneficiarios

  • Administración de GomezLee Marketing Nicaragua.
  • Personal responsable de validar nómina e IR.
  • Dirección administrativa.

Arquitectura

Diagrama general

Formulario n8n
    |
    |-- Mes
    |-- Año
    |-- Nómina Q1 (.xlsx)
    `-- Nómina Q2 (.xlsx)
            |
            v
Conversión temporal de XLSX a Google Sheets
            |
            v
Lectura de todas las pestañas operativas
            |
            v
Normalización y cruce de empleados
            |
            v
Recalculo independiente del IR
            |
            v
Creación de memoria de cálculo
    |-- MEMORIA DE CALCULO
    `-- DIFERENCIAS
            |
            +--> Compartir Google Sheet
            +--> Exportar copia XLSX
            +--> Enviar correo HTML
            `--> Eliminar archivos temporales

Stack tecnológico

Componente Tecnología Propósito
Automatización n8n self-hosted Orquestación del proceso
Interfaz de entrada n8n Form Trigger Recepción de período y archivos
Procesamiento JavaScript nativo en Code nodes Lectura lógica, normalización, cruce y cálculo
Conversión de archivos Google Drive API Conversión temporal de XLSX a Google Sheets
Lectura y escritura Google Sheets API Lectura multih hoja, fórmulas, formato y reporte
Notificaciones Gmail OAuth2 Envío del correo HTML y del Excel adjunto
Almacenamiento temporal Google Drive Archivos temporales durante la ejecución

Integraciones externas

Sistema Tipo de integración Datos que fluyen
Google Drive OAuth2 / REST API Carga, conversión, exportación, permisos y eliminación
Google Sheets OAuth2 / REST API Lectura de pestañas, escritura, fórmulas y formato
Gmail OAuth2 Correo HTML y archivo Excel adjunto
n8n Form Trigger web Mes, año y nóminas Q1/Q2

Reglas de negocio

Archivos de entrada

  1. El formulario exige dos archivos: nómina de primera quincena y nómina de segunda quincena.
  2. Ambos archivos deben estar en formato .xlsx.
  3. Los dos libros deben corresponder al mismo mes y año seleccionados.
  4. La validación del período se realiza con el contenido de cada pestaña, no únicamente con el nombre del archivo.
  5. El archivo Q1 admite hojas con período del día 1 al 15.
  6. El archivo Q2 admite hojas del día 16 al 28, 29, 30 o 31 y hojas mensuales del día 1 al 28, 29, 30 o 31.
  7. Se excluyen automáticamente resúmenes, hojas auxiliares, copias de otros períodos, filas de totales y notas administrativas.

Fuente monetaria para el cálculo

La fuente principal es la columna Salario INSS, porque representa el ingreso bruto sujeto a INSS antes de descontar el 7 %.

Cuando Salario INSS está vacío, se aplican los siguientes respaldos:

  1. Salario IR / 0.93.
  2. INSS Laboral / 0.07.
  3. El registro se marca como dato derivado o incompleto.

No se utiliza Total Ingresos como fuente principal, porque puede incluir subsidios u otros conceptos no sujetos a INSS o IR.

Cruce de empleados

El orden de coincidencia es:

  1. Cédula normalizada.
  2. Número de INSS válido.
  3. Nombre normalizado.

El empleado no necesita permanecer en la misma hoja, proyecto o cliente entre las dos quincenas.

Cálculo para personal quincenal

Ingreso sujeto mensual = Salario INSS Q1 + Salario INSS Q2
INSS laboral = Ingreso sujeto mensual × 7 %
Base imponible = Ingreso sujeto mensual − INSS laboral
Proyección anual = Base imponible × 12

A la proyección anual se le aplica la tabla progresiva del IR de Nicaragua.

Cálculo para personal mensual

Para empleados incluidos en una hoja mensual dentro del archivo Q2:

Ingreso sujeto mensual = Salario INSS mensual de Q2

No se busca una pareja en Q1 porque el valor de Q2 ya representa el mes completo.

Tabla fiscal aplicada

Renta anual Porcentaje Impuesto base Exceso sobre
Hasta C$100,000.00 0 % C$0.00 C$0.00
C$100,000.01 a C$200,000.00 15 % C$0.00 C$100,000.00
C$200,000.01 a C$350,000.00 20 % C$15,000.00 C$200,000.00
C$350,000.01 a C$500,000.00 25 % C$45,000.00 C$350,000.00
Más de C$500,000.00 30 % C$82,500.00 C$500,000.00

Comparación

Diferencia = IR registrado en nómina Q2 − IR esperado
  • Resultado negativo: la nómina retuvo menos IR del esperado.
  • Resultado positivo: la nómina retuvo más IR del esperado.
  • Diferencia absoluta menor o igual a C$1.00: tolerancia de redondeo.
  • Diferencia absoluta mayor a C$1.00: diferencia material.

Estados del reporte

Estado Significado
VALIDADO El IR se encuentra dentro de la tolerancia
DIFERENCIA IR Existe una diferencia material mayor a C$1.00
SOLO EN 1RA QUINCENA El empleado no aparece en Q2
SOLO EN 2DA QUINCENA El empleado no aparece en Q1
DATO DERIVADO Se utilizó un respaldo o el cruce fue por nombre
DATO INCOMPLETO No fue posible obtener toda la información requerida

Los empleados presentes en una sola quincena se muestran como No comparables; el flujo no presenta un cálculo parcial como si fuera una validación mensual completa.

Colores del reporte

  • Rojo: diferencia material de IR.
  • Amarillo: empleado presente en una sola quincena.
  • Naranja: dato incompleto.
  • Azul: dato derivado o emparejamiento por nombre.
  • Sin alerta: empleado validado.

Reportes generados

Pestaña MEMORIA DE CALCULO

Contiene a todos los empleados identificados y conserva la estructura de la memoria original:

  • NSS, cédula, nombres, cargo, empresa y departamento.
  • Salario contractual, primera quincena y segunda quincena.
  • Total, INSS, base imponible y proyección anual.
  • Exceso, diferencia, porcentaje e impuesto base.
  • IR anual, IR mensual e IR quincenal.

La tabla fiscal y las columnas técnicas se mantienen ocultas para facilitar la lectura.

Pestaña DIFERENCIAS

Muestra únicamente registros que requieren atención:

  • Diferencias materiales.
  • Empleados presentes en una sola quincena.
  • Datos derivados.
  • Datos incompletos.

Incluye IR esperado, IR de nómina, diferencia, estado, interpretación, observación, hojas de origen y método de cruce.

Correo HTML

El correo incluye:

  • Branding y logo de GomezLee Marketing.
  • Período procesado.
  • Empleados Q1, Q2 y emparejados.
  • Diferencias materiales.
  • Empleados presentes en una sola quincena.
  • Datos por revisar.
  • Tabla con las principales diferencias.
  • Botón para abrir el Google Sheet.
  • Copia del reporte en formato Excel.

Destinatarios y permisos

El correo y el acceso de edición al Google Sheet se asignan a:

Nombre Correo
Isaac Aracena iaracena@gomezleemarketing.com
Estefani Orozco administrativo@gomezleemarketing.com
Angie Carolina Chavez Silva administrativonicaragua@gomezleemarketing.com
Mati Soto Valenzuela msoto@gomezleemarketing.com
Iveth Herrera iherrera@gomezleemarketing.com
Máximo Gomez mgomez@gomezleemarketing.com

No existe modo de prueba en la versión de producción. Cada ejecución envía el correo y comparte el documento con las seis personas configuradas.

Configuración y setup

Prerrequisitos

  • Acceso al servidor corporativo de n8n.
  • Google Drive API habilitada.
  • Google Sheets API habilitada.
  • Credencial OAuth2 de Google Drive en n8n.
  • Credencial OAuth2 de Google Sheets en n8n.
  • Credencial OAuth2 de Gmail en n8n.
  • Permisos de Google Workspace para crear, compartir y eliminar archivos.

Credenciales requeridas

Credencial Uso
Google Drive OAuth2 Conversión, exportación, permisos y eliminación
Google Sheets OAuth2 Lectura, escritura, fórmulas y formato
Gmail OAuth2 Envío del correo y adjunto

Nunca incluir tokens, secretos OAuth ni contraseñas en el repositorio.

Variables de entorno

El proyecto no requiere variables de entorno adicionales ni cambios al servidor.

No necesita ExcelJS, require(), NODE_FUNCTION_ALLOW_EXTERNAL, Dockerfile personalizado ni paquetes npm externos.

Instalación

git clone https://git.digitalcompass.agency/Isaac_Aracena/ir-nicaragua.git
cd ir-nicaragua
  1. Abrir n8n.
  2. Ir a Workflows.
  3. Seleccionar Import from File.
  4. Importar Cálculo de IR - Nicaragua.json.
  5. Confirmar las credenciales de Google Drive, Google Sheets y Gmail.
  6. Guardar y publicar el workflow.
  7. Copiar la Production URL del Form Trigger.
  8. Registrar la URL en Kan.bn y compartirla únicamente con usuarios autorizados.

Workflow de limpieza

El workflow auxiliar revisa diariamente Google Drive y elimina archivos temporales cuyo nombre comienza con:

TMP_IR_NIC_

Solo elimina temporales con más de 24 horas para cubrir ejecuciones interrumpidas.

Cómo funciona

  1. Administración abre el formulario.
  2. Selecciona mes y año.
  3. Adjunta Q1 y Q2.
  4. n8n valida los archivos.
  5. Google Drive los convierte temporalmente a Google Sheets.
  6. Google Sheets API enumera las pestañas.
  7. Se identifican las hojas operativas válidas.
  8. Se normalizan encabezados e identificadores.
  9. Se extrae Salario INSS y el IR de Q2.
  10. Se cruzan los empleados.
  11. Se recalcula el IR.
  12. Se crea la memoria completa.
  13. Se genera la pestaña DIFERENCIAS.
  14. Se comparte el Google Sheet.
  15. Se exporta el Excel.
  16. Gmail envía el correo.
  17. Se eliminan los temporales.
  18. El formulario muestra la confirmación.

Triggers

Trigger Frecuencia Descripción
n8n Form Trigger Bajo demanda Administración carga las nóminas
Schedule Trigger de limpieza Diario, 2:00 a. m. Elimina temporales con más de 24 horas

Testing

Regresión histórica

Período Empleados Q1 Empleados Q2 Emparejados Diferencias > C$1 Solo en una quincena
Marzo 2026 208 230 194 12 32
Abril 2026 223 237 207 20 28
Mayo 2026 225 245 220 14 13

Casos de prueba

Caso Resultado esperado Estado
Q1 y Q2 válidos Reporte, correo y permisos correctos Validado
Meses diferentes Ejecución detenida Validado
Archivo no XLSX Rechazo antes de procesar Validado
Hoja auxiliar Excluida Validado
Empleado mensual Cálculo con Q2 mensual Validado
Solo Q1 o solo Q2 No comparable Validado
Sin Salario INSS Valor derivado y marcado Validado
Diferencia ≤ C$1 Redondeo Validado
Diferencia > C$1 Alerta roja Validado
Error temporal de Google Reintentos automáticos Configurado
Fallo antes de limpiar Limpieza diaria Configurado

Errores conocidos y troubleshooting

Error Causa probable Solución
Form Trigger con ? Versión incompatible Usar typeVersion: 2.3
Error de this.helpers Helper no soportado Usar el workflow actual sin helpers
Google no convierte el XLSX Sesión vencida o archivo incompatible Iniciar una ejecución nueva
Error al aplicar formato Columnas congeladas cortan celdas combinadas Congelar solo filas
No encuentra hojas válidas Mes/año incorrecto Revisar archivos y selección
Coincidencia muy baja Q1 y Q2 no corresponden Cargar el mismo período
Correo no enviado OAuth Gmail vencido Reconectar la credencial
Permiso no creado Restricción de Workspace Revisar Google Admin
Timeout Libro grande o servicio lento Revisar retries y timeout
Temporales en Drive Fallo antes de limpiar Verificar workflow diario

Monitoreo

  • Revisar n8n → Executions después de cada procesamiento.
  • Verde significa completado; rojo significa fallo.
  • Confirmar recepción del correo por los seis destinatarios.
  • Confirmar las pestañas MEMORIA DE CALCULO y DIFERENCIAS.
  • Confirmar el Excel adjunto.
  • Confirmar la eliminación de temporales.
  • Revisar el workflow de limpieza diariamente.

Output esperado

  1. Google Sheet con memoria completa.
  2. Pestaña de diferencias.
  3. Permisos de edición para seis destinatarios.
  4. Correo HTML.
  5. Excel adjunto.
  6. Confirmación final en el formulario.
  7. Eliminación de archivos temporales.

Seguridad

  • El formulario procesa datos sensibles de nómina.
  • La URL debe compartirse únicamente con personal autorizado.
  • No almacenar credenciales en el JSON.
  • No publicar los reportes mediante acceso público por enlace.
  • Eliminar temporales al finalizar.
  • No subir nóminas reales ni reportes con datos personales al repositorio.

Estructura del repositorio

/ir-nicaragua
├── README.md
├── Cálculo de IR - Nicaragua.json
├── n8n/
│   ├── workflow-principal.json
│   └── workflow-limpieza-temporales.json
├── docs/
│   ├── arquitectura.md
│   ├── reglas-negocio.md
│   └── pruebas-historicas.md
├── CHANGELOG.md
└── DECISIONS.md

Changelog

2026-07-15 — v1.0.0

  • Workflow listo para producción.
  • Formulario con Q1 y Q2.
  • Lectura dinámica de pestañas.
  • Cruce de empleados.
  • Cálculo progresivo de IR.
  • Memoria completa y pestaña de diferencias.
  • Branding GLM.
  • Correo HTML y Excel adjunto.
  • Permisos para seis destinatarios.
  • Limpieza de temporales.
  • Pruebas de marzo, abril y mayo.
  • Modo de prueba eliminado.

2026-07-13 — v0.9.0

  • Ajustes de formato.
  • Corrección de alineaciones y cuadrícula.
  • Mejora de observaciones.
  • Ajuste automático de filas.
  • Corrección de celdas combinadas.

2026-07-10 — v0.1.0

  • Inicio del proyecto.
  • Análisis de la memoria.
  • Análisis de nóminas.
  • Definición de reglas.

Decisions log

DEC-001 — Exigir ambas quincenas

  • Decisión: Q1 y Q2 son obligatorias.
  • Razón: el IR depende de la suma real de ambas quincenas.

DEC-002 — Usar Salario INSS

  • Decisión: Salario INSS es la fuente principal.
  • Razón: la memoria descuenta por sí misma el 7 %.

DEC-003 — No instalar módulos externos

  • Decisión: usar APIs de Google.
  • Razón: no se puede modificar el servidor de n8n.

DEC-004 — Tolerancia de C$1.00

  • Decisión: reportar como material una diferencia absoluta mayor a C$1.
  • Razón: excluir redondeos normales.

DEC-005 — Dos pestañas

  • Decisión: MEMORIA DE CALCULO y DIFERENCIAS.
  • Razón: mantener trazabilidad y simplificar la revisión.

DEC-006 — Una sola quincena no es comparable

  • Decisión: dejar IR esperado y diferencia en blanco.
  • Razón: evitar cálculos mensuales parciales.

DEC-007 — Seis responsables

  • Decisión: correo y edición para Isaac, Estefani, Angie, Mati, Iveth y Máximo.
  • Razón: responsables oficiales de operación y seguimiento.

DEC-008 — Limpieza automática

  • Decisión: workflow diario de temporales.
  • Razón: seguridad y mantenimiento de Drive.

Contactos del proyecto

Rol Nombre Contacto
Product Owner / Sponsor Máximo Gomez mgomez@gomezleemarketing.com
IT Manager Luis Matos Contacto corporativo GLM
Developer principal Isaac Aracena iaracena@gomezleemarketing.com
Administración Nicaragua Estefani Orozco administrativo@gomezleemarketing.com
Administración Nicaragua Angie Carolina Chavez Silva administrativonicaragua@gomezleemarketing.com
Revisión Mati Soto Valenzuela msoto@gomezleemarketing.com
Revisión Iveth Herrera iherrera@gomezleemarketing.com

Checklist mensual

Antes:

  • Confirmar mismo mes en Q1 y Q2.
  • Confirmar formato .xlsx.
  • Seleccionar mes y año correctos.

Después:

  • Confirmar ejecución verde.
  • Abrir el Google Sheet.
  • Revisar filas rojas.
  • Revisar filas amarillas.
  • Revisar datos derivados.
  • Confirmar recepción del correo.
  • Confirmar Excel adjunto.
  • Confirmar permisos.
  • Confirmar eliminación de temporales.

Definition of Done

  • Memoria original analizada.
  • Nóminas históricas analizadas.
  • Reglas fiscales reproducidas.
  • Formulario funcionando.
  • Q1 y Q2 obligatorias.
  • Lectura multih hoja.
  • Cruce validado.
  • Google Sheet y Excel.
  • Pestaña de diferencias.
  • Correo HTML.
  • Permisos configurados.
  • Limpieza de temporales.
  • Pruebas históricas.
  • Workflow versionado.
  • README completo.
  • Modo de prueba eliminado.

Mantenimiento

Todo cambio en la tasa del INSS, tabla fiscal, estructura de nóminas, encabezados, destinatarios, tolerancia o permisos debe:

  1. Documentarse.
  2. Probarse con un período histórico.
  3. Exportarse nuevamente desde n8n.
  4. Actualizarse en Gitea.
  5. Registrarse en el changelog.

Documento mantenido por el equipo GLM IT.

Reference in New Issue View Git Blame Copy Permalink
S
Description
Automatización del cálculo y validación de IR para Nicaragua
Readme 308 KiB