Pular para o conteúdo principal

Configuração do Sistema

OmniCRM utiliza dois sistemas principais de configuração: crm_config.yaml para configurações da API do backend e variáveis de ambiente para a interface do usuário React. Este guia cobre todas as opções de configuração e como modificá-las.

Visão Geral dos Arquivos de Configuração​

Configuração da API do Backend:

  • Arquivo: OmniCRM-API/crm_config.yaml
  • Formato: YAML
  • Requer: Reinício da API após alterações
  • Usado para: Banco de dados, integrações, segurança, provisionamento

Configuração da Interface do Usuário Frontend:

  • Arquivo: OmniCRM-UI/.env
  • Formato: Variáveis de ambiente
  • Requer: Recompilação da UI após alterações
  • Usado para: Branding, recursos, serviços externos

Configuração do Backend (crm_config.yaml)​

O arquivo crm_config.yaml contém todas as configurações do sistema backend.

Configuração do Banco de Dados​

database:
  username: omnitouch
  password: omnitouch2024
  server: localhost

Campos:

  • username - Nome de usuário do banco de dados MySQL
  • password - Senha do banco de dados MySQL
  • server - Nome do host ou IP do servidor de banco de dados (padrão: localhost)

Conexão com o Banco de Dados:

  • O nome do banco de dados é codificado como omnicrm
  • Porta padrão: 3306 (padrão do MySQL)
  • String de conexão: mysql+pymysql://username:password@server/omnicrm

Nota de Segurança: Nunca comite este arquivo com credenciais reais para controle de versão. Use configuração específica do ambiente ou gerenciamento de segredos.

Tipos de Serviço​

service_types:
  - omnicharge
  - mobile
  - internet
  - iptv
  - voip

Propósito: Define valores válidos de tipo de serviço para o campo service_type.

Tipos Padrão:

  • mobile - Serviços móveis/celulares
  • internet - Internet fixa (fibra, DSL, sem fio)
  • iptv - Serviços de televisão
  • voip - Serviços de voz sobre IP
  • omnicharge - Serviços de faturamento/cobrança

Adicione tipos de serviço personalizados aqui para seus casos de uso específicos.

Configuração do HSS (Home Subscriber Server)​

hss:
  hss_peers:
    - 'http://10.179.2.140:8080'
  apn_list: "1,2,3,4,5,6"

Campos:

  • hss_peers - Lista de URLs do servidor HSS para gerenciamento de assinantes
  • apn_list - Lista separada por vírgulas de identificadores APN (Access Point Name)

Usado para: Provisionamento de rede móvel e autenticação de assinantes.

Configuração de Email do Mailjet​

mailjet:
  api_key: your_mailjet_api_key
  api_secret: your_mailjet_api_secret

  api_crmCommunicationCustomerWelcome:
    from_email: "support@yourcompany.com"
    from_name: "Your Company Support"
    template_id: 5977509
    subject: "Welcome to Your Company"

  api_crmCommunicationCustomerInvoice:
    from_email: "billing@yourcompany.com"
    from_name: "Your Company Billing"
    template_id: 6759851
    subject: "Your Invoice - "

Tipos de Email Configurados:

  • api_crmCommunicationCustomerWelcome - Email de boas-vindas para novos clientes
  • api_crmCommunicationCustomerInvoice - Entrega de fatura
  • api_crmCommunicationCustomerInvoiceReminder - Lembretes de faturas em atraso
  • api_crmCommunicationUserWelcome - Boas-vindas para novos usuários da equipe
  • api_crmCommunicationUserPasswordReset - Solicitações de redefinição de senha
  • api_crmCommunicationUserPasswordResetSuccess - Redefinição de senha bem-sucedida
  • api_crmCommunicationUserPasswordChange - Notificações de alteração de senha
  • api_crmCommunicationEmailVerification - Verificação de endereço de email
  • api_crmCommunicationsBalanceExpired - Notificações de expiração de serviço
  • api_crmCommunicationsBalanceLow - Alertas de saldo baixo

IDs de Template:

Obtenha da sua conta Mailjet após criar templates de email. Veja integrations_mailjet para detalhes.

Configuração de Provisionamento​

provisioning:
  failure_list: ['admin@yourcompany.com', 'ops@yourcompany.com']

Campos:

  • failure_list - Endereços de email para notificar quando o provisionamento falha

Quando os playbooks do Ansible falham durante o provisionamento, o sistema envia detalhes de erro para esses endereços.

Configuração de Faturas​

