Notas sobre la Facturación de Servicios / Productos CRM

::: note ::: title Nota :::

Para una guía completa de extremo a extremo que cubra la definición de productos, aprovisionamiento, complementos y desaprovisionamiento con ejemplos detallados de Ansible y estrategia de precios, consulte la Guía Completa del Ciclo de Vida del Producto. :::

Descripción General de Productos y Servicios

Producto (Elemento del Menú):

Un Producto es como un plato específico en el menú de un restaurante, como un "Espagueti Carbonara."

Tiene una descripción clara, una lista de ingredientes (como pasta, crema, huevos, queso y tocino) y un precio.

En OmniCRM, un Producto contiene de manera similar los detalles de lo que está incluido --- características, especificaciones y precios.

A menudo, los clientes pueden querer modificaciones, como "sin cebollas" o "agregar queso extra" a su comida. Dentro de OmniCRM, esto corresponde a personalizar un servicio antes de su creación. El nivel de personalizaciones o modificaciones a un servicio depende de usted (el operador) definir.

En OmniCRM, los clientes o el personal pueden modificar un Producto para adaptarlo mejor a las necesidades de un cliente específico, como mejorar su velocidad de Internet o agregar características específicas. Esta personalización se refleja en el Servicio específico proporcionado.

Un producto es esencialmente una oferta de la que los clientes pueden elegir ordenar, similar a leer y seleccionar un plato del menú.

Catálogo de Productos (Menú del Restaurante):

El Catálogo de Productos es como todo el menú en un restaurante, que enumera todos los platos disponibles --- desde aperitivos hasta postres.

Es la colección completa de todo lo que el restaurante (o en su caso, el Proveedor de Servicios) tiene para ofrecer.

En el contexto empresarial, el Catálogo de Productos proporciona a los clientes todos los Productos disponibles, para que puedan elegir el que mejor se adapte a sus necesidades.

Servicio (Plato Preparado):

Cuando un cliente ordena un artículo del menú, el plato se prepara en la cocina. Esto es similar a crear un Servicio a partir de un Producto.

En OmniCRM, cuando un cliente selecciona un Producto, se crea una instancia de ese Producto y se entrega como un Servicio.

Se personaliza y prepara específicamente para ese cliente, al igual que una comida preparada para un comensal.

Por ejemplo, cuando alguien selecciona el "Plan de Internet Bronce" del Catálogo de Productos, el sistema de aprovisionamiento "cocina" una instancia de ese plan a partir de los ingredientes (direcciones IP, módems y puertos) --- es decir, activa el plan y lo entrega al cliente específico.

Productos Agrupados (Comidas Combinadas):

El Catálogo de Productos también puede ofrecer paquetes, como una comida combinada que incluye un aperitivo, un plato principal y un postre juntos a un precio especial.

En OmniCRM, los Productos agrupados combinan múltiples Productos individuales en un solo paquete conveniente --- como un "Paquete de Esenciales para el Hogar" que incluye servicios de Internet, cable y teléfono a una tarifa con descuento.

Una vez seleccionado, este paquete se convierte en múltiples Servicios adaptados para el cliente.

Definiciones de Producto

Un producto es una plantilla que se utiliza para crear un servicio / complemento / descuento / adición, etc.

Dentro de la definición incluimos:

• Información sobre el producto (características, inclusiones, Términos y Condiciones, duración del contrato, ícono, etc.) que se muestra al usuario del CRM (Cliente o Personal).

• La lógica empresarial sobre quién puede comprar el producto (Empresarial o Residencial), si depende de tener un servicio principal aprovisionado (como complementos móviles solo disponibles para clientes con un servicio móvil), si puede ser ordenado directamente por un cliente a través de autoatención o solo por un agente de servicio al cliente, y cuándo se puede comprar el producto (permitiendo que un producto esté disponible solo por un período de tiempo determinado).

• Cuando se deben incluir elementos de inventario (como módems o tarjetas SIM), estos se especifican como Lista de Elementos de Inventario, por ejemplo, el servicio a continuación requiere que se asigne una tarjeta SIM y un número de teléfono:

  ['SIM Card', 'Phone Number'] Estos se correlacionan con los Elementos de Inventario definidos en el CRM.

• Referencia a un Playbook de Ansible para aprovisionar el servicio Provisioning Play así como las variables a pasar a Ansible. Estas variables a pasar son mágicas, en el sentido de que pueden ser variables como service_id que están definidas por el producto al que estamos agregando, o pueden ser como ICCID y MSISDN donde hemos seleccionado elementos de inventario que se pasan al asignar el inventario. El agrupamiento se maneja en el playbook de aprovisionamiento para contener múltiples servicios, por ejemplo, un producto de internet en casa, TV y voz agrupados, puede aprovisionar un servicio para cada uno.

Categorías de Productos y Tipos de Servicio

Los productos utilizan dos campos de clasificación para ayudar a organizar y filtrar las ofertas:

Categorías de Productos

El campo category controla dónde se muestran los productos en la interfaz de usuario. Los valores comunes incluyen:

• standalone - Se muestra como una opción de servicio base al crear un nuevo servicio
• addon - Se muestra al agregar a un servicio existente
• bundle - Se muestra como una opción de servicio agrupado (aprovisionado como un complemento a servicios existentes)
• promo - Ofertas promocionales especiales

Estas categorías son puramente organizativas y no dictan lo que se aprovisiona. El comportamiento real de aprovisionamiento está determinado completamente por el playbook de Ansible referenciado en provisioning_play.

Por ejemplo: - Un producto standalone típicamente crea un nuevo objeto de servicio - Un producto addon o bundle típicamente se agrega a un servicio existente - Pero esto depende del implementador que escribe el playbook - podría crear múltiples objetos de servicio a partir de un complemento, o modificar servicios existentes a partir de un producto independiente si es necesario

La categoría simplemente controla el flujo de la interfaz de usuario y dónde los clientes/personal ven la opción del producto.

Tipos de Servicio

El campo service_type categoriza qué tipo de servicio se está proporcionando.

Estos están completamente definidos por el usuario, pero los valores comunes incluyen:

• mobile - Servicios de teléfono móvil con voz, SMS y datos
• fixed - Servicios de internet inalámbrico o por cable
• fixed-voice - Servicios de voz de línea fija (VoIP, línea terrestre)
• hotspot - Dispositivos de punto de acceso móvil o de alquiler
• dongle - Servicios de módem USB o dongle
• voice - Servicios solo de voz
• data - Servicios solo de datos

Al igual que las categorías, los tipos de servicio son personalizables según sus ofertas. Ayudan en:

• Filtrar qué complementos se aplican a qué servicios base
• Organizar productos en el portal del cliente
• Coincidir con los requisitos de inventario
• Determinar flujos de trabajo de aprovisionamiento

Ejemplo: Un cliente con un servicio mobile puede ver complementos móviles, mientras que un cliente con un servicio fixed ve complementos de línea fija.

Gestión de Productos

Los productos se gestionan a través de la página de Gestión de Productos, donde puede ver, buscar, filtrar y editar todos los productos disponibles.

{.align-center width="800px"}

Interfaz Modal de Producto

Hacer clic en cualquier producto abre una interfaz de pestañas mejorada que organiza todas las configuraciones del producto en grupos lógicos para una navegación y edición más fáciles.

{.align-center width="800px"}

El modal de gestión de productos cuenta con cinco pestañas organizadas:

1. 📋 Información Básica - Información central del producto (nombre, slug, categoría, ícono, características, términos)
2. 💰 Precios - Todos los campos relacionados con costos, incluidos costos recurrentes, costos de instalación y porcentaje de impuestos
3. ⚙️ Configuración - Configuraciones de renovación, tipos de clientes y dependencias
4. 🔧 Aprovisionamiento - Configuración del playbook de Ansible y requisitos de inventario
5. 📅 Disponibilidad - Rangos de fechas y marcas de tiempo del sistema

{.align-center width="800px"}

Organización de la Pestaña de Precios:

La pestaña de precios agrupa los campos de costo en secciones lógicas:

• Costos Recurrentes - Costos minoristas y mayoristas mensuales uno al lado del otro
• Costos de Instalación - Tarifas de activación únicas para minoristas y mayoristas
• Impuesto - Configuración del porcentaje de impuestos con cálculo automático

Características del Modo de Edición:

• Selector de Íconos - Buscar y seleccionar íconos de FontAwesome visualmente
• Selector de Elementos de Inventario - Seleccionar entre los tipos de elementos de inventario disponibles
• Selector de Fecha/Hora - Selección fácil de ventanas de disponibilidad
• Formato de Moneda - Prefijo automático $ para campos de costo
• Selectores Desplegables - Opciones predefinidas para categorías y campos booleanos

{.align-center width="800px"}

Selector de Íconos:

Al editar el campo de ícono, aparece una interfaz de selección de íconos buscable que le permite navegar y seleccionar visualmente entre miles de íconos de FontAwesome.

{.align-center width="800px"}

Características: * Buscar íconos por palabra clave (por ejemplo, "llave inglesa", "móvil", "wifi") * Previsualizar la apariencia del ícono en tiempo real * Muestra el nombre de la clase del ícono como referencia * Selección desplegable para acceso rápido

Pestaña de Configuración:

La pestaña de configuración organiza las configuraciones del comportamiento del producto en grupos lógicos.

{.align-center width="800px"}

Secciones de Configuración:

• Configuraciones de Renovación:
  • Auto Renovar - Comportamiento de renovación predeterminado (Solicitar/Sí/No)
  • Permitir Auto Renovar - Si los clientes pueden habilitar la auto-renovación
  • Días de Contrato - Duración mínima del contrato (por ejemplo, 30 para mensual, 365 para anual)
• Tipos de Clientes:
  • Residencial - Disponible para clientes consumidores
  • Empresarial - Disponible para clientes comerciales
• Dependencias:
  • Lista de Dependencias - IDs de productos o tipos de servicio requeridos antes de que se pueda agregar este producto
  • Usado para dependencias de complementos (por ejemplo, los complementos móviles requieren un servicio móvil activo)

Pestaña de Aprovisionamiento:

La pestaña de aprovisionamiento maneja la automatización de Ansible y los requisitos de inventario.

{.align-center width="800px"}

Campos de Aprovisionamiento:

• Play de Aprovisionamiento:
  • Nombre del playbook de Ansible (sin extensión .yaml)
  • Debe existir en el directorio OmniCRM-API/Provisioners/plays/
  • Se llama cuando se crea, actualiza o desaprovisiona el servicio
• Variables JSON de Aprovisionamiento:
  • Variables predeterminadas pasadas al playbook de Ansible como JSON
  • Pueden ser anuladas durante el aprovisionamiento
  • El playbook recibe estas más customer_id, product_id, service_id, access_token
• Lista de Elementos de Inventario:
  • Selector de múltiples elementos que muestra los tipos de elementos de inventario disponibles
  • Ejemplos: Tarjeta SIM, Número de Teléfono, Módem Router, Dirección IPv4
  • El cliente/personal selecciona elementos específicos del inventario disponible durante el pedido
  • Los IDs de inventario seleccionados se pasan al playbook con el tipo de inventario como nombre de variable

Pestaña de Disponibilidad:

La pestaña de disponibilidad controla cuándo se puede comprar el producto y muestra metadatos del sistema.

{.align-center width="800px"}

Configuraciones de Disponibilidad:

• Disponible Desde:
  • Fecha/hora cuando el producto se vuelve disponible para la compra
  • Dejar vacío para disponibilidad inmediata
  • Útil para pre-anunciar nuevos productos
• Disponible Hasta:
  • Fecha/hora cuando el producto ya no está disponible para la compra
  • Dejar vacío para disponibilidad indefinida
  • Perfecto para promociones por tiempo limitado o productos al final de su vida útil
• Metadatos del Sistema (Solo Lectura):
  • Creado - Marca de tiempo cuando se creó el producto por primera vez
  • Última Modificación - Marca de tiempo de la actualización más reciente
  • Mantenido automáticamente por el sistema

Acciones del Modal:

• Modo de Visualización:
  • Cerrar - Descartar modal
  • Clonar Producto - Crear una copia con el sufijo "_clone"
  • Editar Producto - Cambiar a modo de edición
• Modo de Edición/Creación:
  • Cancelar - Descartar cambios y cerrar
  • Guardar Cambios - Crear o actualizar producto (botón grande para énfasis)

Campos del Producto

El modelo de Producto contiene toda la información necesaria para definir una oferta y cómo debe ser aprovisionada. Estos campos se gestionan a través de la interfaz modal de gestión de productos descrita anteriormente.

Información Básica

• product_id - Identificador único asignado automáticamente por el sistema
• product_name - Nombre de visualización mostrado a los clientes y al personal en la interfaz de usuario
• product_slug - Identificador único utilizado en URLs y llamadas a la API (minúsculas, sin espacios, usar guiones)
• category - Controla dónde aparece este producto en la interfaz de usuario:
  • standalone - Se muestra como una opción de servicio base al crear un nuevo servicio
  • addon - Se muestra al agregar a un servicio existente
  • bundle - Se muestra como una opción de servicio agrupado
  • promo - Ofertas promocionales especiales
• service_type - Tipo de servicio que se está proporcionando (por ejemplo, móvil, fijo, voz fija, hotspot, dongle, voz, datos). Se utiliza para filtrar qué complementos se aplican a qué servicios.
• comment - Notas internas sobre el producto solo para referencia del personal (no se muestra a los clientes)
• icon - Clase de ícono de FontAwesome mostrada en la interfaz de usuario (por ejemplo, fa-solid fa-sim-card)

Campos de Precios

• retail_cost - Cargo recurrente mensual facturado al cliente (establecer en 0 para compras únicas o productos prepagos)
• wholesale_cost - Su costo mensual por proporcionar este servicio (utilizado para cálculos de margen)
• retail_setup_cost - Tarifa de activación o configuración única cobrada al cliente
• wholesale_setup_cost - Su costo único por configurar el servicio
• tax_percentage - Porcentaje de impuestos aplicado a este producto (por ejemplo, 10 para 10%, 12.5 para 12.5%). Establecer en 0 para productos exentos de impuestos. Esta tasa impositiva se aplica automáticamente a las transacciones creadas a partir de este producto.

{.align-center width="800px"}

Aplicación de Impuestos:

Cuando se crea una transacción a partir de este producto, el porcentaje de impuestos se copia automáticamente a la transacción y se calcula el monto del impuesto. Por ejemplo:

• Producto con 10% de impuestos, $50.00 costo minorista → Transacción tiene $5.00 de impuestos
• Producto con 0% de impuestos (exento de impuestos) → Transacción tiene $0.00 de impuestos
• Anulación manual de transacción → El personal puede cambiar el porcentaje de impuestos por transacción

Visibilidad y Acceso del Cliente

• enabled - Si este producto está activo y disponible para la compra (establecer en falso para ocultar sin eliminar)
• residential - Si los clientes residenciales (consumidores) pueden comprar este producto
• business - Si los clientes comerciales (empresariales) pueden comprar este producto
• customer_can_purchase - Si los clientes pueden auto-comprar a través del portal (verdadero) o si solo el personal puede agregarlo (falso)
• available_from - Fecha/hora cuando este producto se vuelve disponible para la compra (opcional)
• available_until - Fecha/hora cuando este producto ya no está disponible para la compra (opcional, útil para ofertas por tiempo limitado)

Contrato y Renovación

• contract_days - Duración mínima del contrato en días (por ejemplo, 30 para mensual, 365 para anual, 0 para sin contrato mínimo)
• auto_renew - Comportamiento de renovación predeterminado:
  • prompt - Pregunta al cliente cada vez si desea renovar
  • true - Renueva automáticamente sin preguntar
  • false - Requiere renovación manual
