15 KiB
glm-docassist
Sistema conversacional que genera documentos laborales automaticamente a partir de una solicitud en lenguaje natural, extrayendo los datos del empleado desde BambooHR y aplicando el template correspondiente al pais.
Informacion General
| Campo | Detalle |
|---|---|
| Proyecto | GLM DocAssist — Asistente de Documentos RRHH |
| Area | RRHH |
| Estado | En Progreso |
| Developer Principal | Isaac Aracena |
| IT Manager | Luis Matos |
| Fecha de Inicio | 2026-07-01 |
| Fecha de Cierre Estimada | 2026-08-11 |
| Ciclo Shape Up | Ciclo 3 — Semana 1 de 6 |
| Pais Piloto | El Salvador |
| Board de Ejecucion | [Link a Kan.bn — completar al crear el board] |
| PRD | [Link al PRD en Gitea — completar] |
Objetivo
Problema que resuelve
El equipo de RRHH recibe solicitudes frecuentes de documentos laborales por parte de los empleados: cartas de constancia laboral, cartas de recomendacion, contratos de trabajo, cartas de apertura de cuenta bancaria, cartas de autorizacion para acceso a puntos de venta, ofertas de empleo, entre otros. Hoy cada documento se elabora de forma completamente manual: el coordinador busca el template, lo abre, completa los datos uno a uno y entrega el documento. Este proceso toma entre 20 y 60 minutos por documento, genera backlog en RRHH y deja al empleado sin respuesta a tiempo.
Solucion implementada
El coordinador de RRHH envia una solicitud por WhatsApp o Gmail en lenguaje natural. El sistema interpreta la solicitud, identifica el tipo de documento y el empleado, consulta los datos del empleado en BambooHR, aplica el template correspondiente al pais y genera el documento .docx listo para entregar. El coordinador recibe el archivo en el mismo canal donde hizo la solicitud en menos de 2 minutos.
Usuarios / Beneficiarios
- Opera el sistema: Coordinador de RRHH de El Salvador (piloto — 1 usuario).
- Se beneficia del output: Empleados de GLM en El Salvador que solicitan documentos laborales.
Arquitectura
Diagrama de flujo
[WhatsApp / Gmail]
|
v
[n8n: recepcion del mensaje entrante]
|
v
[IA — Claude / Gemini: interpretacion de solicitud]
[Extrae: tipo de documento + nombre del empleado]
|
v
[BambooHR API: consulta de datos del empleado]
[nombre, cargo, departamento, fecha ingreso, salario, jefe directo]
|
v
[Python: carga del template .docx del pais correspondiente]
[Sustitucion de variables {{campo}} con los datos del empleado]
|
v
[n8n: entrega del documento .docx generado al coordinador]
[via WhatsApp / Gmail — canal de origen de la solicitud]
Stack tecnologico
| Componente | Tecnologia | Proposito |
|---|---|---|
| Automatizacion | n8n | Orquestacion del flujo de solicitud y entrega |
| IA | Claude / Gemini | Interpretacion del mensaje, extraccion de intencion y datos |
| Generacion de documentos | Python (python-docx) | Llenado de templates y generacion del .docx final |
| Base de datos | Supabase / Postgres | Almacenamiento de templates por pais y log de documentos generados |
| Infraestructura | Google Cloud / Servidor Virtual | Hosting y ejecucion del sistema |
Integraciones externas
| Sistema | Tipo de integracion | Datos que fluyen |
|---|---|---|
| BambooHR | API REST | Datos del empleado: nombre, cargo, fecha de ingreso, salario, jefe directo, departamento |
| API / n8n | Canal de entrada para solicitudes del coordinador; canal de entrega del documento generado | |
| Gmail | OAuth / MCP | Canal alternativo de entrada y entrega del documento generado |
Configuracion y Setup
Prerequisitos
- Credenciales de BambooHR API configuradas (API Key + subdominio de la empresa)
- Webhook de n8n activo para recepcion de mensajes de WhatsApp
- Credenciales de Gmail OAuth configuradas en n8n
- Templates de documentos de El Salvador cargados en
/templates/SV/ - Variables de entorno configuradas en
.env(ver seccion siguiente) - Conexion a Supabase configurada con tabla
document_logy tablatemplates
Variables de entorno
| Variable | Descripcion | Donde se obtiene |
|---|---|---|
BAMBOOHR_API_KEY |
API Key de BambooHR | BambooHR → Perfil → API Keys |
BAMBOOHR_SUBDOMAIN |
Subdominio de la empresa en BambooHR | URL de BambooHR: {subdomain}.bamboohr.com |
N8N_WEBHOOK_URL |
URL del webhook de n8n para recepcion de solicitudes | n8n → Workflow → Webhook node |
SUPABASE_URL |
URL de conexion a Supabase | Supabase → Settings → API |
SUPABASE_KEY |
API Key de Supabase | Supabase → Settings → API |
CLAUDE_API_KEY |
API Key de Claude (Anthropic) | console.anthropic.com |
TEMPLATES_PATH |
Ruta local a la carpeta de templates | /templates (relativa al root del proyecto) |
NUNCA commitear credenciales al repo. Todas las keys van en el vault de credenciales GLM.
Instalacion / Deploy
# Clonar el repo
git clone https://gitea.glm.com/glm-it/glm-docassist
# Instalar dependencias
pip install -r requirements.txt
# Configurar variables de entorno
cp .env.example .env
# Editar .env con las credenciales reales
# Cargar templates de El Salvador en la carpeta correspondiente
# /templates/SV/Carta_Constancia_Laboral_SV.docx
# /templates/SV/Carta_Recomendacion_SV.docx
# (ver convencion de nombres en /docs/templates_guide.md)
# Correr en local
python main.py
Como funciona
Flujo paso a paso
-
Trigger: El coordinador de RRHH envia un mensaje por WhatsApp o Gmail con la solicitud en lenguaje natural. Ejemplo: "necesito una carta de constancia laboral para Juan Perez".
-
Recepcion en n8n: El webhook de n8n captura el mensaje entrante e inicia el flujo.
-
Interpretacion por IA: Claude o Gemini analiza el mensaje y extrae dos datos clave: el tipo de documento solicitado y el nombre del empleado. Si el mensaje es ambiguo, el sistema responde con opciones para que el coordinador confirme.
-
Consulta a BambooHR: El sistema llama a la API de BambooHR con el nombre del empleado, obtiene su ficha completa y mapea los campos necesarios para el template seleccionado.
-
Generacion del documento: Python carga el template
.docxcorrespondiente al tipo de documento y al pais (El Salvador en el piloto), sustituye las variables{{campo}}con los datos reales del empleado y genera el archivo final. -
Entrega al coordinador: n8n envia el archivo
.docxgenerado al coordinador de RRHH por el mismo canal donde hizo la solicitud (WhatsApp o Gmail). El coordinador lo revisa y lo entrega al empleado. -
Log: El sistema registra cada documento generado en Supabase con fecha, tipo de documento, empleado y coordinador que lo solicito.
Triggers
| Trigger | Frecuencia | Descripcion |
|---|---|---|
| Webhook POST WhatsApp | On demand | Solicitud entrante del coordinador via WhatsApp |
| Webhook POST Gmail | On demand | Solicitud entrante del coordinador via Gmail |
Convencion de templates
Los templates son archivos .docx con variables marcadas con doble llave. El sistema sustituye cada variable con el dato correspondiente del empleado en BambooHR.
Variables estandar disponibles
| Variable | Dato que inserta |
|---|---|
{{nombre_empleado}} |
Nombre completo del empleado |
{{cargo}} |
Titulo del puesto |
{{departamento}} |
Departamento o area |
{{fecha_ingreso}} |
Fecha de inicio de la relacion laboral |
{{salario}} |
Salario actual |
{{jefe_directo}} |
Nombre del supervisor inmediato |
{{nombre_empresa}} |
Nombre legal de la empresa en ese pais |
{{fecha_documento}} |
Fecha de generacion del documento (automatica) |
Nombre de archivos de templates
Convencion: [Tipo_Documento]_[CODIGO_PAIS].docx
Ejemplos:
Carta_Constancia_Laboral_SV.docxCarta_Recomendacion_SV.docxCarta_Apertura_Banco_SV.docxContrato_Trabajo_SV.docxCarta_Autorizacion_PDV_SV.docx
Los templates se almacenan en /templates/{CODIGO_PAIS}/.
Testing
Como probar el sistema
# Tests unitarios
python -m pytest tests/
# Test de integracion completo (requiere credenciales reales)
python tests/integration_test.py
# Test manual del flujo en n8n
# Abrir workflow en n8n → Click "Execute workflow"
# Usar el payload de prueba en /tests/payloads/test_constancia_laboral.json
Casos de prueba minimos
| Caso | Input | Output esperado |
|---|---|---|
| Solicitud clara, empleado existe | "carta de constancia laboral para Juan Perez" | Documento .docx generado y entregado sin errores |
| Solicitud ambigua | "necesito un documento para Maria Lopez" | Sistema responde con lista de tipos de documento disponibles |
| Empleado no encontrado en BambooHR | Nombre incorrecto o inexistente | Mensaje de error al coordinador: "No encontre empleado con ese nombre" |
| Campo faltante en BambooHR | Empleado sin salario registrado | Documento generado con campo vacio y alerta al coordinador |
| Tipo de documento no soportado | "necesito una carta de recomendacion personal" | Mensaje al coordinador indicando que ese tipo no esta disponible |
| Timeout de BambooHR | API no responde en 10s | Retry automatico x1; si falla, alerta al coordinador |
Errores conocidos y troubleshooting
| Error | Causa probable | Solucion |
|---|---|---|
401 Unauthorized en BambooHR |
API Key vencida o incorrecta | Renovar key en BambooHR → Perfil → API Keys y actualizar .env |
Empleado no encontrado |
Nombre enviado no coincide exactamente con BambooHR | Verificar ortografia y nombre legal en BambooHR; considerar busqueda por ID |
Template no encontrado |
Archivo de template no esta en la ruta esperada | Verificar que el archivo existe en /templates/SV/ con la convencion de nombre correcta |
Timeout en n8n |
BambooHR o Claude API lentos | Aumentar timeout en el node correspondiente → Settings → Timeout |
| Documento generado con campos vacios | Campo no disponible en BambooHR para ese empleado | Revisar ficha del empleado en BambooHR y completar los datos faltantes |
| Webhook no recibe mensajes | URL de webhook incorrecta o n8n caido | Verificar que n8n esta corriendo y que la URL del webhook en WhatsApp / Gmail esta actualizada |
Monitoreo
Como saber si el sistema esta funcionando
- n8n Executions: Revisar logs en n8n → Executions diariamente. Cada solicitud debe aparecer como ejecucion exitosa.
- Log en Supabase: La tabla
document_logdebe registrar cada documento generado constatus = success. - Output esperado: Por cada solicitud valida del coordinador, debe generarse un archivo
.docxy entregarse en menos de 2 minutos. - Alertas: El sistema envia un mensaje al coordinador si ocurre un error durante la generacion. Errores criticos deben escalarse a Luis Matos.
Estructura del repositorio
/glm-docassist
├── README.md <- Este archivo
├── .env.example <- Variables de entorno de ejemplo (sin valores reales)
├── requirements.txt <- Dependencias Python
├── main.py <- Punto de entrada principal
├── /src
│ ├── bamboohr_client.py <- Cliente para la API de BambooHR
│ ├── document_generator.py <- Motor de llenado de templates .docx
│ ├── intent_parser.py <- Modulo de interpretacion de solicitudes via IA
│ └── document_log.py <- Registro de documentos generados en Supabase
├── /templates
│ └── /SV <- Templates de El Salvador
│ ├── Carta_Constancia_Laboral_SV.docx
│ ├── Carta_Recomendacion_SV.docx
│ └── [otros templates SV]
├── /n8n
│ └── workflow.json <- Export del workflow de n8n
├── /tests
│ ├── test_bamboohr.py <- Tests del cliente BambooHR
│ ├── test_document_generator.py <- Tests del motor de templates
│ ├── test_intent_parser.py <- Tests del modulo de IA
│ └── /payloads
│ └── test_constancia_laboral.json <- Payload de prueba
├── /docs
│ ├── architecture.png <- Diagrama de arquitectura
│ └── templates_guide.md <- Guia de convencion y entrega de templates
├── CHANGELOG.md <- Historial de cambios
└── DECISIONS.md <- Log de decisiones tecnicas
CHANGELOG
[2026-07-01] v0.1 — Inicio del ciclo. Setup inicial del repositorio.
DECISIONS LOG
DEC-001 — Convencion de variables en templates con doble llave
- Fecha: 2026-07-01
- Contexto: Se necesitaba una convencion estandar para marcar campos variables en los templates .docx que RRHH entrega y que el sistema debe sustituir.
- Opciones consideradas: Llaves simples
{campo}vs doble llave{{campo}}vs marcadores especiales[CAMPO]. - Decision: Doble llave
{{campo}}. - Razon: Es el estandar de python-docx y la mayoria de motores de templates. Reduce la probabilidad de colisiones con texto normal del documento y es familiar para el equipo tecnico.
DEC-002 — Piloto en El Salvador antes de expansion a otros paises
- Fecha: 2026-07-01
- Contexto: El sistema debe eventualmente soportar los 14 paises de GLM, pero cada pais tiene templates y datos diferentes.
- Opciones consideradas: Desarrollar soporte multi-pais desde el inicio vs piloto en un pais y expansion incremental.
- Decision: Piloto en El Salvador, expansion en ciclos futuros.
- Razon: Reduce el riesgo del primer ciclo, permite validar el motor de templates y la integracion con BambooHR con un scope controlado antes de escalar.
Contactos del proyecto
| Rol | Nombre | Contacto |
|---|---|---|
| Product Owner | Maximo Gomez | [email/WhatsApp] |
| IT Manager | Luis Matos | [email/WhatsApp] |
| Developer Principal | Isaac Aracena | [email/WhatsApp] |
Definition of Done
Checklist antes de mover a Completado en Kan.bn:
- Los 3 tipos de documentos del piloto generados sin errores en ambiente real
- Tiempo de entrega del documento menor a 2 minutos desde la solicitud
- Codigo commiteado y pusheado a Gitea
- README completo y actualizado
- Variables de entorno documentadas en
.env.example - Tests basicos pasando
- Workflow de n8n exportado en
/n8n/workflow.json - CHANGELOG actualizado con la version
- Probado en ambiente real (no solo local)
- Coordinador de RRHH El Salvador valido el output
- Luis Matos valido el output tecnico
- Maximo aprobo el resultado final
Documento mantenido por el equipo GLM IT · Ultima actualizacion: 2026-07-01