ir-nicaragua/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](https://pmit.digitalcompass.agency/cards/z7ms5z0ciw1k) |
| **Repositorio** | [Gitea — ir-nicaragua](https://git.digitalcompass.agency/Isaac_Aracena/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

```text
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

```text
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:

```text
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

```text
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

```bash
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:

```text
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

```text
/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` |

---

## Definition of Done

- [x] Memoria original analizada.
- [x] Nóminas históricas analizadas.
- [x] Reglas fiscales reproducidas.
- [x] Formulario funcionando.
- [x] Q1 y Q2 obligatorias.
- [x] Lectura multih hoja.
- [x] Cruce validado.
- [x] Google Sheet y Excel.
- [x] Pestaña de diferencias.
- [x] Correo HTML.
- [x] Permisos configurados.
- [x] Limpieza de temporales.
- [x] Pruebas históricas.
- [x] Workflow versionado.
- [x] README completo.
- [x] 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.

---