cruces-seguridad-social/README.md

# Cruces de Seguridad Social

> Repositorio centralizado de workflows de n8n para automatizar los cruces mensuales de Seguridad Social entre nómina, entidades locales y BambooHR en los distintos países de GomezLee Marketing.

---

## INFORMACIÓN GENERAL

| Campo | Detalle |
|---|---|
| **Proyecto** | Cruces de Seguridad Social |
| **Área** | Administración |
| **Developer Principal** | Isaac Aracena |
| **IT Manager** | Luis Matos |
| **Países implementados** | Guatemala, Honduras, República Dominicana, Costa Rica y El Salvador |

---

## OBJETIVO

### Problema que resuelve

La validación mensual de Seguridad Social requiere comparar manualmente la información de nómina de GomezLee Marketing contra los archivos oficiales o soportes utilizados por las entidades de Seguridad Social de cada país.

Este proceso implica revisar, según el país:

- Que todos los empleados presentes en nómina aparezcan en Seguridad Social.
- Que no existan personas reportadas en Seguridad Social que no estén en nómina.
- Diferencias de cédula, DUI, identidad u otros documentos.
- Diferencias de nombres y apellidos.
- Diferencias entre montos reportados o descontados.
- Casos especiales presentes en estructuras auxiliares de la nómina.
- Empleados presentes en nómina que no se encuentran claramente en BambooHR.
- Estado laboral y fecha de ingreso de empleados que requieren revisión.

La revisión manual consume tiempo, depende de múltiples formatos y aumenta el riesgo de errores humanos.

### Solución implementada

Se desarrolló una colección centralizada de workflows independientes en **n8n**, uno por país, que recibe los documentos mensuales mediante formularios, interpreta los formatos reales utilizados por cada operación, normaliza los datos y genera automáticamente los cruces y reportes requeridos.

Los workflows automatizan, según el país:

- Cruce de identidad.
- Cruce de montos.
- Detección de empleados presentes únicamente en una fuente.
- Detección de identificadores distintos.
- Comparación robusta de nombres.
- Consulta de BambooHR.
- Generación de la hoja `Nómina sin BambooHR`.
- Generación y formato de reportes.
- Compartición automática de archivos.
- Envío de correos HTML con branding GLM.
- Auditoría de ejecuciones y hallazgos.
- Manejo controlado de errores.
- Retorno al formulario para realizar otro cruce.

### Usuarios / Beneficiarios

- Administración.
- Recursos Humanos.
- Responsables de nómina.
- Equipo IT.
- Personal encargado de validar obligaciones de Seguridad Social.

---

## ARQUITECTURA

### Diagrama de flujo general

```text
[n8n Form]
    ↓
[Selección de período]
    ↓
[Carga de Nómina + Seguridad Social]
    ↓
[Validación de archivos]
    ↓
[Lectura y normalización]
    ↓
[Consulta BambooHR]
    ↓
[Cruce de Identidad]
    ↓
[Cruce de Montos]
    ↓
[Detección de Hallazgos]
    ↓
[Generación de Reporte]
    ↓
[Google Sheets / Google Drive]
    ↓
[Compartición de permisos]
    ↓
[Correo HTML GLM]
    ↓
[Auditoría]
    ↓
[Resultado final / Realizar otro cruce]
```

### Stack tecnológico

| Componente | Tecnología | Propósito |
|---|---|---|
| Automatización | n8n | Orquestación completa de los procesos |
| Formularios | n8n Forms | Recepción mensual de documentos |
| RRHH | BambooHR API | Consulta de empleados |
| Reportes | Google Sheets API | Generación y formato de reportes |
| Archivos | Google Drive API | Almacenamiento y permisos |
| Notificaciones | Gmail OAuth | Envío de correos |
| Auditoría | Supabase / REST API | Registro de ejecuciones, archivos y hallazgos |

### Integraciones externas

| Sistema | Tipo de integración | Datos que fluyen |
|---|---|---|
| BambooHR | API REST | Nombre, estado, fecha de ingreso y datos laborales |
| Google Sheets | REST API / OAuth | Creación, escritura y formato de reportes |
| Google Drive | OAuth | Archivos, almacenamiento y permisos |
| Gmail | OAuth | Correos de resultados |
| Supabase | REST API | Auditoría de ejecuciones y hallazgos |
| n8n Forms | Form Trigger | Parámetros y documentos del usuario |