• allow_auto_renew - Si los clientes pueden habilitar la renovación automática (establecer en falso para compras únicas)

Contenido Visible para el Cliente

• terms - Términos y condiciones mostrados a los clientes antes de la compra (incluir limitaciones, reglas de caducidad, condiciones de uso)
• features_list - Lista de características e inclusiones mostradas a los clientes (formato de lista de Python: ['Feature 1', 'Feature 2'])

Configuración de Aprovisionamiento

• provisioning_play - Nombre del playbook de Ansible que aprovisiona este servicio (sin extensión .yaml). Debe existir en el directorio OmniCRM-API/Provisioners/plays/.
• provisioning_json_vars - Variables predeterminadas pasadas al playbook de Ansible como JSON. Estas pueden ser anuladas al aprovisionar. El playbook recibe estas junto con customer_id, product_id, service_id y access_token.
• inventory_items_list - Lista de elementos de inventario requeridos para este producto (por ejemplo, ['SIM Card', 'Mobile Number']). Cuando un cliente ordena, se le pedirá que seleccione elementos específicos del inventario disponible. Los IDs de inventario seleccionados se pasan al playbook con el tipo de inventario como nombre de variable.
• relies_on_list - Lista de IDs de productos o tipos de servicio que deben existir antes de que se pueda agregar este producto. Se utiliza para dependencias de complementos (por ejemplo, los complementos móviles requieren un servicio móvil activo).

Metadatos del Sistema

• created - Marca de tiempo cuando se creó el producto (establecido automáticamente)
• last_modified - Marca de tiempo cuando se actualizó por última vez el producto (actualizado automáticamente)

Ejemplos de Definiciones de Productos

Producto Independiente (SIM Móvil)

{
  "product_id": 1,
  "product_slug": "Mobile-SIM",
  "product_name": "Mobile SIM Only",
  "category": "standalone",
  "service_type": "mobile",
  "provisioning_play": "play_psim_only",
  "provisioning_json_vars": "{\"iccid\": \"\", \"msisdn\": \"\"}",
  "inventory_items_list": "['SIM Card', 'Mobile Number']",
  "retail_cost": 0,
  "retail_setup_cost": 0,
  "wholesale_cost": 3,
  "wholesale_setup_cost": 1,
  "contract_days": 0,
  "residential": true,
  "business": true,
  "enabled": true,
  "customer_can_purchase": true,
  "icon": "fa-solid fa-sim-card",
  "features_list": "['Australian Phone Number (04xxx)', 'Fastest speeds', 'Best coverage', 'Roaming on the Mainland']",
  "terms": "Must be activated within 6 months. All credit lost if service is not used for 12 months.",
  "comment": "Physical SIM card for use with Mobile Phones"
}

Este producto independiente requiere dos elementos de inventario (Tarjeta SIM y Número Móvil) y crea un nuevo servicio cuando se aprovisiona.

Producto Complementario (Plan de Datos Mensual)

{
  "product_slug": "norfone-mobile-prepaid-mini",
  "product_name": "Norfone Mini Plan",
  "category": "addon",
  "service_type": "mobile",
  "provisioning_play": "play_topup_charge_then_action",
  "provisioning_json_vars": "",
  "inventory_items_list": "[]",
  "retail_cost": 30,
  "retail_setup_cost": 0,
  "wholesale_cost": 5.84,
  "contract_days": 30,
  "residential": true,
  "business": false,
  "enabled": true,
  "customer_can_purchase": true,
  "auto_renew": "prompt",
  "icon": "fa-solid fa-sim-card",
  "features_list": "['8GB of Ultra fast data', 'Unlimited Calls & Texts to Norfone users', '100 Minutes of Talk to Australia', '100 SMS to Australia', '30 Day Expiry']",
  "terms": "Credit expires after 30 days. Once data, voice or sms is used up, you will need to top up to continue using the service.",
  "comment": "Our smallest plan for light users"
}

Este producto complementario no requiere inventario y se aplica a un servicio existente. Cobra al cliente y agrega créditos/saldos a su servicio.

Producto Agrupado (Paquete para Personas Mayores)

{
  "product_slug": "Bundle-Seniors",
  "product_name": "Seniors Bundle",
  "category": "bundle",
  "service_type": "fixed",
  "provisioning_play": "play_seniors_package",
  "provisioning_json_vars": "{\"IPTV_Service_ID\": \"SeniorBundle\"}",
  "inventory_items_list": "['Modem Router']",
  "retail_cost": 30,
  "retail_setup_cost": 0,
  "wholesale_cost": 10,
  "wholesale_setup_cost": 11,
  "contract_days": 180,
  "residential": true,
  "business": false,
  "enabled": true,
  "icon": "fa-solid fa-person-walking-with-cane",
  "features_list": "['20Mbps Download', '5Mbps Upload', 'Unlimited Data', 'Home Voice', 'TV: Extra +£5 per month', '£60 Installation Fee']",
  "terms": "6 Month Contract, must show senior citizen's card to qualify",
  "comment": "20Mbps/2Mbps GPON Service + IPTV + Phone"
}

Este producto agrupado aprovisiona múltiples servicios (Internet + IPTV + Teléfono) utilizando un solo playbook. Requiere un elemento de inventario (Módem Router).

Producto Complementario (Recarga Simple)

{
  "product_slug": "Mobile-Topup-5",
  "product_name": "PAYG £5 Topup",
  "category": "addon",
  "service_type": "mobile",
  "provisioning_play": "play_topup_monetary",
  "provisioning_json_vars": "{\"service_id\": \"\"}",
  "inventory_items_list": "[]",
  "retail_cost": 5,
  "retail_setup_cost": 0,
  "wholesale_cost": 0,
  "contract_days": 0,
  "residential": true,
  "business": false,
  "enabled": true,
  "customer_can_purchase": true,
  "icon": "fa-solid fa-coins",
  "features_list": "['£5 credit', 'Valid for 180 days']",
  "terms": "Valid for 180 days or until all credit is used. See our website for full rates",
  "comment": "£5 to use for Calls, SMS & Data"
}

Este complemento simplemente agrega crédito monetario a un servicio existente. No se requiere inventario, y utiliza service_id para identificar qué servicio recargar.

Cómo se Pasan las Variables a Ansible

Entender cómo fluyen las variables desde la definición del producto a través de la API hasta el playbook de Ansible es crítico para escribir playbooks de aprovisionamiento efectivos.

Fuentes de Variables y Fusión

Cuando se crea un trabajo de aprovisionamiento, las variables provienen de múltiples fuentes y se fusionan en este orden (las fuentes posteriores anulan a las anteriores):

1. Variables de provisioning_json_vars del Producto - Variables predeterminadas de la definición del producto
2. Cuerpo de la Solicitud - Variables pasadas en la llamada a la API (pueden anular los valores predeterminados del producto)
3. Variables Agregadas por el Sistema - Agregadas automáticamente por el sistema de aprovisionamiento
4. Selecciones de Inventario - IDs de los elementos de inventario seleccionados (si inventory_items_list no está vacío)

Proceso de Fusión de Variables

El sistema fusiona variables de todas las fuentes, con las fuentes posteriores anulando a las anteriores. Esto permite una personalización flexible en el momento del aprovisionamiento.

Por ejemplo, si su producto tiene:

"provisioning_json_vars": "{\"monthly_cost\": 50, \"data_gb\": 100}"

Y su solicitud de API incluye:

{
  "product_id": 10,
  "customer_id": 456,
  "monthly_cost": 45,
  "custom_param": "value"
}

Las variables finales extra_vars pasadas a Ansible serán:

{
    "monthly_cost": 45,        # Anulado desde la solicitud
    "data_gb": 100,            # Desde provisioning_json_vars
    "product_id": 10,          # Desde la solicitud
    "customer_id": 456,        # Desde la solicitud
    "custom_param": "value",   # Desde la solicitud
    "access_token": "eyJ..."   # Agregado por el sistema
}

Variables Agregadas por el Sistema

