Zenvia Integration Worker

Un servicio de worker Node.js que sincroniza los datos de las llamadas desde la plataforma de comunicación Zenvia con Google Sheets para generar informes y análisis.

Descripción general

Este worker recupera automáticamente los registros de llamadas dla API de Zenvia y los sincroniza con Google Sheets, proporcionando una vista centralizada de los datos de comunicación para las operaciones comerciales.

Características

Sincronización de datos de llamadas: Sincroniza automáticamente los registros de llamadas de Zenvia con Google Sheets
Filtrado de fechas: Filtra registros para incluir solo los datos de ayer
Soporte de cola: Admite informes de llamadas generales y específicos de colas
Actualizaciones en tiempo real: Procesa nuevos datos diariamente a través de flujos de trabajo automatizados
Manejo seguro de datos: Toda la información confidencial está debidamente enmascarada y protegida

Arquitectura

Componentes

API de Zenvia Cliente: Obtiene datos de llamadas de la plataforma de comunicación de Zenvia
Integración de Google Sheets: escribe datos procesados en Google Sheets
Procesamiento de datos: Filtra y da formato a los datos para compatibilidad con hojas de cálculo.
Registro seguro: Registra todas las operaciones con enmascaramiento de datos confidenciales

Flujo de datos

Autenticación: Recibe el token de Google OAuth de Google Auth Worker
Obtención de datos: Recupera registros de llamadas de API de Zenvia
Procesamiento de datos: Filtros para registros de ayer y datos de formato.
Actualización de hoja: Agrega datos procesados a Google Sheets
Informes de estado: Informa el estado de ejecución al sistema de monitoreo

Configuración

Variables de entorno requeridas

GOOGLE_TOKEN=oauth_access_token_from_google_auth_worker
ZENVIA_ACCESS_TOKEN=your_zenvia_api_access_token
ZENVIA_QUEUE_ID=optional_queue_id_for_specific_queue_reports
SPREADSHEET_ID=your_google_spreadsheet_id
SHEET_NAME=your_google_sheet_name

GitHub Secretos

Se deben configurar los siguientes secretos en el repositorio GitHub:

GOOGLE_TOKEN: OAuth token de acceso (proporcionado por Google Auth Worker)
ZENVIA_ACCESS_TOKEN: API de Zenvia token de acceso
ZENVIA_QUEUE_ID: ID de cola opcional para informes de cola específicos
SPREADSHEET_ID: ID de hoja de cálculo de Google Sheets
SHEET_NAME: nombre de la hoja de destino dentro de la hoja de cálculo

Uso

Activación de sincronización

El worker se activa automáticamente mediante eventos de envío del repositorio desde Google Auth Worker:

{
  "event_type": "google_token_ready",
  "client_payload": {
    "token": "oauth_access_token"
  }
}

Procesamiento de datos

El worker procesa los datos de la llamada con la siguiente lógica:

Filtrado de fechas: Sólo incluye registros de ayer
Filtrado de colas: Si ZENVIA_QUEUE_ID se proporciona, recupera datos específicos de la cola
Mapeo de datos: Asigna campos Zenvia a columnas de hoja de cálculo
Procesamiento por lotes: Envía datos en lotes de 5000 filas para evitar límites de API

Campos de datos

Los siguientes campos están sincronizados con Google Sheets:

ID de llamada
Fecha/Hora (formateada para la zona horaria de Brasil)
Números de origen/destino
Información del agente
Estado y duración de la llamada
Disponibilidad de grabación
Motivos de desconexión

Funciones de seguridad

Seguridad de tokens: Los tokens OAuth se reciben de forma segura a través del envío del repositorio.
Enmascaramiento de datos: Toda la información confidencial está enmascarada en registros
Variables de entorno: Credenciales almacenadas de forma segura como variables de entorno
Permisos mínimos: Los flujos de trabajo GitHub Actions utilizan los permisos mínimos requeridos

Monitoreo

El estado de ejecución se informa al sistema de seguimiento central:

Estado de éxito/fracaso
Número de registros procesados
Marcas de tiempo de ejecución
Detalles del error (con datos confidenciales enmascarados)

Solución de problemas

Problemas comunes

Errores de autenticación: Verificar el token de Google y el token de acceso Zenvia
API Límites de tarifa: El worker incluye retrasos para evitar la limitación de tarifas
Filtrado de fechas: Asegúrese de que la zona horaria del sistema esté configurada correctamente
Permisos de hoja: Verificar los permisos de Google Sheets API

Registros

Todos los registros de ejecución se procesan mediante funciones de registro seguras que:

Enmascarar información confidencial
Incluir marcas de tiempo y niveles de registro
Reportar al sistema de monitoreo

Puntos de integración

Google Auth Worker: Recibe OAuth tokens
API de Zenvia: recupera datos de llamadas
Google Sheets API: escribe datos procesados
Monitor de operaciones en la nube: Estado de ejecución de informes

Contribuyendo

Bifurcar el repositorio
Crear una rama de características
Haz tus cambios
Agregue pruebas para sus cambios
Enviar una solicitud de extracción

Licencia

Este proyecto tiene la licencia MIT (consulte la notas de licencia en el repositorio para más detalles.

Soporte

Para soporte y preguntas, comuníquese con el equipo de desarrollo.

Autor

Patrick Araujo - Ingeniero Informático
GitHub: https://github.com/PkLavc
Portafolio: https://pklavc.com/projects/

Zenvia Integration Worker - Pipeline automatizada de ingesta de datos de llamadas para análisis de comunicaciones.

Zenvia Integration Worker | JavaScript

Contexto del problema, stack y tipo de sistema

Alcance técnico

Documentación completa del proyecto