---

## PAÍSES IMPLEMENTADOS

### 🇬🇹 Guatemala

Archivo:

```text
Cruce de Seguridad Social - Guatemala.json
```

Automatiza el cruce mensual de Seguridad Social para Guatemala, incluyendo validaciones de identidad, diferencias entre fuentes, consulta complementaria de BambooHR y generación automatizada del reporte.

### 🇭🇳 Honduras

Archivo:

```text
Cruce de Seguridad Social - Honduras.json
```

El formulario recibe el mes a validar, una o varias planillas IHSS en PDF y la nómina mensual. El workflow procesa identidades extraídas de las planillas IHSS, hojas válidas de la nómina, la hoja `IHSS-RAP`, personal especial cuando existe, cruce de identidad, cruce de montos IHSS, BambooHR, Nómina sin BambooHR, reporte final, permisos, correo y auditoría.

### 🇩🇴 República Dominicana

Archivo:

```text
Cruce de Seguridad Social - República Dominicana.json
```

Procesa la nómina mensual contra los archivos oficiales de TSS y fue adaptado para trabajar directamente con el formato real utilizado por los archivos recibidos mensualmente, evitando depender de una preparación manual previa.

Incluye solo en Nómina, solo en TSS, cruces de identidad y montos, información BambooHR, Nómina sin BambooHR, reporte en Google Sheets, correo y permisos automáticos.

### 🇨🇷 Costa Rica

Archivo:

```text
Cruce de Seguridad Social - Costa Rica.json
```

Procesa la nómina mensual y la planilla oficial CCSS. Incluye cruce de presencia Nómina ↔ CCSS, validación de cédulas, comparación robusta de nombres, cruce de montos por empleado, conciliación de totales, validación del período, BambooHR, Nómina sin BambooHR y reporte con formato GLM.

El lector de PDF de CCSS incluye controles para evitar generar reportes cuando la extracción del documento queda desalineada.

### 🇸🇻 El Salvador

Archivo:

```text
Cruce de Seguridad Social - El Salvador.json
```

Procesa nómina y Planilla Única en Excel. El workflow contempla archivos históricos donde la hoja de nómina no siempre utiliza el mismo nombre, pudiendo resolver estructuras como `Nomina`, `FEBRERO`, `MARZO` o `Nómina` según el archivo recibido.

Incluye cruce de DUI, nombres, posible mismo empleado con DUI diferente, montos, BambooHR, generación del Excel final, Google Drive, permisos, correo HTML, manejo de errores y botón para realizar otro cruce.

---

## REGLAS DE NEGOCIO

1. La nómina y los documentos de Seguridad Social deben corresponder al mismo período.
2. Cuando existe un identificador oficial confiable en ambas fuentes, este tiene prioridad sobre el nombre.
3. Los nombres deben normalizarse antes de comparar: mayúsculas/minúsculas, acentos, espacios, nombres adicionales y variaciones razonables de escritura.
4. Una coincidencia aproximada no debe aceptarse automáticamente cuando existan varios candidatos con similitud equivalente.
5. El cruce debe hacerse en ambos sentidos: `Nómina → Seguridad Social` y `Seguridad Social → Nómina`.
6. Las personas presentes únicamente en una fuente deben quedar identificadas como hallazgo.
7. Los empleados que requieran validación pueden complementarse con estado en BambooHR, fecha de ingreso y nombre registrado en BambooHR.
8. `Nómina sin BambooHR` debe contener exclusivamente empleados sin una coincidencia suficientemente confiable.
9. Los workflows deben tolerar variaciones ortográficas razonables sin producir falsos negativos.
10. Los reportes deben priorizar diferencias y hallazgos en lugar de llenar las hojas con registros que ya coinciden.
11. Las diferencias de montos deben considerar el redondeo correspondiente antes de marcar un caso como error.
12. Si la lectura del documento no es suficientemente confiable, el workflow debe detenerse antes de generar un reporte potencialmente incorrecto.
13. Un mismo documento cargado más de una vez no debe duplicar empleados ni montos.
14. Los reportes solo deben compartirse con los usuarios autorizados configurados para cada país.
15. Las credenciales nunca deben almacenarse directamente en el repositorio.