El sistema de aprovisionamiento agrega automáticamente:

• access_token - Token JWT para autenticar llamadas a la API de vuelta al CRM (desde g.access_token para autenticación IP/API key, o generado desde refresh_token para autenticación de usuario)
• initiating_user - El ID de usuario que activó el aprovisionamiento (o el primer administrador para sistemas automatizados)
• Cualquier campo del cuerpo de la solicitud (product_id, customer_id, service_id, etc.)

Variables de Inventario

Cuando un producto requiere elementos de inventario (por ejemplo, inventory_items_list: "['SIM Card', 'Mobile Number']"), el proceso funciona de la siguiente manera:

1. Interfaz UI/API solicita selección - El usuario selecciona elementos de inventario específicos del stock disponible
2. IDs de Inventario se agregan a las variables - Los IDs de los elementos de inventario seleccionados se agregan con el tipo de inventario como nombre de variable
3. El playbook accede a los IDs de inventario - El playbook de aprovisionamiento puede recuperar los detalles completos del inventario desde la API del CRM

Por ejemplo, si un usuario selecciona: - Tarjeta SIM con inventory_id: 789 - Número Móvil con inventory_id: 101

Las variables pasadas al playbook incluyen: - SIM Card: 789 - Mobile Number: 101

El playbook puede entonces usar estos IDs para obtener los registros completos de inventario (ICCID, IMSI, MSISDN, etc.) de la API del CRM y usar esa información para aprovisionar el servicio en el equipo de red.

Cómo Ansible Recibe Variables

El sistema de aprovisionamiento pasa todas las variables fusionadas al playbook de Ansible como extravars. Dentro del playbook, estas variables están disponibles a través del sistema de variables estándar de Ansible y pueden ser utilizadas en tareas.

Las variables pueden ser referenciadas directamente en las tareas del playbook utilizando la sintaxis {{ variable_name }}. Por ejemplo, {{ product_id }}, {{ customer_id }}, {{ monthly_cost }}, etc.

Variables Pasadas a Productos Complementarios

Cuando se aprovisiona un producto complementario, el sistema pasa automáticamente:

• product_id - El ID del producto complementario que se está aprovisionando
• customer_id - El cliente que posee el servicio
• service_id - El ID del servicio al que se está agregando este complemento (crítico para complementos)
• access_token - Token de autenticación para llamadas a la API
• Cualquier variable de provisioning_json_vars
• Cualquier variable adicional de la solicitud de API

Ejemplo de Flujo de Aprovisionamiento de Complemento

Cuando un cliente agrega el complemento "Recarga de £5" a su servicio móvil (service_id: 123), el playbook recibe variables que incluyen:

• product_id: 45 (el producto de recarga)
• customer_id: 456 (el cliente)
• service_id: 123 (el servicio al que agregar crédito)
• access_token: Token de autenticación
• Más cualquier variable de provisioning_json_vars del producto

El playbook luego utiliza estas variables para:

1. Obtener detalles del servicio desde la API del CRM utilizando el service_id
2. Extraer el UUID del servicio y otra información del registro del servicio
3. Agregar crédito al sistema de facturación (OCS) utilizando el UUID del servicio
4. Registrar la transacción en el CRM para fines de facturación

Este flujo permite que el complemento identifique exactamente qué servicio modificar y aplicar los cambios apropiadamente.

Diferencia entre Variables de Productos Independientes y Complementarios

Productos Independientes reciben:

• product_id - El producto que se está aprovisionando
• customer_id - El cliente que ordena el servicio
• IDs de elementos de inventario (por ejemplo, SIM Card, Mobile Number) si el producto los requiere
• access_token - Para autenticación de API

Productos Complementarios reciben:

• product_id - El producto complementario que se está aprovisionando
• customer_id - El cliente que posee el servicio
• service_id - El ID del servicio existente a modificar (esta es la clave de diferencia)
• access_token - Para autenticación de API

La clave diferencia es service_id - esto le dice al playbook qué servicio existente modificar o agregar.

Productos Agrupados

Los productos agrupados se aprovisionan como complementos, pero su playbook puede crear múltiples registros de servicio. Reciben las mismas variables que los complementos, incluyendo:

• product_id - El producto agrupado
• customer_id - El cliente
• service_id - Servicio principal (si corresponde)
• IDs de elementos de inventario (por ejemplo, Modem Router) si se requieren
• access_token - Para autenticación de API

El playbook de agrupación (por ejemplo, play_seniors_package) luego crea múltiples servicios relacionados (Internet, IPTV, Teléfono) y los vincula juntos.

Servicios

Un servicio es una instancia de un producto que pertenece a un cliente, por la que se le factura.

Es esencialmente un enlace a una cuenta de OCS (Sistema de Facturación en Línea) que maneja la generación de cargos y los saldos y usos reales de la cuenta. El OCS es impulsado por CGRateS y gestiona saldos monetarios, saldos unitarios (datos, voz, SMS), Planes de Acción para la auto-renovación y ThresholdS para límites de gasto.

Agregar un Servicio: Selección y Filtrado de Productos

Al agregar un servicio a un cliente (ya sea un nuevo servicio independiente o un complemento a un servicio existente), el sistema muestra los productos disponibles en una interfaz de carrusel. Los productos mostrados se filtran según varios criterios:

Filtrado de Productos para Servicios Independientes

Al crear un nuevo servicio para un cliente, la interfaz de usuario muestra productos filtrados por:

1. Tipo de Cliente - Los productos se categorizan como:
   • Individual (Residencial): Productos donde residential = true o business = false
   • Empresarial: Productos donde business = true
2. Categoría - Los productos se separan en:
   • Planes de Servicio: Productos con category = standalone o bundle
   • Complementos: Productos con category = addon (mostrados en carrusel separado)
3. Disponibilidad - Los productos solo se muestran si:
   • enabled = true - El producto está activo y no está deshabilitado
   • La fecha actual está entre available_from y available_until - El producto está dentro de su ventana de disponibilidad
   • customer_can_purchase = true (si el cliente está auto-comprando) - El producto permite la compra directa por parte del cliente

::: note ::: title Nota :::

Filtrado a Nivel de API: La API filtra automáticamente los productos por estado habilitado y fechas de disponibilidad en dos niveles:

• Puntos finales de Compra/Selección (/crm/product/) - Usado por el modal de Complementos y la Lista de Planes para la selección de productos. Filtra automáticamente para mostrar SOLO productos habilitados dentro de su rango de fechas de disponibilidad. Esto asegura que los clientes y el personal solo puedan seleccionar productos que están actualmente disponibles para la compra.
• Puntos finales de Gestión (/crm/product/paginated) - Usado por la página de Gestión de Productos. Muestra TODOS los productos, incluidos los deshabilitados y fuera de las fechas de disponibilidad, permitiendo a los administradores gestionar el catálogo completo de productos, incluidos los productos inactivos.

Pase include_disabled=true al punto final base del producto para omitir el filtrado (solo para uso administrativo). :::

La interfaz de usuario muestra carruseles separados para:

• Planes de Servicio Individuales - Productos residenciales para clientes consumidores
• Planes de Servicio Empresariales - Productos comerciales para clientes empresariales
• Complementos Individuales - Paquetes de complementos residenciales
• Complementos Empresariales - Paquetes de complementos comerciales

Filtrado de Productos para Servicios Complementarios

Al agregar un complemento a un servicio existente, se aplica un filtrado adicional:

1. Coincidencia de Tipo de Servicio - Solo se muestran complementos con service_type coincidente:
   • Si el servicio existente tiene service_type = "mobile", solo se muestran complementos con service_type = "mobile"
   • Esto asegura que los clientes móviles solo vean complementos móviles, los clientes de internet solo vean complementos de internet, etc.
2. Verificación de Dependencias - Si un complemento tiene una relies_on_list:
   • El sistema verifica si el cliente tiene los productos/servicios requeridos
   • Solo se muestran los complementos cuyas dependencias están satisfechas
