Saltar al contenido principal

Configuración del Sistema

OmniCRM utiliza dos sistemas de configuración principales: crm_config.yaml para la configuración del API del backend y variables de entorno para la interfaz de usuario de React. Esta guía cubre todas las opciones de configuración y cómo modificarlas.

Resumen de Archivos de Configuración​

Configuración del API del Backend:

  • Archivo: OmniCRM-API/crm_config.yaml
  • Formato: YAML
  • Requiere: Reinicio del API después de los cambios
  • Usado para: Base de datos, integraciones, seguridad, aprovisionamiento

Configuración de la Interfaz de Usuario del Frontend:

  • Archivo: OmniCRM-UI/.env
  • Formato: Variables de entorno
  • Requiere: Reconstrucción de la UI después de los cambios
  • Usado para: Marca, características, servicios externos

Configuración del Backend (crm_config.yaml)​

El archivo crm_config.yaml contiene todos los ajustes del sistema del backend.

Configuración de la Base de Datos​

database:
  username: omnitouch
  password: omnitouch2024
  server: localhost

Campos:

  • username - Nombre de usuario de la base de datos MySQL
  • password - Contraseña de la base de datos MySQL
  • server - Nombre de host o IP del servidor de la base de datos (por defecto: localhost)

Conexión a la Base de Datos:

  • El nombre de la base de datos está codificado como omnicrm
  • Puerto por defecto: 3306 (por defecto de MySQL)
  • Cadena de conexión: mysql+pymysql://username:password@server/omnicrm

Nota de Seguridad: Nunca comprometas este archivo con credenciales reales a control de versiones. Utiliza configuración específica del entorno o gestión de secretos.

Tipos de Servicio​

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

Propósito: Define los valores válidos de tipo de servicio para el campo service_type.

Tipos por Defecto:

  • mobile - Servicios móviles/celulares
  • internet - Internet fijo (fibra, DSL, inalámbrico)
  • iptv - Servicios de televisión
  • voip - Servicios de voz sobre IP
  • omnicharge - Servicios de facturación/cobro

Agrega tipos de servicio personalizados aquí para tus casos de uso específicos.

Configuración del HSS (Servidor de Suscriptores en el Hogar)​

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

Campos:

  • hss_peers - Lista de URLs del servidor HSS para la gestión de suscriptores
  • apn_list - Lista separada por comas de identificadores de APN (Nombre del Punto de Acceso)

Usado para: Aprovisionamiento de redes móviles y autenticación de suscriptores.

Configuración de Correo Electrónico de 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 Correo Electrónico Configurados:

  • api_crmCommunicationCustomerWelcome - Correo electrónico de bienvenida para nuevos clientes
  • api_crmCommunicationCustomerInvoice - Entrega de factura
  • api_crmCommunicationCustomerInvoiceReminder - Recordatorios de factura vencida
  • api_crmCommunicationUserWelcome - Bienvenida a nuevos usuarios del personal
  • api_crmCommunicationUserPasswordReset - Solicitudes de restablecimiento de contraseña
  • api_crmCommunicationUserPasswordResetSuccess - Restablecimiento de contraseña exitoso
  • api_crmCommunicationUserPasswordChange - Notificaciones de cambio de contraseña
  • api_crmCommunicationEmailVerification - Verificación de dirección de correo electrónico
  • api_crmCommunicationsBalanceExpired - Notificaciones de expiración de servicio
  • api_crmCommunicationsBalanceLow - Alertas de saldo bajo

IDs de Plantillas:

Obtén de tu cuenta de Mailjet después de crear plantillas de correo electrónico. Consulta integrations_mailjet para más detalles.

Configuración de Aprovisionamiento​

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

Campos:

  • failure_list - Direcciones de correo electrónico para notificar cuando el aprovisionamiento falla

Cuando los playbooks de Ansible fallan durante el aprovisionamiento, el sistema envía detalles de error a estas direcciones.

Configuración de Factura​

invoice:
  template_filename: 'your_invoice_template.html'

Campos:

  • template_filename - Archivo de plantilla HTML para la generación de facturas

El archivo de plantilla debe existir en el directorio OmniCRM-API/templates/.

URL Base del CRM​

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

Propósito: Usado por los playbooks de Ansible para hacer llamadas API de regreso al CRM.