---

## CONFIGURACIÓN Y SETUP

### Prerrequisitos

Se requiere acceso a:

- n8n de GomezLee Marketing.
- BambooHR.
- Google Workspace.
- Google Drive.
- Google Sheets.
- Gmail.
- Supabase cuando el workflow utilice auditoría.
- Credenciales correspondientes configuradas en n8n.

### Credenciales

Las credenciales se administran desde el **Credential Manager de n8n**.

Integraciones habituales:

```text
BambooHR GLM Full Access
Google Drive OAuth
Google Sheets OAuth
Gmail OAuth
Supabase / REST API
```

Los nombres concretos pueden variar según el workflow.

> **NUNCA commitear API Keys, passwords, tokens OAuth, secretos, service-account keys ni archivos de credenciales al repositorio.**

### Variables de entorno

Actualmente la mayor parte de las integraciones utiliza credenciales almacenadas directamente en n8n. Cuando un endpoint o secreto sea externalizado deberá documentarse mediante `.env.example`.

Ejemplo:

```env
N8N_BASE_URL=
SUPABASE_URL=
SUPABASE_ANON_KEY=
```

Los valores reales nunca deben almacenarse en Git.

### Esquema de base de datos

No existe un schema SQL único para todo el repositorio. Los workflows que utilizan Supabase consumen las estructuras de auditoría configuradas en la infraestructura de GLM.

---

## INSTALACIÓN / DEPLOY

Clonar el repositorio:

```bash
git clone <URL_GITEA>/Isaac_Aracena/cruces-seguridad-social.git
cd cruces-seguridad-social
```

Importar el workflow requerido desde n8n:

```text
n8n
→ Workflows
→ Import from File
→ Seleccionar el JSON del país
```

Ejemplo:

```text
Cruce de Seguridad Social - Honduras.json
```

Después de importar:

1. Revisar las credenciales.
2. Confirmar IDs de Google Drive / Google Sheets utilizados.
3. Revisar destinatarios.
4. Confirmar URLs de producción del formulario.
5. Publicar el workflow.
6. Ejecutar una prueba con archivos reales.

---

## CÓMO FUNCIONA

### Flujo paso a paso

1. **Trigger:** un usuario envía el formulario n8n del país correspondiente.
2. **Inicialización:** se genera un identificador de ejecución, se guarda el período y se inicializa la memoria temporal.
3. **Lectura de documentos:** los archivos son clasificados y procesados con la lógica específica del país.
4. **Normalización:** se normalizan identidades, DUI, cédulas, nombres, montos, fechas y estados.
5. **BambooHR:** los workflows que necesitan información laboral consultan BambooHR; cuando se requieren empleados históricos se utiliza `onlyCurrent=false`.
6. **Cruce de identidad:** se identifican coincidencias, solo nómina, solo Seguridad Social y diferencias de identidad.
7. **Cruce de montos:** los valores son conciliados según las reglas específicas del país.
8. **Reporte:** se genera el reporte final con formato GLM.
9. **Permisos:** el archivo se comparte con los usuarios autorizados.
10. **Correo:** se envía un correo HTML con branding GomezLee Marketing.
11. **Auditoría:** los workflows que utilizan Supabase registran la ejecución, archivos y hallazgos.
12. **Output:** la pantalla final permite regresar al formulario mediante el botón `Realizar otro cruce`.

### Schedules / Triggers

| Trigger | Frecuencia | Descripción |
|---|---|---|
| n8n Form Trigger | Bajo demanda | Administración ejecuta el cruce mensual correspondiente |

Los workflows no dependen de un Cron para su ejecución normal.

---

## TESTING

### Casos de prueba mínimos