invoice:
  template_filename: 'your_invoice_template.html'

Campos:

  • template_filename - Arquivo de template HTML para geração de faturas

O arquivo de template deve existir no diretório OmniCRM-API/templates/.

URL Base do CRM​

crm:
  base_url: 'http://localhost:5000'

Propósito: Usado pelos playbooks do Ansible para fazer chamadas de API de volta ao CRM.

Importante:

  • Não inclua barra final
  • Use URL acessível publicamente se os playbooks forem executados em servidores diferentes
  • Atualize ao implantar em produção (por exemplo, https://api.yourcrm.com)

Configuração do OCS (Online Charging System)​

ocs:
  ocsApi: 'http://10.179.2.142:8080/api'
  ocsTenant: 'mnc380.mcc313.3gppnetwork.org'
  cgrates: 'localhost:2080'

Campos:

  • ocsApi - URL do endpoint da API REST do OCS
  • ocsTenant - Identificador do inquilino para implantações multi-inquilino do OCS
  • cgrates - Endpoint JSON-RPC do CGRateS (host:port)

Usado para: Cobrança em tempo real, gerenciamento de saldo, rastreamento de uso.

Configuração do SMSC (SMS Center)​

smsc:
  source_msisdn: 'YourCompany'
  smsc_url: 'http://10.179.2.216/SMSc/'
  api_key: 'your_smsc_api_key'

Campos:

  • source_msisdn - ID do remetente para SMS de saída (nome da empresa ou código curto)
  • smsc_url - URL do endpoint da API do SMS Center
  • api_key - Chave de autenticação para a API do SMSC

Usado para: Envio de notificações SMS (alertas de saldo, OTPs, etc.)

Configuração de Transmissão de Célula​

cbc_url: 'http://10.179.1.113:8080'

Propósito: Endpoint da API do Centro de Transmissão de Célula (CBC) para alertas de emergência.

Veja features_cell_broadcast para detalhes de uso.

Chave Secreta JWT​

jwt_secret: '2b93110f723db60172c8e9a1eaa80027a9a9c3f05b44e50dc3fcf38dba68d87e'

Propósito: Chave secreta para assinar tokens de autenticação JWT.

Segurança:

  • Gere usando: openssl rand -hex 32
  • Nunca compartilhe publicamente
  • Alterar isso invalida todas as sessões de usuário existentes
  • Use segredos diferentes para dev/staging/produção

Configuração de Pagamento Stripe​

stripe:
  secret_key: 'sk_test_...'
  publishable_key: 'pk_test_...'
  currency: 'usd'
  statement_descriptor_suffix: 'YOURCOMPANY'

Campos:

  • secret_key - Chave secreta da API do Stripe (começa com sk_)
  • publishable_key - Chave publicável do Stripe (começa com pk_)
  • currency - Código de moeda ISO 4217 (usd, gbp, aud, eur, etc.)
  • statement_descriptor_suffix - Texto que aparece nos extratos de cartão de crédito dos clientes

Tipos de Chaves:

  • Chaves de teste: sk_test_... e pk_test_... (para desenvolvimento)
  • Chaves ao vivo: sk_live_... e pk_live_... (para produção)

Veja integrations_stripe para detalhes de configuração.

Chaves da API​

api_keys:
  "your-secure-api-key-minimum-32-chars":
    roles: ["admin"]
    ips: ["127.0.0.1", "::1"]
  "another-api-key-for-specific-service":
    roles: ["customer_service_agent_1"]
    ips: ["10.0.1.50"]

Estrutura:

  • Chave (string): A chave da API real (mínimo 32 caracteres)
  • roles (lista): Nomes de função aos quais esta chave tem acesso
  • ips (lista, opcional): Endereços IP permitidos para usar esta chave

Gerando Chaves da API:

openssl rand -base64 48

Funções:

  • admin - Acesso total a todos os endpoints
  • Funções personalizadas definidas no sistema RBAC

Veja administration_api_keys e concepts_api para detalhes.

Lista Branca de IP​

ip_whitelist:
  "10.179.2.142":
    roles: ["admin"]
  "192.168.1.100":
    roles: ["provisioning"]

Propósito: Permitir que endereços IP específicos acessem a API sem autenticação.

Estrutura:

  • Endereço IP (string): Endereço IPv4 a ser incluído na lista branca
  • roles (lista): Funções atribuídas a solicitações deste IP

Aviso de Segurança:

  • Use apenas para redes internas confiáveis
  • Não deve usar IPs localhost (127.0.0.1, ::1)
  • Use chaves da API em vez disso para acesso externo
  • Considere regras de firewall como proteção adicional

Configuração Frontend (.env)​

A interface do usuário React é configurada por meio de variáveis de ambiente em OmniCRM-UI/.env.

Configuração de Branding​

REACT_APP_COMPANY_NAME="YourCompany"
REACT_APP_PORTAL_NAME="YourPortal"
REACT_APP_SELF_CARE_NAME="YourCare"
REACT_APP_COMPANY_TAGLINE="Your Company Slogan"

Campos:

  • REACT_APP_COMPANY_NAME - Nome da empresa (aparece em cabeçalhos, emails, branding)
  • REACT_APP_PORTAL_NAME - Nome do portal de administração (títulos de página, navegação)
  • REACT_APP_SELF_CARE_NAME - Nome do portal do cliente
  • REACT_APP_COMPANY_TAGLINE - Slogan de marketing (aparece na página de login)

Exemplo:

Configuração Regional​

REACT_APP_DEFAULT_LOCATION="London, United Kingdom"
REACT_APP_DEFAULT_COUNTRY="United Kingdom"
REACT_APP_DEFAULT_LANGUAGE="en"
REACT_APP_LOCALE="en-GB"

Campos:

  • REACT_APP_DEFAULT_LOCATION - Localização padrão para mapas e endereços
  • REACT_APP_DEFAULT_COUNTRY - País padrão para formulários
  • REACT_APP_DEFAULT_LANGUAGE - Idioma da interface do usuário (ar, ch, en, fr, gr, it, ru, sp)
  • REACT_APP_LOCALE - Localidade para formatação de data/número (en-GB, en-US, etc.)

Idiomas Suportados:

  • ar - Árabe
  • ch - Chinês
  • en - Inglês (padrão)
  • fr - Francês
  • gr - Grego
  • it - Italiano
  • ru - Russo
  • sp - Espanhol

Configuração de Moeda​

REACT_APP_CURRENCY_CODE="USD"
REACT_APP_CURRENCY_SYMBOL="$"

Campos:

  • REACT_APP_CURRENCY_CODE - Código de moeda ISO 4217
  • REACT_APP_CURRENCY_SYMBOL - Símbolo a ser exibido (£, $, €, etc.)

Moedas Comuns:

  • USD - $ (Dólar Americano)
  • GBP - £ (Libra Esterlina)
  • EUR - € (Euro)
  • AUD - $ (Dólar Australiano)
  • CAD - $ (Dólar Canadense)

Nota: Deve corresponder a stripe.currency em crm_config.yaml.

Configuração de Tema de Cores​

REACT_APP_PRIMARY_COLOR=#405189
REACT_APP_SECONDARY_COLOR=#2bFFcf
REACT_APP_TERTIARY_COLOR=#1a9fbf

Cores Disponíveis:

  • REACT_APP_PRIMARY_COLOR - Cor principal da marca (botões, links, destaques)
  • REACT_APP_SECONDARY_COLOR - Cor de destaque
  • REACT_APP_TERTIARY_COLOR - Destaque adicional
  • REACT_APP_SUCCESS_COLOR - Mensagens de sucesso (#28a745)
  • REACT_APP_INFO_COLOR - Mensagens de informação (#17a2b8)
  • REACT_APP_WARNING_COLOR - Avisos (#ffc107)
  • REACT_APP_DANGER_COLOR - Erros (#dc3545)
  • REACT_APP_LIGHT_COLOR - Fundos claros (#f8f9fa)
  • REACT_APP_DARK_COLOR - Texto escuro (#343a40)
  • REACT_APP_PRIMARY_DARK_COLOR - Variante escura da cor primária (para modo escuro/estados de hover)

Formato: Códigos de cores hexadecimais (#RRGGBB)

Configuração de Fonte​

REACT_APP_FONT_FAMILY=Quicksand

Propósito: Define a família de fontes primária para toda a interface do usuário.

Importante: Todas as fontes são auto-hospedadas localmente dentro do aplicativo OmniCRM-UI. Isso significa:

  • Nenhum carregamento de fonte externo - As fontes são empacotadas com o aplicativo
  • Compatível com jardim murado - Nenhum acesso à internet é necessário para que as fontes funcionem
  • Operação offline - Funcionalidade completa em ambientes de rede isolados ou restritos
  • Privacidade - Nenhuma solicitação externa para Google Fonts, Adobe Fonts ou outros CDNs
  • Desempenho - Carregamento mais rápido sem dependências externas
  • Segurança - Sem rastreamento de terceiros ou vazamento de dados através de solicitações de fonte

Opções Disponíveis:

Fontes Sem Serifa:

  • Inter
  • Roboto
  • Open Sans
  • Lato
  • Quicksand (padrão)
  • Poppins
  • Nunito
  • Montserrat
  • Work Sans
  • Source Sans Pro
  • Raleway
  • Ubuntu
  • Josefin Sans
  • HKGrotesk

Fontes Serifadas:

  • Merriweather
  • Lora
  • Playfair Display

Fontes do Sistema:

  • System - Usa fontes nativas do dispositivo para melhor desempenho e menor tamanho do pacote

Padrão: Quicksand

Adicionando Fontes Personalizadas​

Sim, você pode adicionar fontes adicionais! Todas as fontes são armazenadas localmente no aplicativo.

Para adicionar uma nova fonte personalizada:

  1. Adicione arquivos de fonte em OmniCRM-UI/src/assets/fonts/your-font-name/

    • Use o formato WOFF2 para melhor compressão e suporte a navegadores
    • Inclua múltiplos pesos (300, 400, 500, 600, 700) para renderização adequada
    • Nomeie os arquivos: your-font-name-300.woff2, your-font-name-400.woff2, etc.

  2. Defina regras @font-face em OmniCRM-UI/src/assets/scss/fonts/_google-fonts.scss

    //
    // Sua Fonte Personalizada - Descrição
    //

    @font-face {
      font-family: 'Your Font Name';
      font-style: normal;
      font-weight: 400;
      font-display: swap;
      src: url("../../fonts/your-font-name/your-font-name-400.woff2") format('woff2');
    }

    @font-face {
      font-family: 'Your Font Name';
      font-style: normal;
      font-weight: 700;
      font-display: swap;
      src: url("../../fonts/your-font-name/your-font-name-700.woff2") format('woff2');
    }

  3. Defina no arquivo .env:

    REACT_APP_FONT_FAMILY=Your Font Name

Diretrizes de Peso da Fonte:

  • 300 - Leve (opcional, para cabeçalhos sutis)
  • 400 - Regular (obrigatório, texto padrão)
  • 500 - Médio (opcional, ênfase)
  • 600 - Semi-Negrito (opcional, subtítulos)
  • 700 - Negrito (obrigatório, cabeçalhos e texto forte)

Nota: Todas as fontes permanecem auto-hospedadas e funcionam offline. Nenhum CDN externo ou conexão com a internet é necessária.

Serviços Externos​

REACT_APP_GOOGLE_API_KEY=your_google_maps_api_key
REACT_APP_STRIPE_PUBLISHABLE_KEY=pk_test_...

Campos:

  • REACT_APP_GOOGLE_API_KEY - Chave da API do Google Maps (para mapas, geolocalização)
  • REACT_APP_STRIPE_PUBLISHABLE_KEY - Chave publicável do Stripe (para pagamentos)

Deve corresponder:

REACT_APP_STRIPE_PUBLISHABLE_KEY deve corresponder a stripe.publishable_key em crm_config.yaml.

REACT_APP_WEB_APP_1_NAME="GitHub"
REACT_APP_WEB_APP_1_URL="https://github.com"
REACT_APP_WEB_APP_1_ICON_PATH="resources/webapp_icons/github.png"

Propósito: Configurar até 6 links de aplicativos web de acesso rápido na navegação da interface do usuário.

Padrão:

  • REACT_APP_WEB_APP_N_NAME - Nome exibido
  • REACT_APP_WEB_APP_N_URL - URL de destino
  • REACT_APP_WEB_APP_N_ICON_PATH - Caminho do arquivo do ícone (relativo a public/)

Exemplos de Ícones: GitHub, Xero, Monday.com, Gmail, MailJet, Slack

Integração com Grafana​

REACT_APP_GRAFANA_URLS=http://grafana1.local/d/abc,http://grafana2.local/d/xyz
REACT_APP_GRAFANA_LABELS=Network Monitoring,Service Health
REACT_APP_GRAFANA_API_KEY=your_grafana_api_key

Campos:

  • REACT_APP_GRAFANA_URLS - Lista separada por vírgulas de URLs de dashboards do Grafana
  • REACT_APP_GRAFANA_LABELS - Lista separada por vírgulas de nomes de dashboards
  • REACT_APP_GRAFANA_API_KEY - Chave da API do Grafana para incorporação

Uso: Incorpora dashboards do Grafana na página de dashboard do OmniCRM.

URLs de Suporte​

REACT_APP_FAQS_URL=https://support.yourcompany.com/faqs
REACT_APP_SUPPORT_URL=https://support.yourcompany.com

Propósito: Links para recursos de suporte externos mostrados na interface do usuário.

Logins Sociais​

REACT_APP_ALLOW_SOCIAL_LOGINS=yes

Opções:

  • yes - Habilitar botões de login social (Google, Facebook, etc.)
  • no - Desabilitar logins sociais

Nota: Provedores de login social devem ser configurados separadamente.

Configuração de Recarga e Recarregamento​

REACT_APP_TOPUP_PRICE_PER_DAY=10

Propósito: Define o preço por dia para serviços de recarga/recarregamento no portal de autoatendimento.

Campos:

  • REACT_APP_TOPUP_PRICE_PER_DAY - Preço diário para serviços de recarga (valor numérico)

Exemplo: Se definido como 10 e a moeda for USD, os clientes pagam $10 por dia de serviço.

Nota: Este valor deve corresponder à configuração de preços do backend. Veja features_topup_recharge para detalhes completos de configuração.

Aplicando Alterações de Configuração​

Backend (crm_config.yaml)​

  1. Edite OmniCRM-API/crm_config.yaml
  2. Salve as alterações
  3. Reinicie o serviço da API:
cd OmniCRM-API
sudo systemctl restart omnicrm-api
# ou
./restart_api.sh

As alterações entram em vigor imediatamente após o reinício.

Frontend (.env)​

  1. Edite OmniCRM-UI/.env
  2. Salve as alterações
  3. Recompile a UI:
cd OmniCRM-UI
npm run build
  1. Reinicie o serviço da UI ou servidor web

Modo de Desenvolvimento:

Durante o desenvolvimento com npm start, reinicie o servidor de desenvolvimento para aplicar as alterações.

Melhores Práticas de Configuração​

Segurança​

  • Nunca comite segredos - Use .gitignore para arquivos de configuração com credenciais
  • Use configurações específicas do ambiente - Separe configurações de dev/staging/produção
  • Rotacione segredos regularmente - Atualize segredos JWT, chaves da API periodicamente
  • Limite permissões de chaves da API - Atribua funções mínimas necessárias
  • Use listas brancas de IP com moderação - Prefira chaves da API para melhor segurança

Manutenção​

  • Documente alterações - Mantenha um changelog de modificações de configuração
  • Faça backup das configurações - Armazene cópias antes de grandes alterações
  • Teste em staging - Verifique alterações de configuração antes da implantação em produção
  • Controle de versão - Rastreie templates de configuração (sem segredos) no git

Desempenho​

  • Use banco de dados local - Evite banco de dados remoto para melhor desempenho
  • Configure cache - Habilite cache do OCS se disponível
  • Otimize Grafana - Limite o número de dashboards incorporados

Branding​

  • Combine cores - Certifique-se de que as cores da interface do usuário complementam seu logotipo
  • Teste contraste - Verifique a legibilidade do texto em fundos coloridos
  • Teste em dispositivos móveis - Verifique o branding em dispositivos móveis
  • Posicionamento do logotipo - Coloque logotipos da empresa em OmniCRM-UI/public/resources/

Solução de Problemas​

Alterações não aplicadas

  • Causa: Serviço não reiniciado ou UI não recompilada
  • Solução: Reinicie os serviços da API/UI após alterações de configuração

Erros de sintaxe YAML

  • Causa: Formatação YAML inválida (indentação, aspas, etc.)
  • Solução: Valide o YAML online ou use yamllint crm_config.yaml

Falha na conexão com o banco de dados

  • Causa: Credenciais erradas ou servidor inacessível
  • Solução: Verifique se o banco de dados está em execução, se as credenciais estão corretas

Pagamentos Stripe não funcionando

  • Causa: Chaves incompatíveis entre backend e frontend
  • Solução: Certifique-se de que publishable_key corresponda em ambos os arquivos

Emails não enviados

  • Causa: Credenciais do Mailjet inválidas ou IDs de template
  • Solução: Verifique a chave/secreto da API do Mailjet, verifique se os IDs de template existem

Documentação Relacionada​

  • administration_api_keys - Gerenciamento de chaves da API
  • integrations_stripe - Configuração de pagamento Stripe
  • integrations_mailjet - Integração de email
  • concepts_api - Autenticação da API
  • rbac - Controle de acesso baseado em função