Importante:

  • No incluyas una barra diagonal al final
  • Usa una URL accesible públicamente si los playbooks se ejecutan en servidores diferentes
  • Actualiza al desplegar en producción (por ejemplo, https://api.yourcrm.com)

Configuración del OCS (Sistema de Carga en Línea)​

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

Campos:

  • ocsApi - URL del endpoint de la API REST del OCS
  • ocsTenant - Identificador de inquilino para implementaciones OCS multi-inquilino
  • cgrates - Endpoint JSON-RPC de CGRateS (host:puerto)

Usado para: Carga en tiempo real, gestión de saldo, seguimiento de uso.

Configuración del SMSC (Centro de SMS)​

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

Campos:

  • source_msisdn - ID del remitente para SMS salientes (nombre de la empresa o código corto)
  • smsc_url - URL del endpoint de la API del Centro de SMS
  • api_key - Clave de autenticación para la API del SMSC

Usado para: Envío de notificaciones SMS (alertas de saldo, OTPs, etc.)

Configuración de Difusión Celular​

cbc_url: 'http://10.179.1.113:8080'

Propósito: Endpoint de la API del Centro de Difusión Celular (CBC) para alertas de emergencia.

Consulta features_cell_broadcast para detalles de uso.

Clave Secreta JWT​

jwt_secret: '2b93110f723db60172c8e9a1eaa80027a9a9c3f05b44e50dc3fcf38dba68d87e'

Propósito: Clave secreta para firmar tokens de autenticación JWT.

Seguridad:

  • Generar usando: openssl rand -hex 32
  • Nunca compartir públicamente
  • Cambiar esto invalida todas las sesiones de usuario existentes
  • Usa secretos diferentes para dev/staging/producción

Configuración de Pagos de Stripe​

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

Campos:

  • secret_key - Clave API secreta de Stripe (comienza con sk_)
  • publishable_key - Clave publicable de Stripe (comienza con pk_)
  • currency - Código de moneda ISO 4217 (usd, gbp, aud, eur, etc.)
  • statement_descriptor_suffix - Texto que aparece en los estados de cuenta de tarjetas de crédito de los clientes

Tipos de Clave:

  • Claves de prueba: sk_test_... y pk_test_... (para desarrollo)
  • Claves en vivo: sk_live_... y pk_live_... (para producción)

Consulta integrations_stripe para detalles de configuración.

Claves 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"]

Estructura:

  • Clave (cadena): La clave API real (mínimo 32 caracteres)
  • roles (lista): Nombres de roles a los que esta clave tiene acceso
  • ips (lista, opcional): Direcciones IP permitidas para usar esta clave

Generación de Claves API:

openssl rand -base64 48

Roles:

  • admin - Acceso total a todos los endpoints
  • Roles personalizados definidos en el sistema RBAC

Consulta administration_api_keys y concepts_api para más detalles.

Lista Blanca de IP​

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

Propósito: Permitir que direcciones IP específicas accedan a la API sin autenticación.

Estructura:

  • Dirección IP (cadena): Dirección IPv4 para incluir en la lista blanca
  • roles (lista): Roles asignados a las solicitudes desde esta IP

Advertencia de Seguridad:

  • Usar solo para redes internas de confianza
  • No se deben usar IPs de localhost (127.0.0.1, ::1)
  • Usar claves API en su lugar para acceso externo
  • Considerar reglas de firewall como protección adicional

Configuración del Frontend (.env)​

La interfaz de usuario de React se configura a través de variables de entorno en OmniCRM-UI/.env.

Configuración de Marca​

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 - Nombre de la empresa (aparece en encabezados, correos, marca)
  • REACT_APP_PORTAL_NAME - Nombre del portal de administración (títulos de página, navegación)
  • REACT_APP_SELF_CARE_NAME - Nombre del portal del cliente
  • REACT_APP_COMPANY_TAGLINE - Lema de marketing (aparece en la página de inicio de sesión)

Ejemplo:

Configuración 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 - Ubicación predeterminada para mapas y direcciones
  • REACT_APP_DEFAULT_COUNTRY - País predeterminado para formularios
  • REACT_APP_DEFAULT_LANGUAGE - Idioma de la UI (ar, ch, en, fr, gr, it, ru, sp)
  • REACT_APP_LOCALE - Configuración regional para formato de fecha/número (en-GB, en-US, etc.)

Idiomas Soportados:

  • ar - Árabe
  • ch - Chino
  • en - Inglés (predeterminado)
  • fr - Francés
  • gr - Griego
  • it - Italiano
  • ru - Ruso
  • sp - Español

Configuración de Moneda​

REACT_APP_CURRENCY_CODE="USD"
REACT_APP_CURRENCY_SYMBOL="$"

Campos:

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

Monedas Comunes:

  • USD - $ (Dólar estadounidense)
  • GBP - £ (Libra esterlina)
  • EUR - € (Euro)
  • AUD - $ (Dólar australiano)
  • CAD - $ (Dólar canadiense)

Nota: Debe coincidir con stripe.currency en crm_config.yaml.

Configuración de Tema de Color​

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

Colores Disponibles:

  • REACT_APP_PRIMARY_COLOR - Color principal de la marca (botones, enlaces, resaltados)
  • REACT_APP_SECONDARY_COLOR - Color de acento
  • REACT_APP_TERTIARY_COLOR - Acento adicional
  • REACT_APP_SUCCESS_COLOR - Mensajes de éxito (#28a745)
  • REACT_APP_INFO_COLOR - Mensajes de información (#17a2b8)
  • REACT_APP_WARNING_COLOR - Advertencias (#ffc107)
  • REACT_APP_DANGER_COLOR - Errores (#dc3545)
  • REACT_APP_LIGHT_COLOR - Fondos claros (#f8f9fa)
  • REACT_APP_DARK_COLOR - Texto oscuro (#343a40)
  • REACT_APP_PRIMARY_DARK_COLOR - Variante oscura del color primario (para modo oscuro/estados de hover)

Formato: Códigos de color hexadecimal (#RRGGBB)

Configuración de Fuente​

REACT_APP_FONT_FAMILY=Quicksand

Propósito: Establece la familia de fuente principal para toda la UI.

Importante: Todas las fuentes están auto-alojadas localmente dentro de la aplicación OmniCRM-UI. Esto significa:

  • Sin carga de fuentes externas - Las fuentes están empaquetadas con la aplicación
  • Compatible con jardín amurallado - No se requiere acceso a Internet para que las fuentes funcionen
  • Operación sin conexión - Funcionalidad completa en entornos de red restringidos o aislados
  • Privacidad - Sin solicitudes externas a Google Fonts, Adobe Fonts, o otros CDNs
  • Rendimiento - Carga más rápida sin dependencias externas
  • Seguridad - Sin seguimiento de terceros o filtración de datos a través de solicitudes de fuentes

Opciones Disponibles:

Fuentes Sans-Serif:

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

Fuentes Serif:

  • Merriweather
  • Lora
  • Playfair Display

Fuentes del Sistema:

  • System - Usa fuentes nativas del dispositivo para mejor rendimiento y menor tamaño de paquete

Predeterminado: Quicksand

Agregando Fuentes Personalizadas​

¡Sí, puedes agregar fuentes adicionales! Todas las fuentes se almacenan localmente en la aplicación.

Para agregar una nueva fuente personalizada:

  1. Agrega archivos de fuente a OmniCRM-UI/src/assets/fonts/your-font-name/

    • Usa formato WOFF2 para mejor compresión y soporte en navegadores
    • Incluye múltiples pesos (300, 400, 500, 600, 700) para un renderizado adecuado
    • Nombra los archivos: your-font-name-300.woff2, your-font-name-400.woff2, etc.

  2. Define reglas @font-face en OmniCRM-UI/src/assets/scss/fonts/_google-fonts.scss

    //
    // Tu Fuente Personalizada - Descripción
    //

    @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. Establece en el archivo .env:

    REACT_APP_FONT_FAMILY=Your Font Name

Guías de Peso de Fuente:

  • 300 - Ligera (opcional, para encabezados sutiles)
  • 400 - Regular (requerido, texto por defecto)
  • 500 - Media (opcional, énfasis)
  • 600 - Semi-Negrita (opcional, subtítulos)
  • 700 - Negrita (requerido, encabezados y texto fuerte)

Nota: Todas las fuentes permanecen auto-alojadas y funcionan sin conexión. No se requiere CDN externo o conexión a Internet.

Servicios Externos​

REACT_APP_GOOGLE_API_KEY=your_google_maps_api_key
REACT_APP_STRIPE_PUBLISHABLE_KEY=pk_test_...

Campos:

  • REACT_APP_GOOGLE_API_KEY - Clave de API de Google Maps (para mapas, geolocalización)
  • REACT_APP_STRIPE_PUBLISHABLE_KEY - Clave publicable de Stripe (para pagos)

Debe Coincidir:

REACT_APP_STRIPE_PUBLISHABLE_KEY debe coincidir con stripe.publishable_key en crm_config.yaml.

Enlaces Rápidos a la Aplicación Web​

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: Configura hasta 6 enlaces de acceso rápido a aplicaciones web en la navegación de la UI.

Patrón:

  • REACT_APP_WEB_APP_N_NAME - Nombre a mostrar
  • REACT_APP_WEB_APP_N_URL - URL de destino
  • REACT_APP_WEB_APP_N_ICON_PATH - Ruta del archivo de icono (relativa a public/)

Ejemplos de Iconos: GitHub, Xero, Monday.com, Gmail, MailJet, Slack

Integración de 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 comas de URLs de paneles de Grafana
  • REACT_APP_GRAFANA_LABELS - Lista separada por comas de nombres de paneles
  • REACT_APP_GRAFANA_API_KEY - Clave de API de Grafana para incrustar

Uso: Incrusta paneles de Grafana en la página del panel de OmniCRM.

URLs de Soporte​

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

Propósito: Enlaces a recursos de soporte externos mostrados en la UI.

Inicios de Sesión Sociales​

REACT_APP_ALLOW_SOCIAL_LOGINS=yes

Opciones:

  • yes - Habilitar botones de inicio de sesión social (Google, Facebook, etc.)
  • no - Deshabilitar inicios de sesión sociales

Nota: Los proveedores de inicio de sesión social deben configurarse por separado.

Configuración de Recarga y Recarga​

REACT_APP_TOPUP_PRICE_PER_DAY=10

Propósito: Establece el precio por día para servicios de recarga en el portal de autoservicio.

Campos:

  • REACT_APP_TOPUP_PRICE_PER_DAY - Precio diario para servicios de recarga (valor numérico)

Ejemplo: Si se establece en 10 y la moneda es USD, los clientes pagan $10 por día de servicio.

Nota: Este valor debe coincidir con la configuración de precios del backend. Consulta features_topup_recharge para detalles completos de configuración.

Aplicando Cambios de Configuración​

Backend (crm_config.yaml)​

  1. Edita OmniCRM-API/crm_config.yaml
  2. Guarda los cambios
  3. Reinicia el servicio del API:
cd OmniCRM-API
sudo systemctl restart omnicrm-api
# o
./restart_api.sh

Los cambios entran en efecto inmediatamente después del reinicio.

Frontend (.env)​

  1. Edita OmniCRM-UI/.env
  2. Guarda los cambios
  3. Reconstruye la UI:
cd OmniCRM-UI
npm run build
  1. Reinicia el servicio de la UI o el servidor web

Modo de Desarrollo:

Durante el desarrollo con npm start, reinicia el servidor de desarrollo para aplicar los cambios.

Mejores Prácticas de Configuración​

Seguridad​

  • Nunca comprometas secretos - Usa .gitignore para archivos de configuración con credenciales
  • Usa configuraciones específicas del entorno - Separa configuraciones de dev/staging/producción
  • Rota secretos regularmente - Actualiza secretos JWT, claves API periódicamente
  • Limita los permisos de las claves API - Asigna roles mínimos necesarios
  • Usa la lista blanca de IP con moderación - Prefiere claves API para mejor seguridad

Mantenimiento​

  • Documenta los cambios - Mantén un registro de cambios de las modificaciones de configuración
  • Haz copias de seguridad de las configuraciones - Almacena copias antes de cambios importantes
  • Prueba en staging - Verifica cambios de configuración antes del despliegue en producción
  • Control de versiones - Rastrear plantillas de configuración (sin secretos) en git

Rendimiento​

  • Usa base de datos local - Evita base de datos remota para mejor rendimiento
  • Configura caché - Habilita caché OCS si está disponible
  • Optimiza Grafana - Limita el número de paneles incrustados

Marca​

  • Coincide colores - Asegúrate de que los colores de la UI complementen tu logo
  • Prueba contraste - Verifica la legibilidad del texto en fondos coloreados
  • Pruebas móviles - Verifica la marca en dispositivos móviles
  • Colocación del logo - Coloca los logos de la empresa en OmniCRM-UI/public/resources/

Solución de Problemas​

Cambios no aplicados

  • Causa: Servicio no reiniciado o UI no reconstruida
  • Solución: Reinicia los servicios del API/UI después de cambios de configuración

Errores de sintaxis YAML

  • Causa: Formato YAML inválido (sangrías, comillas, etc.)
  • Solución: Valida YAML en línea o usa yamllint crm_config.yaml

Conexión a la base de datos fallida

  • Causa: Credenciales incorrectas o servidor inalcanzable
  • Solución: Verifica que la base de datos esté en funcionamiento, que las credenciales sean correctas

Pagos de Stripe no funcionan

  • Causa: Claves desajustadas entre backend y frontend
  • Solución: Asegúrate de que publishable_key coincida en ambos archivos

Correos electrónicos no enviados

  • Causa: Credenciales de Mailjet inválidas o IDs de plantilla
  • Solución: Verifica la clave/secret de la API de Mailjet, verifica que existan los IDs de plantilla

Documentación Relacionada​

  • administration_api_keys - Gestión de claves API
  • integrations_stripe - Configuración de pagos de Stripe
  • integrations_mailjet - Integración de correo electrónico
  • concepts_api - Autenticación de API
  • rbac - Control de acceso basado en roles