| Caso | Input | Output esperado | Estado |
|---|---|---|---|
| Caso feliz | Documentos correctos del mismo período | Reporte generado | ✅ |
| Sin diferencias | Fuentes conciliadas | Sin hallazgos materiales | ✅ |
| Solo Nómina | Empleado faltante en Seguridad Social | Hallazgo visible | ✅ |
| Solo Seguridad Social | Persona inexistente en Nómina | Hallazgo visible | ✅ |
| Documento diferente | Misma persona con identificador distinto | Caso para revisión | ✅ |
| Diferencia ortográfica menor | Nombre equivalente | No generar falso faltante | ✅ |
| Nombre adicional | Misma identidad | Coincidencia válida | ✅ |
| Monto diferente | Valores distintos | Diferencia visible | ✅ |
| Diferencia de redondeo | Diferencia mínima | Aplicar tolerancia | ✅ |
| No encontrado en BambooHR | Empleado sin match | Nómina sin BambooHR | ✅ |
| Empleado inactivo | Registro histórico BambooHR | Mostrar Inactivo | ✅ |
| Archivo incorrecto | Formato o período inválido | Error controlado | ✅ |
| Documento duplicado | Archivo repetido | No duplicar resultados | ✅ |
| API externa no disponible | Timeout/error | Error controlado / retry | ✅ |

---

## ERRORES CONOCIDOS Y TROUBLESHOOTING

| Error | Causa probable | Solución |
|---|---|---|
| `Spreadsheet does not contain sheet called "Nomina"` | Archivo histórico utiliza otro nombre de hoja | Usar la detección dinámica de hojas implementada |
| `binary file 'data' ... none was found` | Una rama de fallback perdió el binario original | Recuperar el archivo original antes del siguiente intento |
| Empleado no encontrado en BambooHR | Variación de nombre | Revisar matching y consulta `onlyCurrent=false` |
| Muchos casos Solo Nómina / Solo SS | Lectura desalineada | Revisar el extractor antes de cambiar el cruce |
| Diferencia de pocos centavos | Redondeo | Revisar tolerancia y cálculo por empleado |
| PDF sin empleados | Documento escaneado o texto no extraíble | Revisar calidad y formato del PDF |
| Botón `Realizar otro cruce` falla | URL relativa o webhook incorrecto | Usar Production URL completa |
| Gmail no envía | Credencial OAuth | Revisar credencial y nodo de envío |
| Error de permisos Drive | Usuario o credencial sin acceso | Revisar credencial y propiedad del archivo |
| Timeout BambooHR | API lenta | Retry + timeout extendido |

---

## MONITOREO

### n8n Executions

Revisar:

```text
n8n → Workflow → Executions
```

Referencia:

```text
Verde = ejecución exitosa
Rojo = ejecución fallida
```

Cuando exista un error debe identificarse primero el nodo exacto que falla antes de modificar la lógica global.

### Auditoría Supabase

Cuando está habilitada puede registrar:

- Ejecución.
- País.
- Período.
- Archivos procesados.
- Hallazgos.
- Estado final.
- Métricas de resultado.

### Output esperado

Una ejecución normal debe finalizar con:

- Cruces completados.
- Reporte generado.
- Archivo compartido.
- Correo enviado.
- Auditoría registrada cuando aplica.
- Página final disponible para realizar otro cruce.

---

## ESTRUCTURA DEL REPOSITORIO

```text
/cruces-seguridad-social
│
├── README.md
│
├── Cruce de Seguridad Social - Costa Rica.json
├── Cruce de Seguridad Social - El Salvador.json
├── Cruce de Seguridad Social - Guatemala.json
├── Cruce de Seguridad Social - Honduras.json
└── Cruce de Seguridad Social - República Dominicana.json
```

Cada JSON debe representar la **última versión estable del workflow del país correspondiente**.

---

## CONVENCIÓN DE ACTUALIZACIÓN

Después de realizar cambios en producción:

```bash
git add "Cruce de Seguridad Social - Honduras.json"
git commit -m "Actualizar Cruce de Seguridad Social - Honduras"
git push origin main
```

Proceso recomendado:

1. Validar el workflow en n8n.
2. Ejecutar una prueba real.
3. Exportar el JSON.
4. Reemplazar únicamente el archivo del país correspondiente.
5. Verificar que el JSON no incluya secretos.
6. Hacer commit.
7. Hacer push a Gitea.

---

> Documento mantenido por el equipo **GLM IT**.