Hablla Integration Worker
Un worker de integración Node.js que sincroniza datos operativos Hablla en Google Sheets para análisis, monitoreo de asistencia y enriquecimiento de la base de clientes estilo CRM.
Descripción general
Este worker es parte de una cadena de integración impulsada por eventos. Recibe tokens de Google OAuth del worker de autenticación, se autentica con API de Habllas y ejecuta tres pipelines sincronizadas:
- Sincronización de tarjetas (
Base Hablla Card) - Resumen del desempeño del asistente (
Base Atendente) - Exportación cliente/persona (
Base Cliente)
La implementación incluye deduplicación, API limitación, desinfección de datos y prácticas de registro seguro para operaciones de repositorios públicos.
Arquitectura del sistema
graph TB
A[Google Auth Worker] -->|repository_dispatch| B[Hablla Integration Worker]
B --> C[API de Hablla]
B --> D[Google Sheets API]
C --> E[Cards]
C --> F[Service Summary]
C --> G[Persons]
B --> H[Data Sanitization]
H --> D
Características principales
- Sincronización incremental de tarjetas con
updated_afterfiltrado - Ventana de limpieza de seguridad (últimos 7 días) antes de agregar datos nuevos
- Limpieza de duplicados mediante ID de tarjeta única en
Base Hablla Card - Ingestión de KPI del operador (TME, TMA, CSAT, FCR)
- Exportación de cliente/persona con mapeo de contacto/etiqueta/campo personalizado normalizado
- Prevención de inyección de fórmula de hoja de cálculo mediante la función de desinfección
- Modelo de ejecución segura con comportamiento de registro sensible a máscaras
- Limitación de velocidad entre llamadas de API para reducir el riesgo de limitación del proveedor
Pipelines de datos
1. Tarjeta básica Hablla
El worker:
- Se autentica en Hablla
- Lee filas recientes de
Base Hablla Card - Elimina filas recientes de ventanas móviles (limpieza de seguridad)
- Obtiene tarjetas paginadas de Hablla
- Asigna campos personalizados y metadatos de tarjetas
- Agrega filas a Google Sheets
- Reconstruye datos deduplicados por ID de tarjeta
2. Asistente de base
El worker solicita métricas de resumen de servicio diario de Hablla y agrega filas por agente que contienen:
- totales de servicio
- Métricas TME/TMA
- metadatos de conexión
- Indicadores CSAT
- Contadores FCR
3. Cliente base
El worker recupera personas/clientes por ventana de fecha y exporta:
- Indicador de teléfono principal y WhatsApp.
- lista de correo electrónico aplanada
- sectores y etiquetas
- ID de campos personalizados fijos asignados a columnas dedicadas
- campos adicionales dinámicos serializados en una columna de "otros campos"
Controles de seguridad
- Sanitización: Prefija cadenas de alto riesgo que comienzan con
=,+,-,@ - Registro seguro para el público: Evita exponer detalles confidenciales de la payload
- Autenticación solo de secretos: Las credenciales y los tokens se inyectan únicamente en el entorno.
- Modelo de flujo de trabajo con privilegios mínimos: Ejecuta solo los pasos requeridos en GitHub Actions
Configuración
Variables de entorno requeridas
GOOGLE_TOKEN=oauth_access_token_from_google_auth_worker
HABLLA_EMAIL=your_hablla_email
HABLLA_PASSWORD=your_hablla_password
HABLLA_WORKSPACE_ID=workspace_identifier
HABLLA_BOARD_ID=board_identifier
SPREADSHEET_ID=target_google_spreadsheet_id
GitHub Actions Activador
Este worker es desencadenado por:
on:
repository_dispatch:
types: [google_token_ready]
Notas de confiabilidad
- Utiliza intervalos de sueño controlados entre solicitudes Hablla
- Utiliza paginación limitada para evitar bucles ilimitados.
- Maneja las pestañas opcionales que faltan (
Base Cliente) con gracia - Envuelve la ejecución en try/catch controlado para lograr estabilidad operativa
Licencia
Este proyecto está bajo la licencia MIT. Ver el notas de licencia en el repositorio.
Autor
Patrick Araujo - Ingeniero Informático
GitHub: https://github.com/PkLavc
Portafolio: https://pklavc.com/projects/
Hablla Integration Worker - Sincronización de datos orientada a la producción para análisis operativos y canales de inteligencia de clientes.
