Importador Bitrix

Aplicativo desktop (Electron) para importacao controlada de dados Excel no Bitrix24. O fluxo inclui mapeamento coluna->campo, normalizacao, deduplicacao e distribuicao por usuario com limite de carga.

Este README foi escrito para publicacao sem expor dados confidenciais. Nenhuma credencial, webhook ou informacao sensivel deve ser versionada.

Escopo funcional

• Entrada: planilha Excel (.xlsx/.xls) com cabecalhos na primeira linha.
• Saida: mesma planilha com coluna de status atualizada (ex: IMPORTADO = SIM/ERRO).
• Entidades suportadas pela UI: lead e deal (com validacao dinamica de campos no Bitrix).
• Operacoes: cria, atualiza ou ignora registros existentes (baseado em telefone/email quando aplicavel).
• Distribuicao: round-robin simples com limite por usuario do departamento.

Fluxo tecnico (pipeline)

1. UI seleciona arquivo Excel e entidade (lead/deal).
2. UI consulta campos da entidade via crm.{entity}.fields.
3. UI monta o mapeamento coluna->campo e valida campos customizados.
4. Backend le a planilha e cria um mapa de colunas.
5. Para cada linha nao marcada como importada:
   • Normaliza dados (telefone/CPF/CNPJ quando presentes).
   • Busca existente por telefone/email (contato/empresa quando aplicavel).
   • Atualiza se houver diferencas, senao ignora.
   • Se nao existir, cria novo registro com ASSIGNED_BY_ID definido.
   • Marca status na coluna configurada.
6. Ao final, grava a planilha com status e retorna o relatorio da sessao.

Arquitetura

• main.js: janela Electron + IPC (UI -> backend).
• preload.js: exposicao segura da API para o renderer.
• ui/: HTML/CSS/JS com mapeamento, validacao e log de progresso.
• core/:
  • runner.js: orquestra leitura, mapeamento, importacao e escrita do Excel.
  • importer.js: normalizacao, deduplicacao e decisao create/update/skip.
  • distributor.js: round-robin com limite por usuario.
• services/:
  • bitrixService.js: cliente REST (webhook) com retry e rate limit.
  • excelService.js: I/O de planilha.
• utils/: logger, normalizer, retry, rateLimiter, validator.

Endpoints Bitrix usados

• crm.{entity}.fields (descoberta de campos)
• crm.{entity}.list (search por telefone/email)
• crm.{entity}.add (create)
• crm.{entity}.update (update)
• department.get (lista de departamentos)
• user.get (usuarios por departamento)
• userfield.get (metadata de campos customizados)

Requisitos

• Node.js LTS.
• Webhook do Bitrix24 com permissao para CRM e usuarios.

Instalacao

npm install

Execucao

App desktop (Electron)

npm run start

Modo CLI (opcional)

npm run cli

No modo CLI, os valores ficam em index.js (arquivo, entidade, usuarios). Ajuste conforme necessario.

Build/empacotamento

npm run pack
npm run dist

Configuracao (sem segredos)

As configuracoes estao em config.js e variaveis de ambiente via dotenv. Nao versionar dados reais.

Use o arquivo .env.example como base e crie um .env local com valores ficticios.

Exemplo de .env:

BITRIX_WEBHOOK=https://example.bitrix24.com.br/rest/1/xxxxxxxx/
REQUEST_TIMEOUT=20000
MAX_RETRY=3
RATE_LIMIT_DELAY=400
MAX_PER_USER=6
STATUS_COLUMN=IMPORTADO

Variaveis

• BITRIX_WEBHOOK: base URL do webhook (sem expor tokens reais).
• REQUEST_TIMEOUT: timeout de chamadas HTTP (ms).
• MAX_RETRY: tentativas com backoff.
• RATE_LIMIT_DELAY: delay por chamada para evitar limite da API.
• MAX_PER_USER: limite de registros por usuario.
• STATUS_COLUMN: nome da coluna de status na planilha.

Detalhes de deduplicacao

• Para entidades contact/company, busca por PHONE e depois EMAIL.
• A normalizacao remove nao numericos de telefone/CPF/CNPJ.
• Atualizacao ocorre somente quando existe diferenca entre campos.

Observabilidade

• Logger de sessao gera contadores (created/updated/skipped/errors) e detalhes por linha.
• UI recebe eventos de progresso via IPC e exibe log em tempo real.

Segurança e privacidade

• Nunca versionar .env com valores reais.
• Nao incluir dados pessoais em exemplos.
• Evitar logs persistentes com dados sensiveis.

Estrutura do projeto

importador-bitrix/
  core/
  services/
  ui/
  utils/
  .env.example
  CHANGELOG.md
  config.js
  index.js
  main.js
  preload.js

Limitacoes conhecidas

• A UI suporta lead e deal; outras entidades exigem ajustes.
• A planilha processada usa a primeira aba e a primeira linha como cabecalho.
• A deduplicacao por telefone/email so e aplicada a contact/company.
• O arquivo de origem e sobrescrito com status (nao ha modo dry-run).
• A importacao e sequencial, sem paralelismo por design.

Releases e Changelog

• Releases: https://github.com/OsmarZM/Importador-Bitrix24/releases
• Changelog: CHANGELOG.md (Keep a Changelog)

Licenca

Defina a licenca que voce deseja ao publicar o repositorio (ex: MIT, Apache-2.0).