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 / Recursos Humanos / IT
Estado	En producción / mantenimiento evolutivo
Developer Principal	Isaac Aracena
IT Manager	Luis Matos
Organización	GomezLee Marketing
Tecnología principal	n8n
Repositorio	cruces-seguridad-social
Países implementados	Guatemala, Honduras, República Dominicana, Costa Rica y El Salvador
Fecha de inicio	2026
Fecha de cierre estimada	Proyecto evolutivo
Ciclo Shape Up	No documentado
Board de ejecución	No documentado
PRD del proyecto	No documentado

---

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
Infraestructura	Servidor GLM / DigitalCompass	Hosting de n8n y formularios

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.

---

CHANGELOG

2026-08 — Consolidación del repositorio

• Centralización de los workflows de Seguridad Social.
• Guatemala incorporado.
• Honduras incorporado.
• República Dominicana incorporado.
• Costa Rica incorporado.
• El Salvador incorporado.
• Integración BambooHR.
• Formularios mensuales.
• Reportes automatizados.
• Correos HTML GLM.
• Compartición automática.
• Auditoría Supabase en los workflows aplicables.

Costa Rica

• Lectura robusta de los PDF oficiales de CCSS.
• Validación de período.
• Cruce de identidad y montos.
• Conciliación de totales.
• Matching robusto BambooHR.
• Nómina sin BambooHR.
• Formato optimizado del reporte.

El Salvador

• Soporte para nóminas históricas con nombres de hoja variables.
• Preservación del binario entre intentos de lectura.
• Cruce DUI y montos.
• Matching BambooHR.
• Google Drive, permisos y correo final.
• Manejo de errores.
• Botón para realizar otro cruce.

Honduras

• Lectura de múltiples planillas IHSS PDF.
• Procesamiento dinámico de hojas de nómina.
• Lectura de IHSS-RAP.
• Manejo de personal especial.
• Cruce de identidad y montos IHSS.
• BambooHR.
• Nómina sin BambooHR.
• Auditoría.

República Dominicana

• Lectura del formato real de TSS.
• Cruce Nómina vs. TSS.
• Información BambooHR en diferencias.
• Nómina sin BambooHR.
• Formulario reutilizable mensualmente.

---

DECISIONS LOG

DEC-001 — Repositorio centralizado por dominio

• Fecha: 2026
• Contexto: los cruces de Seguridad Social utilizan una misma finalidad de negocio, pero existen múltiples implementaciones por país.
• Opciones consideradas: un repositorio por país vs. un repositorio centralizado.
• Decisión: mantener todos los workflows dentro del repositorio cruces-seguridad-social.
• Razón: facilita versionado, mantenimiento, documentación y expansión a nuevos países.

DEC-002 — Workflow independiente por país

• Fecha: 2026
• Contexto: cada institución utiliza documentos y estructuras distintas.
• Opciones consideradas: un único workflow universal vs. un workflow especializado por país.
• Decisión: mantener un JSON independiente por país.
• Razón: reduce el riesgo de que cambios realizados para una institución afecten las demás.

DEC-003 — Procesar documentos originales

• Fecha: 2026
• Contexto: algunos documentos anteriormente necesitaban preparación manual antes de ser procesados.
• Opciones consideradas: seguir modificando documentos manualmente vs. adaptar los workflows.
• Decisión: los workflows deben leer directamente los archivos en el formato real en que serán utilizados cada mes.
• Razón: Administración debe poder ejecutar el formulario sin depender de IT para modificar previamente los documentos.

DEC-004 — BambooHR como fuente complementaria

• Fecha: 2026
• Contexto: algunos hallazgos necesitan información adicional del empleado.
• Opciones consideradas: revisión manual en BambooHR vs. consulta automática.
• Decisión: utilizar BambooHR para complementar los cruces.
• Razón: permite conocer si un empleado existe, su estado, fecha de ingreso y nombre oficial.

DEC-005 — Matching conservador de identidad

• Fecha: 2026
• Contexto: los nombres pueden presentar errores ortográficos o variaciones entre fuentes.
• Opciones consideradas: matching estricto vs. matching aproximado sin control vs. matching aproximado conservador.
• Decisión: permitir variaciones razonables, pero no aceptar coincidencias ambiguas automáticamente.
• Razón: es preferible enviar un caso a revisión que asociar incorrectamente dos empleados distintos.

---

CONTACTOS DEL PROYECTO

Rol	Nombre	Contacto
IT Manager	Luis Matos	Interno GLM
Developer Principal	Isaac Aracena	iaracena@gomezleemarketing.com
Área usuaria	Administración / Recursos Humanos	Interno GLM

---

DEFINITION OF DONE

Un workflow de Seguridad Social se considera listo cuando:

• El formulario funciona.
• Los documentos originales pueden cargarse sin preparación manual.
• El cruce de identidad funciona.
• El cruce de montos funciona.
• Se analizan ambas direcciones del cruce.
• BambooHR está integrado cuando corresponde.
• Nómina sin BambooHR está disponible cuando aplica.
• El reporte tiene formato legible.
• Los usuarios autorizados reciben acceso.
• El correo de resultado funciona.
• Existe manejo de errores.
• Se puede regresar al formulario.
• El workflow fue probado con archivos reales.
• El JSON estable está almacenado en Gitea.
• El README está actualizado.

---

SEGURIDAD

Este repositorio no debe contener secretos.

Nunca incluir:

Passwords
API Keys
OAuth Client Secrets
Service Account Keys
Access Tokens
Refresh Tokens
Credenciales BambooHR
Credenciales Supabase

Todas las credenciales deben permanecer dentro del Credential Manager de n8n o de la infraestructura segura definida por GLM IT.

---

Documento mantenido por el equipo GLM IT.