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

[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:

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:

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:

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:

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:

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:

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:

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:

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

Importar el workflow requerido desde n8n:

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

Ejemplo:

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:

n8n → Workflow → Executions

Referencia:

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

/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:

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.