3. Filtro de Mismo Tipo de Cliente - Los complementos aún se filtran por residential vs business para coincidir con el tipo de cliente

Ejemplo de Escenario de Filtrado

Para un cliente empresarial con un servicio móvil existente (service_type = "mobile"):

• Productos Independientes Mostrados: Todos los productos independientes/agrupados empresariales (business = true, category != "addon")
• Productos Complementarios Mostrados: Solo complementos móviles empresariales (business = true, category = "addon", service_type = "mobile")
• Productos Ocultos: Productos residenciales, complementos para otros tipos de servicio (internet, voz, etc.), productos deshabilitados

Campos de Servicio

El modelo de Servicio contiene campos que rastrean la instancia de servicio aprovisionada y su relación con el cliente, producto y sistema de facturación.

Información Básica del Servicio

• service_id - Identificador único asignado automáticamente por el sistema (solo lectura)
• customer_id - Enlace al cliente que posee este servicio (solo lectura después de la creación)
• product_id - Enlace al producto del cual se creó este servicio (solo lectura después de la creación)
• service_name - Nombre de visualización mostrado a los clientes (editable)
• service_type - Tipo de servicio: móvil, internet, voip, iptv, paquete, etc. (editable)
• service_uuid - Identificador único utilizado en OCS/CGRateS para facturación (solo lectura, auto-generado)
• icon - Clase de ícono de FontAwesome para mostrar en el portal de autoatención (editable)

Estado y Fechas del Servicio

• service_status - Estado actual: Activo, Inactivo, Suspendido, etc. (editable)
• service_provisioned_date - Cuando se aprovisionó por primera vez el servicio (auto-establecido, solo lectura)
• service_active_date - Cuando el servicio se volvió activo (editable)
• service_deactivate_date - Cuando el servicio caduca o será desactivado (editable)
• contract_end_date - Fecha de finalización del compromiso del contrato (editable)

Facturación y Precios

• retail_cost - Cargo recurrente mensual al cliente (editable)
• wholesale_cost - Su costo por proporcionar el servicio (editable)
• service_billed - Si este servicio aparece en las facturas (editable, predeterminado: verdadero)
• service_taxable - Si se aplican impuestos a este servicio (editable, predeterminado: verdadero)
• invoiced - Si el servicio ha sido facturado (auto-establecido por el sistema de facturación)
• promo_code - Código promocional utilizado cuando se creó el servicio (editable)

Visibilidad del Cliente

• service_visible_to_customer - Si el cliente puede ver este servicio en el portal de autoatención (editable, predeterminado: verdadero)
• service_usage_visible_to_customer - Si el cliente puede ver detalles de uso/saldo (editable, predeterminado: verdadero)

Configuración de Aprovisionamiento

• provisioning_play - Playbook de Ansible utilizado para aprovisionar este servicio (heredado del producto, solo lectura)
• provisioning_json_vars - Variables pasadas al playbook de aprovisionamiento (heredadas del producto, solo lectura)
• deprovisioning_play - Playbook de Ansible a ejecutar cuando se desaprovisiona el servicio (solo lectura)
• deprovisioning_json_vars - Variables para el playbook de desaprovisionamiento (solo lectura)

Relaciones de Servicio

• bundled_parent - Si este servicio es parte de un paquete, el service_id del servicio principal (solo lectura)
• site_id - Enlace al sitio/ubicación física donde se entrega el servicio (editable)

Notas y Metadatos

• service_notes - Notas internas sobre el servicio para referencia del personal (editable)
• created - Marca de tiempo cuando se creó el servicio (auto-establecido, solo lectura)
• last_modified - Marca de tiempo de la última actualización (auto-actualizado, solo lectura)

Campos Editables vs Solo Lectura

Editables a través de API/UI:

Los servicios se pueden actualizar a través de PATCH /crm/service/{service_id} con estos campos:

• service_name, service_type, service_status
• service_notes
• retail_cost, wholesale_cost
• service_billed, service_taxable
• service_visible_to_customer, service_usage_visible_to_customer
• service_active_date, service_deactivate_date, contract_end_date
• icon, promo_code, site_id

Solo Lectura (Auto-Establecidos):

Estos campos no pueden ser modificados directamente después de la creación:

• service_id, customer_id, product_id
• service_uuid (generado durante el aprovisionamiento)
• service_provisioned_date
• provisioning_play, provisioning_json_vars
• deprovisioning_play, deprovisioning_json_vars
• bundled_parent
• invoiced (gestionado por el sistema de facturación)
• created, last_modified (gestionados automáticamente)

Aprovisionamiento de Productos en Servicios

El proceso de aprovisionamiento convierte un Producto (plantilla) en un Servicio (instancia específica del cliente) a través de una serie de pasos coordinados que involucran la interfaz web, la API y los playbooks de Ansible.

Flujo de Aprovisionamiento de Alto Nivel

1. Configuración Pre-Aprovisionamiento - Producto creado en la API con configuración de aprovisionamiento, y los playbooks de Ansible correspondientes escritos y probados
2. Selección de Servicio - Desde la Página del Cliente, el personal o el cliente selecciona "Agregar Servicio"
3. Filtrado de Productos - Productos mostrados filtrados según:
   • Tipo de cliente (residencial/empresarial)
   • Servicios existentes (para dependencias de complementos en relies_on_list)
   • Fechas de disponibilidad (available_from/available_until)
   • Banderas enabled y customer_can_purchase
4. Personalización - Opción para anular variables de aprovisionamiento (para ajustes de precios, configuraciones personalizadas, etc.)
5. Selección de Inventario - Si el producto requiere inventario (inventory_items_list no está vacío), el usuario selecciona elementos específicos (por ejemplo, qué tarjeta SIM, qué número de teléfono)
6. Inicio de Aprovisionamiento - Cuando se hace clic en el botón "Aprovisionar", la API crea un trabajo de aprovisionamiento

Flujo Detallado de Integración de API y Ansible

Cuando se aprovisiona un servicio, ocurre la siguiente secuencia:

Paso 1: Creación del Trabajo de Aprovisionamiento (/routes/service.py)

La API recibe la solicitud de aprovisionamiento y llama a create_provisioning_job() desde services/provisioning_service.py con:

• provisioning_play - Nombre del playbook de Ansible (por ejemplo, play_psim_only)
• provisioning_json_vars - Cadena JSON de variables del producto o anuladas por la solicitud
• customer_id - ID del cliente que ordena el servicio
• product_id - ID del producto que se está aprovisionando
• service_id - (Opcional) ID del servicio existente para complementos
• Selecciones de Inventario - IDs de los elementos de inventario seleccionados

Paso 2: Ensamblaje de Variables (services/provisioning_service.py)

El servicio de aprovisionamiento fusiona variables de múltiples fuentes en este orden:

1. provisioning_json_vars del Producto (valores predeterminados de la definición del producto)
2. Parámetros del cuerpo de la solicitud (pueden anular los valores predeterminados del producto)
3. Variables agregadas por el sistema:
   • access_token - Token JWT para autenticación de API de vuelta al CRM
   • initiating_user - ID de usuario que activó el aprovisionamiento
   • customer_id, product_id, service_id
4. Selecciones de Inventario - Agregadas como pares {inventory_type: inventory_id}

Ejemplo de variables fusionadas:

{
    "customer_id": 123,
    "product_id": 456,
    "service_id": 789,          # Solo para complementos
    "SIM Card": 1001,           # Desde la selección de inventario
    "Mobile Number": 1002,      # Desde la selección de inventario
    "monthly_cost": 30,         # Desde provisioning_json_vars
    "data_gb": 50,              # Desde provisioning_json_vars
    "access_token": "eyJ...",   # Agregado por el sistema para callbacks de API
    "initiating_user": 5        # Agregado por el sistema
}

Paso 3: Creación del Registro de Aprovisionamiento (models.py - Modelo de Aprovisionamiento)

Se crea un registro de Provision en la base de datos con:

• provision_id - Identificador único para seguimiento
• provisioning_play - Nombre del archivo del playbook
• provisioning_json_vars - Variables fusionadas como cadena JSON
• task_count - Número de tareas en el playbook (extraído de YAML)
• provisioning_status - Código de estado (inicialmente establecido en 1 = en ejecución, luego actualizado a 0 = éxito, 2 = fallido, o puede permanecer en 1 si aún está en progreso)
• product_id, customer_id, service_id - Referencias de contexto

Paso 4: Ejecución del Playbook en Segundo Plano (Provisioners/playbook_runner_v2.py)

La API genera un hilo en segundo plano que:

1. Carga el YAML del playbook desde OmniCRM-API/Provisioners/plays/{playbook_name}.yaml
2. Llama a ansible_runner.run() con:
   • playbook - Ruta al archivo YAML cargado
   • extravars - Todas las variables fusionadas (pasadas a Ansible)
   • inventory - Establecido en 'localhost,' (ejecución local)
   • event_handler - Controlador personalizado para capturar eventos de ejecución de tareas
3. Monitorea la ejecución del playbook en tiempo real

Paso 5: Captura de Eventos y Registro (ProvisioningEventHandler)

A medida que se ejecuta cada tarea de Ansible, se capturan eventos y se almacenan como registros de Provision_Event:

• event_name - Nombre de la tarea del playbook
• event_number - Número de secuencia
• provisioning_status - Código de estado que indica el resultado de la tarea:
  • 0 = Éxito - La tarea se completó con éxito
  • 1 = En ejecución - La tarea se está ejecutando actualmente
  • 2 = Fallido - Fallo crítico que detiene el aprovisionamiento
  • 3 = Fallido (ignorado) - La tarea falló pero se ignoraron los errores (ignore_errors: true en el playbook)
• provisioning_result_json - Resultados de la tarea con datos sensibles redactados

El controlador de eventos elimina automáticamente contraseñas, claves, secretos y otros datos sensibles de los registros.

