Zenvia Integration Worker | JavaScript

Zenvia Integration Worker

Um serviço de trabalho Node.js que sincroniza dados de chamadas da plataforma de comunicação Zenvia com o Google Sheets para geração de relatórios e análise.

Visão geral

Este worker busca automaticamente registros de chamadas da API da Zenvia e os sincroniza com o Google Sheets, fornecendo uma visão centralizada dos dados de comunicação para operações comerciais.

Recursos

• Sincronização de dados de chamadas: sincroniza automaticamente os registros de chamadas de Zenvia com o Google Sheets
• Filtragem de data: Filtra registros para incluir apenas os dados de ontem
• Suporte a filas: Suporta relatórios de chamadas gerais e específicos da fila
• Atualizações em tempo real: Processa novos dados diariamente por meio de fluxos de trabalho automatizados
• Tratamento seguro de dados: Todas as informações confidenciais são devidamente mascaradas e protegidas

Arquitetura

Componentes

• API de Zenvia Cliente: busca dados de chamadas da plataforma de comunicação de Zenvia
• Integração com Google Sheets: grava dados processados no Google Sheets
• Processamento de Dados: Filtra e formata dados para compatibilidade com planilhas
• Registro seguro: Registra todas as operações com mascaramento de dados confidenciais

Fluxo de dados

1. Autenticação: Recebe token do Google OAuth de Google Auth Worker
2. Busca de dados: Recupera registros de chamadas de API de Zenvia
3. Processamento de Dados: Filtra os registros de ontem e formata os dados
4. Atualização de planilha: anexa dados processados ao Google Sheets
5. Relatório de status: Reporta o status de execução ao sistema de monitoramento

Configuração

Variáveis de ambiente necessárias

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 Segredos

Os seguintes segredos devem ser configurados no repositório GitHub:

• GOOGLE_TOKEN: OAuth token de acesso (fornecido por Google Auth Worker)
• ZENVIA_ACCESS_TOKEN: API de Zenvia token de acesso
• ZENVIA_QUEUE_ID: ID de fila opcional para relatórios de fila específicos
• SPREADSHEET_ID: ID da planilha do Google Sheets
• SHEET_NAME: Nome da planilha de destino na planilha

Uso

Acionando a sincronização

O worker é acionado automaticamente por eventos de envio do repositório do Google Auth Worker:

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

Processamento de Dados

O worker processa dados de chamada com a seguinte lógica:

1. Filtragem de data: Inclui apenas registros de ontem
2. Filtragem de fila: Se ZENVIA_QUEUE_ID é fornecido, busca dados específicos da fila
3. Mapeamento de dados: mapeia campos Zenvia para colunas da planilha
4. Processamento em lote: Envia dados em lotes de 5.000 linhas para evitar limites de API

Campos de dados

Os seguintes campos são sincronizados com o Google Sheets:

• ID de chamada
• Data/Hora (formatada para fuso horário do Brasil)
• Números de origem/destino
• Informações do agente
• Status e duração da chamada
• Disponibilidade de gravação
• Razões de desconexão

Recursos de segurança

• Segurança de token: OAuth tokens são recebidos com segurança por meio de envio de repositório
• Mascaramento de dados: Todas as informações confidenciais são mascaradas em logs
• Variáveis de ambiente: credenciais armazenadas com segurança como variáveis de ambiente
• Permissões mínimas: fluxos de trabalho GitHub Actions usam permissões mínimas necessárias

Monitoramento

O status de execução é relatado ao sistema de monitoramento central:

• Status de sucesso/falha
• Número de registros processados
• Carimbos de data e hora de execução
• Detalhes do erro (com dados confidenciais mascarados)

Solução de problemas

Problemas comuns

1. Erros de autenticação: Verifique o token do Google e o token de acesso Zenvia
2. API Limites de taxa: O worker inclui atrasos para evitar limitação de taxa
3. Filtragem de data: Certifique-se de que o fuso horário do sistema esteja configurado corretamente
4. Permissões de planilha: Verifique as permissões do Google Sheets API

Registros

Todos os logs de execução são processados por meio de funções de log seguras que:

• Mascarar informações confidenciais
• Incluir carimbos de data/hora e níveis de log
• Reportar ao sistema de monitoramento

Pontos de Integração

• Google Auth Worker: Recebe tokens OAuth
• API de Zenvia: busca dados de chamada
• Google Sheets API: Grava dados processados
• Monitor de operações em nuvem: relata o status de execução

Contribuindo

1. Bifurque o repositório
2. Crie uma ramificação de recursos
3. Faça suas alterações
4. Adicione testes para suas alterações
5. Envie uma solicitação pull

Licença

Este projeto está licenciado sob a licença MIT - veja o notas de licença no repositório para obter detalhes.

Suporte

Para suporte e dúvidas, entre em contato com a equipe de desenvolvimento.

Autor

Patrick Araujo - Engenheiro de Computação
GitHub: https://github.com/PkLavc
Portfólio: https://pklavc.com/projects/

Zenvia Integration Worker - Pipeline automatizado de ingestão de dados de chamadas para análise de comunicações.