Hablla Integration Worker | JavaScript

Hablla Integration Worker

Um worker de integração Node.js que sincroniza dados operacionais Hablla no Google Sheets para análise, monitoramento de presença e enriquecimento da base de clientes no estilo CRM.

Visão geral

Este worker faz parte de uma cadeia de integração orientada por eventos. Ele recebe tokens do Google OAuth do worker de autenticação, autentica com Hablla APIs e executa três pipelines sincronizados:

1. Sincronização de cartão (Base Hablla Card)
2. Resumo de desempenho do atendente (Base Atendente)
3. Exportação de cliente/pessoa (Base Cliente)

A implementação inclui desduplicação, otimização de API, limpeza de dados e práticas seguras de registro para operações de repositório público.

Arquitetura do sistema

graph TB
		A[Google Auth Worker] -->|repository_dispatch| B[Hablla Integration Worker]
		B --> C[Hablla API]
		B --> D[Google Sheets API]
		C --> E[Cards]
		C --> F[Service Summary]
		C --> G[Persons]
		B --> H[Data Sanitization]
		H --> D

Recursos principais

• Sincronização incremental do cartão com updated_after filtragem
• Janela de limpeza de segurança (últimos 7 dias) antes de anexar novos dados
• Limpeza duplicada por ID de cartão exclusivo em Base Hablla Card
• Ingestão de KPI do atendente (TME, TMA, CSAT, FCR)
• Exportação de cliente/pessoa com mapeamento normalizado de contato/tag/campo personalizado
• Prevenção de injeção de fórmula em planilha por meio da função sanitize
• Modelo de execução seguro com comportamento de registro sensível ao mascaramento
• Limitação de taxa entre chamadas de API para reduzir o risco de limitação do provedor

Pipelines de dados

1. Cartão básico Hablla

O worker:

1. Autentica para Hablla
2. Lê linhas recentes de Base Hablla Card
3. Exclui linhas recentes da janela rolante (limpeza de segurança)
4. Busca cartões paginados de Hablla
5. Mapeia campos personalizados e metadados de cartão
6. Acrescenta linhas ao Google Sheets
7. Reconstrói dados desduplicados por ID do cartão

2. Atendente da Base

O worker solicita métricas de resumo de serviço diário de Hablla e anexa linhas por agente contendo:

• totais de serviço
• Métricas TME/TMA
• metadados de conexão
• Indicadores CSAT
• Contadores FCR

3. Cliente Base

O worker busca pessoas/clientes por janela de data e exporta:

• telefone principal e indicador do WhatsApp
• lista de e-mail achatada
• setores e tags
• IDs de campos personalizados fixos mapeados para colunas dedicadas
• campos extras dinâmicos serializados em uma coluna "outros campos"

Controles de segurança

• Sanitização: Prefixa strings de alto risco começando com =, +, -, @
• Registro de segurança pública: evita expor detalhes confidenciais do payload
• Autenticação somente secreta: Credenciais e tokens são injetados apenas no ambiente
• Modelo de fluxo de trabalho com menos privilégios: executa apenas as etapas necessárias em GitHub Actions

Configuração

Variáveis de ambiente necessárias

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 Gatilho

Este worker é acionado por:

on:
	repository_dispatch:
		types: [google_token_ready]

Notas de confiabilidade

• Usa intervalos de suspensão controlados entre solicitações Hablla
• Usa paginação limitada para evitar loops ilimitados
• Lida com guias opcionais ausentes (Base Cliente) graciosamente
• Envolve a execução em try/catch controlado para estabilidade operacional

Licença

Este projeto está licenciado sob a licença MIT. Veja o notas de licença no repositório.

Autor

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

Hablla Integration Worker - Sincronização de dados orientada à produção para análises operacionais e pipelines de inteligência do cliente.