Paso 6: Ejecución del Playbook de Ansible (Provisioners/plays/*.yaml)

El playbook de Ansible se ejecuta localmente y generalmente realiza estas acciones:

a. Obtener Definición del Producto - Solicitud GET a /crm/product/product_id/{{ product_id }} utilizando {{ access_token }}

b. Obtener Información del Cliente - Solicitud GET a /crm/customer/customer_id/{{ customer_id }}

c. Procesar Elementos de Inventario (si es necesario) - Solicitud GET a /crm/inventory/inventory_id/{{ inventory_id }} para cada elemento seleccionado para recuperar detalles completos (ICCID, MSISDN, números de serie, etc.)

d. Configurar Sistemas Externos - Realizar llamadas a la API a:

• HSS (Servidor de Suscriptores en el Hogar) para aprovisionamiento de suscriptores
• IMS (Subsistema Multimedia IP) para registro de voz
• CGRateS/OCS para creación de cuentas, configuración de cargos, planes tarifarios
• Servidores ENUM para mapeo de números de teléfono
• Equipos de red (enrutadores, conmutadores, etc.)

e. Agregar Costos de Instalación (si corresponde) - POST a /crm/transaction/ para registrar cargos únicos

f. Cobrar al Cliente - POST a OCS/CGRateS para cobrar retail_setup_cost si está configurado

g. Crear Cuenta OCS - POST a OCS/CGRateS para crear una cuenta de facturación con UUID

h. Configurar Cargos Recurrentes - Crear Acciones y Planes de Acción en OCS/CGRateS para cargos recurrentes mensuales

i. Crear Registro de Servicio - PUT/POST a /crm/service/ para crear el registro del servicio en el CRM:

{
  "customer_id": 123,
  "product_id": 456,
  "service_name": "Mobile SIM - 0412345678",
  "service_uuid": "generated-uuid-for-ocs",
  "service_status": "Active",
  "service_type": "mobile",
  "retail_cost": 30,
  "wholesale_cost": 5,
  "provisioning_play": "play_psim_only",
  "provisioning_json_vars": "{...}"
}

j. Asignar Inventario - PATCH a /crm/inventory/inventory_id/{{ inventory_id }} para marcar el inventario como "Asignado" al servicio

k. Enviar Notificaciones (opcional) - Correo electrónico o SMS al cliente con detalles del servicio

Paso 7: Finalización y Actualización de Estado

Cuando el playbook se completa:

• Éxito: Provision.provisioning_status actualizado a 0 (Éxito)
• Fallo Crítico: Provision.provisioning_status actualizado a 2 (Fallido), y se envía un correo electrónico de fallo a crm_config.provisioning.failure_list
• Fallos No Críticos: Tareas que fallan con ignore_errors: true se marcan con estado 3 (Fallido pero ignorado) y no detienen el aprovisionamiento

El servicio aprovisionado ahora es visible en el CRM y está activo para el cliente (si el aprovisionamiento tuvo éxito).

Diferencias Clave: Aprovisionamiento de Productos Independientes vs Complementarios vs Agrupados

Productos Independientes (category: standalone):

• Reciben customer_id y product_id
• Típicamente requieren elementos de inventario (tarjetas SIM, números de teléfono, módems)
• Crean un registro de servicio nuevo a través de la API PUT /crm/service/
• Aprovisionan nuevos recursos en sistemas externos (HSS, OCS, equipos de red)
• Ejemplo: Activación de nueva SIM móvil, nueva conexión a internet

Productos Complementarios (category: addon):

• Reciben customer_id, product_id y service_id (servicio existente a modificar)
• Típicamente NO requieren inventario (o inventario mínimo)
• Modifican un servicio existente o agregan cargos a una cuenta OCS existente
• Pueden ejecutar acciones en OCS (agregar paquete de datos, agregar crédito, habilitar característica)
• No crean nuevos registros de servicio (o crean registros de servicio secundarios vinculados al principal)
• Ejemplo: Recarga de plan de datos mensual, paquete de roaming internacional, crédito extra

Productos Agrupados (category: bundle):

• Similar a los complementos en términos de variables recibidas
• Pueden requerir algunos elementos de inventario (por ejemplo, módem para paquete de hogar)
• Crean múltiples registros de servicio relacionados (Internet + TV + Teléfono)
• Aprovisionan múltiples recursos a través de diferentes sistemas
• Vinculan servicios juntos en el CRM para facturación/gestión unificada
• Ejemplo: Paquete de hogar (Internet + IPTV + teléfono VoIP)

Requisitos del Playbook de Aprovisionamiento

Para que un playbook funcione correctamente, debe:

1. Estar ubicado en OmniCRM-API/Provisioners/plays/{playbook_name}.yaml
2. Aceptar variables a través de extravars de Ansible (accedido como {{ variable_name }})
3. Autenticar llamadas a la API utilizando el encabezado Authorization: Bearer {{ access_token }}
4. Manejar fallos de manera adecuada utilizando bloques rescue y ignore_errors donde sea apropiado
5. Crear registro de servicio para productos independientes, o modificar el servicio existente para complementos
6. Asignar inventario si se seleccionaron elementos de inventario
7. Devolver mensajes de error significativos a través del módulo fail cuando ocurran errores críticos

Variables Comunes Disponibles en Playbooks

Cada playbook recibe estas variables:

• customer_id - Entero, cliente que ordena el servicio
• product_id - Entero, producto que se está aprovisionando
• service_id - Entero (solo complementos/agrupados), servicio existente a modificar
• access_token - Cadena, token JWT para autenticación de API de CRM
• initiating_user - Entero, usuario que activó el aprovisionamiento
• Más cualquier ID de elemento de inventario: {{ inventory_type }}: inventory_id
• Más cualquier variable de provisioning_json_vars
• Más cualquier variable pasada en la solicitud de aprovisionamiento

Los playbooks pueden usar estos para:

• Obtener detalles completos del producto: GET /crm/product/product_id/{{ product_id }}
• Obtener detalles del cliente: GET /crm/customer/customer_id/{{ customer_id }}
• Obtener detalles del inventario: GET /crm/inventory/inventory_id/{{ SIM_Card }}
• Crear transacciones: POST /crm/transaction/
• Crear servicios: PUT /crm/service/
• Actualizar servicios: PATCH /crm/service/{{ service_id }}
• Asignar inventario: PATCH /crm/inventory/inventory_id/{{ inventory_id }}

Ejemplo: Flujo de Playbook de Complemento Simple

Para un complemento de recarga de datos móviles:

1. El playbook recibe: customer_id, product_id, service_id, access_token
2. Obtener detalles del servicio: GET /crm/service/{{ service_id }} para obtener service_uuid
3. Obtener detalles del producto: GET /crm/product/product_id/{{ product_id }} para obtener precios y cantidad de datos
4. Cobrar al cliente en OCS: POST a CGRateS para deducir retail_cost del saldo
5. Agregar crédito de datos en OCS: POST a CGRateS para agregar saldo de datos con caducidad
6. Registrar transacción en CRM: POST /crm/transaction/ con detalles del cargo
7. Completar con éxito

Todo el proceso se rastrea en las tablas Provision y Provision_Event para fines de depuración y auditoría.

Participación de OCS

OCS (Sistema de Facturación en Línea), implementado a través de CGRateS, maneja todos los cargos en tiempo real y el seguimiento de uso para los servicios. El registro de servicio del CRM actúa como un puntero a la cuenta de OCS, que gestiona:

• Cargos recurrentes - Tarifas mensuales, alquiler de DID, cargos de suscripción
• Cargos basados en uso - Llamadas de voz por minuto, datos por MB, cargos por SMS
• Gestión de saldos - Saldos monetarios (crédito prepago) y saldos unitarios (GB de datos, minutos de voz, conteo de SMS)
• Conversiones de saldo - Convertir saldos monetarios en saldos unitarios (por ejemplo, gastar $30 para obtener un paquete de datos de 10GB)
• Estado de la cuenta - Activo, suspendido, deshabilitado según límites de crédito y umbrales

El registro de servicio del CRM contiene metadatos y configuración (cliente, producto, precios, visibilidad), mientras que OCS contiene el estado de facturación en vivo (saldos, uso, cargos).

Recuperación de Uso y Saldos del Servicio

La información de uso del servicio se recupera de OCS/CGRateS y se muestra a los clientes y al personal en tiempo real.

Cómo se Recupera el Uso

Cuando se solicita el uso de un servicio (a través de la interfaz de usuario o API), ocurre el siguiente flujo:

1. Solicitud de API - El frontend llama a GET /crm/service/{service_id} o ve detalles del servicio en la interfaz de usuario

2. Búsqueda de Servicio - La API recupera el registro del servicio de la base de datos, extrae service_uuid

3. Llamadas a la API de CGRateS - El módulo cgrates_service.py realiza dos llamadas a CGRateS:

   a. Get_Balance(service_uuid) - Recupera el saldo de la cuenta con BalanceMap

   • Devuelve saldos organizados por tipo: DATOS, VOZ, SMS, MONETARIO, DATOS_DONGLE
   • Cada saldo incluye: ID, Valor, Fecha de Expiración, Peso, IDs de Destino
   • El sistema agrega campos legibles por humanos: custom_Name_hr, custom_Expiration, custom_Description_String b. Get_ActionPlans(service_uuid) - Recupera planes de acción de auto-renovación activos (cubiertos en la siguiente sección)

4. Fusión de Respuesta - Los datos de CGRateS se fusionan en la respuesta del servicio:

   {
     "service_id": 123,
     "service_name": "Mobile Service",
     "service_uuid": "abc-123-def",
     "cgrates": {
       "BalanceMap": {
         "DATA": [{
           "ID": "DATA_10GB",
           "Value": 5368709120,
           "ExpirationDate": "2025-02-01T00:00:00Z",
           "custom_Name_hr": "10GB Data Pack",
           "custom_Expiration": "Feb 1, 2025",
           "custom_Description_String": "5 GB remaining"
         }],
         "VOICE": [{
           "ID": "VOICE_UNLIMITED",
           "Value": 999999999,
           "custom_Name_hr": "Unlimited Calls",
           "custom_Description_String": "Unlimited minutes"
         }],
         "MONETARY": [{
           "ID": "PREPAID_CREDIT",
           "Value": 25.50,
           "custom_Description_String": "$25.50 credit"
         }]
       },
       "ActionPlans": [...]
     }
   }

5. Visualización en UI - Los componentes del frontend muestran los datos de uso:

   • ServiceUsage.js - Componente principal de visualización de uso con actualización automática cada 3 segundos
   • UsageCard.js - Tarjetas de resumen para cada tipo de saldo
   • UsageProgress.js - Barras de progreso que muestran el porcentaje usado/restante
   • Los saldos están codificados por colores y formateados para facilitar la lectura

Estructura de Datos de Uso

Cada saldo en el BalanceMap contiene:

Campos Nativos de CGRateS:

• ID - Identificador único para el saldo (por ejemplo, "DATA_10GB_2025_01")
• Value - Monto del saldo:
  • Para DATOS: bytes (5368709120 = 5 GB)
  • Para VOZ: segundos (3600 = 1 hora)
  • Para SMS: conteo (100 = 100 mensajes)
  • Para MONETARIO: unidades monetarias (25.50 = $25.50)
• ExpirationDate - Marca de tiempo ISO 8601 cuando expira el saldo
• Weight - Prioridad para el consumo del saldo (peso más alto consumido primero)
• DestinationIDs - Destinos a los que se aplica este saldo (por ejemplo, ["AU", "INTERNATIONAL"])

Campos Legibles por Humanos (agregados por CRM):

• custom_Name_hr - Nombre legible por humanos extraído del ID
• custom_Expiration - Fecha de expiración formateada (por ejemplo, "Ene 15, 2025" o "en 11 días")
• custom_Description_String - Descripción legible por humanos del saldo:
  • DATOS: "5 GB restantes" o "10 GB en total"
  • VOZ: "60 minutos restantes" o "Ilimitado"
  • SMS: "50 SMS restantes"
  • MONETARIO: "$25.50 de crédito"

Control de Visibilidad del Uso

La visibilidad del uso del servicio se controla mediante dos campos:

• service_visible_to_customer - Si es falso, el servicio se oculta completamente del portal de autoatención del cliente
• service_usage_visible_to_customer - Si es falso, el servicio es visible pero se ocultan los detalles de uso/saldo (el cliente puede ver que tiene el servicio, pero no cuánto ha usado)

Esto permite a los operadores:

• Ocultar servicios internos/pruebas de los clientes
• Mostrar que el servicio existe sin revelar el uso (útil para planes ilimitados o servicios sensibles)
• Visualización de uso completamente transparente (predeterminado)

Actualizaciones de Uso en Tiempo Real

La interfaz web actualiza automáticamente los datos de uso:

• Intervalo: Cada 3 segundos (configurable en el componente ServiceUsage)
• Método: Consulta GET /crm/service/{service_id} que obtiene datos en vivo de CGRateS
• Eficiencia: Solo las vistas de servicios activos se actualizan; las vistas de lista utilizan datos en caché

Esto asegura que los clientes y el personal vean actualizaciones de saldo casi en tiempo real a medida que ocurre el uso.

Cargos Recurrentes / AutoRenovación

Los cargos recurrentes, como un Cargo de Servicio Mensual, o un Cargo por DID, se crean primero como Acciones dentro de OCS y toman el formato Action_ServiceUUID_ServiceName_WhatitDoes.

Por ejemplo, para un servicio GPON de $60 al mes que incluye 1TB de uso, la Acción se vería algo así:

Action_kj49-adsf-1234-9742_60_GPON_1TB_MonthlyExpiry

1. Restablecer Saldo Monetario a $0
2. Enviar un POST HTTP a /simple_provision en el CRM para aprovisionar algo
3. Agregar un Crédito por 1TB de Uso que expira en 1 mes

Si queremos que el MRC sea recurrente (lo hacemos), entonces crearíamos un ActionPlan llamado ActionPlan_{{ service_uuid }}_Monthly_Charge que tendría el tiempo establecido en mensual para activarse cada mes, y asignaríamos el ActionPlan a la cuenta.

Podemos establecer, según el parámetro Años / Meses / Días, una fecha de caducidad para cuando el MRC se detenga también, por ejemplo, para un servicio fijo de 12 meses que se detenga después de este punto.

Debido a que las Acciones y los ActionPlans son únicos para el servicio, no comparten nada con otros servicios.

Esto significa que podemos aprovisionarlos con valores ajustados, y no impactará a otros servicios.

Complementos y Adiciones

Los complementos / Adiciones como comprar datos adicionales, paquetes de roaming, minutos internacionales, etc., se manejan de manera muy similar. Se crea una Acción para hacer lo que se necesita, como cobrar un valor monetario y luego otorgar un saldo unitario con una caducidad establecida.

En lugar de usar ActionPlans para agregar esto automáticamente en la cuenta, simplemente activamos ExecuteAction para la Acción que acabamos de crear una vez desde Ansible.

Agregar Saldos Monetarios Prepagados

Para saldos monetarios prepagados, como un plan PAYG de $10, esto se agrega como un saldo monetario, pero con una prioridad más alta.

El límite de crédito en estos servicios para el saldo predeterminado sería $0.

Límites de Crédito / Prevención de Gastos Excesivos

ThresholdS se utilizan en cada cuenta para establecer el gasto máximo para un período de tiempo determinado.

Para clientes PAYG / Prepagados, esto es $0.

Interactuando con OCS a través del CRM

Para cada Servicio puede ver los Balances y ActionPlans, Actions y ThresholdS desde OCS desde dentro de la API del CRM.

Los ActionPlans pueden ser eliminados según sea necesario desde la API del CRM, ejecutados a través de Playbooks de Ansible. Los ActionPlans pueden ser agregados según sea necesario, desde el CRM, al agregar un Complemento/Servicio y ejecutados a través de Playbooks de Ansible.

Las cuentas de OCS pueden ser deshabilitadas, lo que detendrá la ejecución de ActionPlans y de que los servicios puedan ser consumidos.

Para Límites de Crédito, se establece un valor de ThresholdS según la política del producto.

Visualización y Gestión de ActionPlans en el CRM

Los ActionPlans (configuraciones de auto-renovación) se muestran y gestionan a través de la interfaz del CRM, permitiendo al personal y a los clientes ver las renovaciones automáticas próximas y gestionarlas.

Cómo se Recuperan y Muestran los ActionPlans

Al ver un servicio en el CRM, los ActionPlans se recuperan y muestran automáticamente:

1. Llamada a la API - Cuando se llama a GET /crm/service/{service_id}, la API:

   • Recupera el registro del servicio de la base de datos
   • Extrae el service_uuid (identificador de cuenta de OCS)
   • Llama a get_cgrates_action_plans_by_service_uuid(service_uuid) desde cgrates_service.py
   • Esto llama internamente a ocs.Get_ActionPlans(service_uuid) para recuperar ActionPlans de CGRateS

2. Estructura de Datos de ActionPlan - Cada ActionPlan devuelto contiene:

   {
       "ActionPlanId": "ServiceID_abc-123-def__ProductID_456__...",
       "PlanName": "Monthly_Renewal_Plan",
       "NextExecTime": "2025-02-01T00:00:00Z",
       "custom_NextExecTime_hr": "in 11 days",
       "ActionPlanId_split_dict": {
           "ServiceID": "abc-123-def",
           "ProductID": 456,
           "CustomerID": 789,
           ...
       }
   }

   • ActionPlanId - Identificador único que contiene información codificada sobre el servicio/producto/cliente
   • PlanName - Nombre del plan de acción (típicamente el nombre del playbook de renovación)
   • NextExecTime - Marca de tiempo ISO cuando se ejecutará el ActionPlan a continuación
   • custom_NextExecTime_hr - Tiempo legible por humanos hasta la ejecución (por ejemplo, "en 11 días", "mañana", "Feb 1, 2025")
   • ActionPlanId_split_dict - Diccionario con componentes analizados del ActionPlanId

3. Visualización en UI - Los ActionPlans se muestran en el componente ActionPlansTable:

   Columnas de la Tabla:

   • Nombre del Producto - Recuperado buscando ProductID del ActionPlanId
   • Costo - Muestra retail_cost de la definición del producto
   • Fecha de Renovación - Muestra custom_NextExecTime_hr (legible por humanos)
   • Acciones - Dos botones:
     • Renovar Ahora - Aprovisionar inmediatamente el complemento/renovación (salta la espera de la ejecución programada)
     • Eliminar Auto Renovación - Cancela la renovación automática

   Cuando No Existen ActionPlans:

   • La tabla muestra el mensaje: "No hay auto-renovación habilitada para este servicio"
   • El cliente puede agregar complementos de auto-renovación para habilitar la auto-renovación

Gestión de ActionPlans

El personal y los clientes pueden gestionar ActionPlans a través de la interfaz de usuario:

Eliminando un ActionPlan (Cancelando la Auto-Renovación):

1. Haga clic en el botón "Eliminar Auto Renovación" en ActionPlansTable
2. Aparece un modal de confirmación: "¿Está seguro de que desea eliminar esta auto-renovación?"
3. Al confirmar, el frontend llama a: DELETE /crm/oam/remove_action_plan/{action_plan_id}
4. La API elimina el ActionPlan de CGRateS a través de ocs.Remove_ActionPlan()
5. La actividad se registra: "Se eliminó ActionPlan {ActionPlanId} del servicio {service_id}"
6. El ActionPlan desaparece de la tabla

Renovando Inmediatamente (Renovación Manual):

1. Haga clic en el botón "Renovar Ahora" en ActionPlansTable
2. Aparece un modal de confirmación: "¿Está seguro de que desea renovar esto ahora?"
3. Al confirmar, el sistema:
   • Extrae product_id del ActionPlanId
   • Crea un nuevo trabajo de aprovisionamiento para ese producto
   • Aprovisiona el complemento inmediatamente (ejecuta el playbook de aprovisionamiento)
   • El servicio recibe los beneficios del complemento sin esperar la renovación programada
4. El modal de estado de aprovisionamiento muestra el progreso
5. Al éxito, los saldos se actualizan inmediatamente

Agregando Auto-Renovación:

La auto-renovación se habilita aprovisionando un producto complemento que tiene auto_renew establecido:

• Productos con auto_renew = "true" - Crean automáticamente ActionPlans durante el aprovisionamiento
• Productos con auto_renew = "prompt" - Preguntan al cliente si desea auto-renovación (diálogo modal)
• Productos con auto_renew = "false" - Nunca crean ActionPlans (compra única)

El playbook de aprovisionamiento crea el ActionPlan en CGRateS con:

• ActionPlanId único que codifica los IDs de servicio, producto y cliente
• Programa de renovación (mensual, anual, intervalo personalizado)
• Acción a ejecutar (típicamente reprovisionar el mismo complemento)
• Fecha de caducidad (si el contrato tiene un término fijo)

Convención de Nombres de ActionPlan

Los ActionPlans siguen una convención de nombres estandarizada para codificar metadatos:

Formato:

ServiceID_{service_uuid}__ProductID_{product_id}__CustomerID_{customer_id}__...

Ejemplo:

ServiceID_abc-123-def__ProductID_456__CustomerID_789__MonthlyRenewal

Esta codificación permite al CRM:

• Identificar a qué servicio pertenece el ActionPlan
• Buscar detalles del producto (nombre, precios) para mostrar
• Rastrear la propiedad del cliente
• Analizar el tipo de renovación y el programa

El CRM analiza automáticamente estos componentes en ActionPlanId_split_dict para un fácil acceso.

ActionPlans en la Vista del Servicio

Al ver un servicio en el CRM, la tabla de ActionPlans se muestra en los detalles del servicio:

Vista del Personal