Notas de Cobrança de Serviço / Produto CRM

Nota

Para um guia completo de ponta a ponta cobrindo definição de produto, provisionamento, complementos e desprovisionamento com exemplos detalhados de Ansible e estratégia de preços, veja Complete Product Lifecycle Guide <guide_product_lifecycle>.

Visão Geral de Produtos e Serviços

Produto (Item do Menu):

Um Produto é como um prato específico em um menu de restaurante, como um "Spaghetti Carbonara."

Ele tem uma descrição clara, uma lista de ingredientes (como massa, creme, ovos, queijo e bacon) e um preço.

No OmniCRM, um Produto contém de forma semelhante os detalhes do que está incluído — recursos, especificações e preços.

Frequentemente, os clientes podem querer modificações, como "sem cebolas" ou "adicionar queijo extra" ao seu prato. Dentro do OmniCRM, isso corresponde a personalizar um serviço antes da criação. O nível de personalizações ou modificações a um serviço fica a seu critério (o operador) para definir.

No OmniCRM, clientes ou funcionários podem modificar um Produto para atender melhor a necessidades específicas de um cliente, como aumentar a velocidade da Internet ou adicionar recursos específicos. Essa personalização é refletida no Serviço específico fornecido.

Um produto é essencialmente uma oferta que os clientes podem escolher para pedir, semelhante a ler e escolher um prato do menu.

Catálogo de Produtos (Menu do Restaurante):

O Catálogo de Produtos é como o menu completo em um restaurante, que lista todos os pratos disponíveis — de aperitivos a sobremesas.

É a coleção completa de tudo que o restaurante (ou, no seu caso, o Provedor de Serviços) tem a oferecer.

No contexto empresarial, o Catálogo de Produtos fornece aos clientes todos os Produtos disponíveis, para que possam escolher aquele que melhor atende às suas necessidades.

Serviço (Prato Preparado):

Quando um cliente pede um item do menu, o prato é preparado na cozinha. Isso é semelhante à criação de um Serviço a partir de um Produto.

No OmniCRM, quando um cliente seleciona um Produto, uma instância desse Produto é criada e entregue como um Serviço.

Ele é personalizado e preparado especificamente para aquele cliente, assim como uma refeição preparada para um cliente.

Por exemplo, quando alguém seleciona o "Plano de Internet Bronze" do Catálogo de Produtos, o sistema de provisionamento "cozinha" uma instância desse plano a partir dos ingredientes (endereços IP, Modems e Portas) — ou seja, ativa o plano e o entrega ao cliente específico.

Produtos Agrupados (Refeições Combo):

O Catálogo de Produtos também pode oferecer pacotes, como uma refeição combo que inclui um aperitivo, prato principal e sobremesa juntos por um preço especial.

No OmniCRM, Produtos agrupados combinam vários Produtos individuais em um pacote conveniente — como um "Pacote de Essenciais para Casa" que inclui serviços de Internet, TV e telefone a uma taxa com desconto.

Uma vez selecionado, esse pacote é transformado em vários Serviços adaptados para o cliente.

Definições de Produto

Um produto é um modelo que é usado para criar um serviço / complemento / desconto / adicional, etc.

Dentro da definição, incluímos:

• Informações sobre o produto (recursos, inclusões, termos e condições, duração do contrato, ícone, etc.) que são exibidas para o usuário do CRM (Cliente ou Funcionário).

• A lógica de negócios sobre quem pode comprar o produto (Empresarial ou Residencial), se depende de ter um serviço pai provisionado (como complementos móveis disponíveis apenas para clientes com um serviço móvel), se pode ser solicitado diretamente por um cliente via autoatendimento ou apenas por um agente de atendimento ao cliente, e quando o produto pode ser adquirido (permitindo que um produto esteja disponível apenas por um período definido).

• Quando itens de Inventário devem ser incluídos (como Modems ou Cartões SIM) estes são especificados como Lista de Itens de Inventário, por exemplo, o serviço abaixo requer um Cartão SIM e um Número de Telefone a serem atribuídos:

  ['SIM Card', 'Phone Number'] Estes correlacionam-se com os Inventory Items <administration_inventory> definidos no CRM.

• Referenciar um Playbook Ansible para provisionar o serviço Provisioning Play <concepts_ansible> bem como as variáveis a passar para o Ansible. Essas variáveis a serem passadas são mágicas, pois podem ser variáveis como service_id que são definidas pelo produto ao qual estamos adicionando, ou podem ser como ICCID & MSISDN onde selecionamos itens de inventário que são passados ao atribuir o inventário. O agrupamento é tratado no playbook de provisionamento para conter vários serviços, por exemplo, um produto de internet residencial, TV e Voz pode provisionar um serviço para cada.

Categorias de Produto e Tipos de Serviço

Os produtos usam dois campos de classificação para ajudar a organizar e filtrar ofertas:

Categorias de Produto

O campo category controla onde os produtos são exibidos na interface do usuário. Valores comuns incluem:

• standalone - Exibido como uma opção de serviço base ao criar um novo serviço
• addon - Exibido ao adicionar a um serviço existente
• bundle - Exibido como uma opção de serviço agrupado (provisionado como um complemento a serviços existentes)
• promo - Ofertas promocionais especiais

Essas categorias são puramente organizacionais e não ditam o que é provisionado. O comportamento real de provisionamento é determinado inteiramente pelo playbook Ansible referenciado em provisioning_play.

Por exemplo: - Um produto standalone normalmente cria um novo objeto de serviço - Um produto addon ou bundle normalmente é adicionado a um serviço existente - Mas isso depende do implementador que escreve o playbook - você poderia criar múltiplos objetos de serviço a partir de um complemento, ou modificar serviços existentes a partir de um produto autônomo, se necessário

A categoria simplesmente controla o fluxo da interface do usuário e onde os clientes/funcionários veem a opção do produto.

Tipos de Serviço

O campo service_type categoriza que tipo de serviço está sendo fornecido.

Esses são definidos inteiramente pelo usuário, mas valores comuns incluem:

• mobile - Serviços de telefone móvel com voz, SMS e dados
• fixed - Serviços de internet fixa sem fio ou com fio
• fixed-voice - Serviços de voz fixa (VoIP, linha fixa)
• hotspot - Dispositivos móveis de hotspot ou de aluguel
• dongle - Serviços de modem USB ou dongle
• voice - Serviços apenas de voz
• data - Serviços apenas de dados

Assim como as categorias, os tipos de serviço são personalizáveis com base nas suas ofertas. Eles ajudam em:

• Filtrar quais complementos se aplicam a quais serviços base
• Organizar produtos no portal do cliente
• Correspondência de requisitos de inventário
• Determinar fluxos de trabalho de provisionamento

Exemplo: Um cliente com um serviço mobile pode ver complementos móveis, enquanto um cliente com um serviço fixed vê complementos de linha fixa.

Gerenciando Produtos

Os produtos são gerenciados através da página de Gerenciamento de Produtos, onde você pode visualizar, pesquisar, filtrar e editar todos os produtos disponíveis.

Interface Modal de Produto

Clicar em qualquer produto abre uma interface de abas aprimorada que organiza todas as configurações do produto em grupos lógicos para navegação e edição mais fáceis.

O modal de gerenciamento de produtos possui cinco abas organizadas:

1. 📋 Informações Básicas - Informações principais do produto (nome, slug, categoria, ícone, recursos, termos)
2. 💰 Preços - Todos os campos relacionados a custos, incluindo custos recorrentes, custos de configuração e percentual de imposto
3. ⚙️ Configuração - Configurações de renovação, tipos de clientes e dependências
4. 🔧 Provisionamento - Configuração do playbook Ansible e requisitos de inventário
5. 📅 Disponibilidade - Intervalos de datas e timestamps do sistema

Organização da Aba de Preços:

A aba de Preços agrupa os campos de custo em seções lógicas:

• Custos Recorrentes - Custos mensais de varejo e atacado lado a lado
• Custos de Configuração - Taxas de ativação únicas para varejo e atacado
• Imposto - Configuração da porcentagem de imposto com cálculo automático

Recursos do Modo de Edição:

• Selecionador de Ícone - Pesquisar e selecionar ícones FontAwesome visualmente
• Selecionador de Itens de Inventário - Selecionar entre os tipos de itens de inventário disponíveis
• Selecionador de Data/Hora - Seleção fácil de janelas de disponibilidade
• Formatação de Moeda - Prefixo automático $ para campos de custo
• Seletores de Dropdown - Opções pré-definidas para categorias e campos booleanos

Selecionador de Ícone:

Ao editar o campo de ícone, uma interface de selecionador de ícone pesquisável aparece permitindo que você navegue visualmente e selecione entre milhares de ícones FontAwesome.

Recursos: * Pesquisar ícones por palavra-chave (por exemplo, "chave inglesa", "móvel", "wifi") * Visualizar a aparência do ícone em tempo real * Mostrar o nome da classe do ícone para referência * Seleção de dropdown para acesso rápido

Aba de Configuração:

A aba de Configuração organiza as configurações de comportamento do produto em grupos lógicos.

Seções de Configuração:

• Configurações de Renovação:
  • Auto Renovar - Comportamento padrão de renovação (Prompt/Sim/Não)
  • Permitir Auto Renovação - Se os clientes podem habilitar a auto-renovação
  • Dias de Contrato - Duração mínima do contrato (por exemplo, 30 para mensal, 365 para anual)
• Tipos de Clientes:
  • Residencial - Disponível para clientes consumidores
  • Empresarial - Disponível para clientes comerciais
• Dependências:
  • Lista de Dependências - IDs de produtos ou tipos de serviço necessários antes que este produto possa ser adicionado
  • Usado para dependências de complementos (por exemplo, complementos móveis requerem serviço móvel ativo)

Aba de Provisionamento:

A aba de Provisionamento lida com automação Ansible e requisitos de inventário.

Campos de Provisionamento:

• Playbook de Provisionamento:
  • Nome do playbook Ansible (sem extensão .yaml)
  • Deve existir no diretório OmniCRM-API/Provisioners/plays/
  • Chamado quando o serviço é criado, atualizado ou desprovisionado
• Variáveis JSON de Provisionamento:
  • Variáveis padrão passadas para o playbook Ansible como JSON
  • Podem ser substituídas durante o provisionamento
  • O playbook recebe essas além de customer_id, product_id, service_id, access_token
• Lista de Itens de Inventário:
  • Seletor de múltipla seleção mostrando os tipos de itens de inventário disponíveis
  • Exemplos: Cartão SIM, Número de Telefone, Roteador Modem, Endereço IPv4
  • Cliente/funcionário seleciona itens específicos do inventário disponível durante o pedido
  • IDs de inventário selecionados passados para o playbook com o tipo de inventário como nome da variável

Aba de Disponibilidade:

A aba de Disponibilidade controla quando o produto pode ser adquirido e exibe metadados do sistema.

Configurações de Disponibilidade:

• Disponível A Partir de:
  • Data/hora quando o produto se torna disponível para compra
  • Deixe vazio para disponibilidade imediata
  • Útil para pré-anunciar novos produtos
• Disponível Até:
  • Data/hora quando o produto não está mais disponível para compra
  • Deixe vazio para disponibilidade indefinida
  • Perfeito para promoções por tempo limitado ou produtos fora de linha
• Metadados do Sistema (Somente Leitura):
  • Criado - Timestamp quando o produto foi criado pela primeira vez
  • Última Modificação - Timestamp da atualização mais recente
  • Mantido automaticamente pelo sistema

Ações do Modal:

• Modo de Visualização:
  • Fechar - Descartar modal
  • Clonar Produto - Criar uma cópia com o sufixo "_clone"
  • Editar Produto - Mudar para modo de edição
• Modo de Edição/Criar:
  • Cancelar - Descartar alterações e fechar
  • Salvar Alterações - Criar ou atualizar produto (botão grande para ênfase)

Campos do Produto

O modelo de Produto contém todas as informações necessárias para definir uma oferta e como ela deve ser provisionada. Esses campos são gerenciados através da interface modal de gerenciamento de produtos descrita acima.

Informações Básicas

• product_id - Identificador único atribuído automaticamente pelo sistema
• product_name - Nome exibido para clientes e funcionários na interface do usuário
• product_slug - Identificador único usado em URLs e chamadas de API (minúsculas, sem espaços, use hífens)
• category - Controla onde este produto aparece na interface do usuário:
  • standalone - Exibido como uma opção de serviço base ao criar um novo serviço
  • addon - Exibido ao adicionar a um serviço existente
  • bundle - Exibido como uma opção de serviço agrupado
  • promo - Ofertas promocionais especiais
• service_type - Tipo de serviço sendo fornecido (por exemplo, móvel, fixo, voz-fixa, hotspot, dongle, voz, dados). Usado para filtrar quais complementos se aplicam a quais serviços.
• comment - Notas internas sobre o produto para referência dos funcionários apenas (não exibidas para clientes)
• icon - Classe de ícone FontAwesome exibida na interface do usuário (por exemplo, fa-solid fa-sim-card)

Campos de Preço

• retail_cost - Custo mensal recorrente cobrado ao cliente (defina como 0 para compras únicas ou produtos pré-pagos)
• wholesale_cost - Seu custo mensal para fornecer este serviço (usado para cálculos de margem)
• retail_setup_cost - Taxa de ativação ou configuração única cobrada ao cliente
• wholesale_setup_cost - Seu custo único para configurar o serviço
• tax_percentage - Porcentagem de imposto aplicada a este produto (por exemplo, 10 para 10%, 12,5 para 12,5%). Defina como 0 para produtos isentos de impostos. Esta taxa de imposto é aplicada automaticamente às transações criadas a partir deste produto.

Aplicação do Imposto:

Quando uma transação é criada a partir deste produto, a porcentagem de imposto é copiada automaticamente para a transação e o valor do imposto é calculado. Por exemplo:

• Produto com 10% de imposto, $50,00 custo de varejo → Transação tem $5,00 de imposto
• Produto com 0% de imposto (isenção de impostos) → Transação tem $0,00 de imposto
• Sobrescrita manual da transação → Funcionários podem alterar a porcentagem de imposto por transação

Visibilidade e Acesso do Cliente

• enabled - Se este produto está ativo e disponível para compra (defina como falso para ocultar sem excluir)
• residential - Se clientes residenciais (consumidores) podem comprar este produto
• business - Se clientes empresariais (comerciais) podem comprar este produto
• customer_can_purchase - Se os clientes podem comprar por conta própria via o portal (verdadeiro) ou se apenas os funcionários podem adicioná-lo (falso)
• available_from - Data/hora quando este produto se torna disponível para compra (opcional)
• available_until - Data/hora quando este produto não está mais disponível para compra (opcional, útil para ofertas por tempo limitado)

Contrato e Renovação

• contract_days - Duração mínima do contrato em dias (por exemplo, 30 para mensal, 365 para anual, 0 para sem contrato mínimo)
• auto_renew - Comportamento padrão de renovação:
  • prompt - Pergunta ao cliente toda vez se deseja renovar
  • true - Renova automaticamente sem perguntar
  • false - Requer renovação manual
• allow_auto_renew - Se os clientes podem habilitar a renovação automática (defina como falso para compras únicas)

Conteúdo Voltado para o Cliente

• terms - Termos e condições exibidos aos clientes antes da compra (inclua limitações, regras de expiração, condições de uso)
• features_list - Lista de recursos e inclusões mostradas aos clientes (formato de lista Python: ['Feature 1', 'Feature 2'])

Configuração de Provisionamento

• provisioning_play - Nome do playbook Ansible que provisiona este serviço (sem extensão .yaml). Deve existir em OmniCRM-API/Provisioners/plays/.
• provisioning_json_vars - Variáveis padrão passadas para o playbook Ansible como JSON. Estas podem ser substituídas durante o provisionamento. O playbook recebe essas junto com customer_id, product_id, service_id e access_token.
• inventory_items_list - Lista de itens de inventário necessários para este produto (por exemplo, ['SIM Card', 'Mobile Number']). Quando um cliente faz um pedido, ele será solicitado a selecionar itens específicos do inventário disponível. IDs de inventário selecionados são passados para o playbook com o tipo de inventário como o nome da variável.
• relies_on_list - Lista de IDs de produtos ou tipos de serviço que devem existir antes que este produto possa ser adicionado. Usado para dependências de complementos (por exemplo, complementos móveis requerem um serviço móvel ativo).

Metadados do Sistema

• created - Timestamp quando o produto foi criado (definido automaticamente)
• last_modified - Timestamp quando o produto foi atualizado pela última vez (atualizado automaticamente)

Exemplos de Definições de Produto

Produto Autônomo (SIM Móvel)

{
  "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 produto autônomo requer dois itens de inventário (Cartão SIM e Número Móvel) e cria um novo serviço quando provisionado.

Produto Adicional (Plano de Dados Mensal)

{
  "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 produto adicional não requer inventário e é aplicado a um serviço existente. Ele cobra o cliente e adiciona créditos/saldos ao seu serviço.

Produto Agrupado (Pacote para Idosos)

{
  "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 produto agrupado provisiona múltiplos serviços (Internet + IPTV + Telefone) usando um único playbook. Ele requer um item de inventário (Roteador Modem).

Produto Adicional (Recarga Simples)

{
  "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 adicional simplesmente adiciona crédito monetário a um serviço existente. Nenhum inventário é necessário, e ele usa service_id para identificar qual serviço deve ser recarregado.

Como as Variáveis são Passadas para o Ansible

Compreender como as variáveis fluem da definição do produto através da API para o playbook Ansible é crítico para escrever playbooks de provisionamento eficazes.

Fontes e Mesclagem de Variáveis

Quando um trabalho de provisionamento é criado, as variáveis vêm de várias fontes e são mescladas nesta ordem (fontes posteriores substituem as anteriores):

1. Variáveis de provisioning_json_vars do Produto - Variáveis padrão da definição do produto
2. Corpo da Solicitação - Variáveis passadas na chamada da API (podem substituir os padrões do produto)
3. Variáveis adicionadas pelo sistema - Adicionadas automaticamente pelo sistema de provisionamento
4. Seleções de Inventário - IDs dos itens de inventário selecionados (se inventory_items_list não estiver vazio)

Processo de Mesclagem de Variáveis

O sistema mescla variáveis de todas as fontes, com fontes posteriores substituindo as anteriores. Isso permite uma personalização flexível no momento do provisionamento.

Por exemplo, se seu produto tiver:

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

E sua solicitação API incluir:

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

As variáveis finais extra_vars passadas para o Ansible serão:

{
    "monthly_cost": 45,        # Substituído pela solicitação
    "data_gb": 100,            # Da provisioning_json_vars
    "product_id": 10,          # Da solicitação
    "customer_id": 456,        # Da solicitação
    "custom_param": "value",   # Da solicitação
    "access_token": "eyJ..."   # Adicionado pelo sistema
}

Variáveis Adicionadas pelo Sistema

O sistema de provisionamento adiciona automaticamente:

• access_token - Token JWT para autenticar chamadas de API de volta ao CRM (a partir de g.access_token para autenticação IP/API key, ou gerado a partir de refresh_token para autenticação de usuário)
• initiating_user - O ID do usuário que acionou o provisionamento (ou primeiro administrador para sistemas automatizados)
• Quaisquer campos do corpo da solicitação (product_id, customer_id, service_id, etc.)

Variáveis de Inventário

Quando um produto requer itens de inventário (por exemplo, inventory_items_list: "['SIM Card', 'Mobile Number']"), o processo funciona da seguinte forma:

1. UI/API solicita seleção - O usuário seleciona itens de inventário específicos do estoque disponível
2. IDs de Inventário são adicionados às variáveis - Os IDs dos itens de inventário selecionados são adicionados com o tipo de inventário como o nome da variável
3. O playbook acessa os IDs de inventário - O playbook de provisionamento pode então recuperar os detalhes completos do inventário da API do CRM

Por exemplo, se um usuário selecionar: - Cartão SIM com inventory_id: 789 - Número Móvel com inventory_id: 101

As variáveis passadas para o playbook incluem: - SIM Card: 789 - Mobile Number: 101

O playbook pode então usar esses IDs para buscar os registros completos de inventário (ICCID, IMSI, MSISDN, etc.) da API do CRM e usar essas informações para provisionar o serviço em equipamentos de rede.

Como o Ansible Recebe Variáveis

O sistema de provisionamento passa todas as variáveis mescladas para o playbook Ansible como extravars. Dentro do playbook, essas variáveis estão disponíveis através do sistema de variáveis padrão do Ansible e podem ser usadas em tarefas.

As variáveis podem ser referenciadas diretamente nas tarefas do playbook usando a sintaxe {{ variable_name }}. Por exemplo, {{ product_id }}, {{ customer_id }}, {{ monthly_cost }}, etc.

Variáveis Passadas para Produtos Adicionais

Quando um produto adicional é provisionado, o sistema passa automaticamente:

• product_id - O ID do produto adicional sendo provisionado
• customer_id - O cliente que possui o serviço
• service_id - O ID do serviço ao qual este complemento está sendo adicionado (crítico para complementos)
• access_token - Token de autenticação para chamadas de API
• Quaisquer variáveis de provisioning_json_vars
• Quaisquer variáveis adicionais da solicitação API

Exemplo de Fluxo de Provisionamento de Complemento

Quando um cliente adiciona o complemento "Recarga de £5" ao seu serviço móvel (service_id: 123), o playbook recebe variáveis incluindo:

• product_id: 45 (o produto de recarga)
• customer_id: 456 (o cliente)
• service_id: 123 (o serviço para o qual adicionar crédito)
• access_token: Token de autenticação
• Além de quaisquer variáveis de provisioning_json_vars do produto

O playbook então usa essas variáveis para:

1. Buscar detalhes do serviço da API do CRM usando o service_id
2. Extrair o UUID do serviço e outras informações do registro do serviço
3. Adicionar crédito ao sistema de cobrança (OCS) usando o UUID do serviço
4. Registrar a transação no CRM para fins de faturamento

Esse fluxo permite que o complemento identifique exatamente qual serviço modificar e aplique as alterações de forma apropriada.

Diferença Entre Variáveis de Produtos Autônomos e Adicionais

Produtos Autônomos recebem:

• product_id - O produto sendo provisionado
• customer_id - O cliente que está solicitando o serviço
• IDs de itens de inventário (por exemplo, SIM Card, Mobile Number) se o produto os requer
• access_token - Para autenticação da API

Produtos Adicionais recebem:

• product_id - O produto adicional sendo provisionado
• customer_id - O cliente que possui o serviço
• service_id - O ID do serviço existente a ser modificado (esta é a principal diferença)
• access_token - Para autenticação da API

A principal diferença é service_id - isso informa ao playbook qual serviço existente modificar ou adicionar a.

Produtos Agrupados

Produtos agrupados são provisionados como complementos, mas seu playbook pode criar múltiplos registros de serviço. Eles recebem as mesmas variáveis que complementos, incluindo:

• product_id - O produto agrupado
• customer_id - O cliente
• service_id - Serviço pai (se aplicável)
• IDs de itens de inventário (por exemplo, Modem Router) se necessário
• access_token - Para autenticação da API

O playbook do pacote (por exemplo, play_seniors_package) então cria múltiplos serviços relacionados (Internet, IPTV, Telefone) e os vincula.

Serviços

Um serviço é uma instância de um produto que pertence a um cliente, pelo qual ele é cobrado.

É essencialmente um link para uma conta do OCS </glossary> (Sistema de Cobrança Online) que lida com a geração de cobranças e os saldos e usos reais da conta. O OCS é alimentado pelo CGRateS e gerencia saldos monetários, saldos unitários (dados, voz, SMS), Planos de Ação para auto-renovação e Limites de Gastos.

Adicionando um Serviço: Seleção e Filtragem de Produtos

Ao adicionar um serviço a um cliente (seja um novo serviço autônomo ou um complemento a um serviço existente), o sistema exibe produtos disponíveis em uma interface de carrossel. Os produtos mostrados são filtrados com base em vários critérios:

Filtragem de Produtos para Serviços Autônomos

Ao criar um novo serviço para um cliente, a interface do usuário exibe produtos filtrados por:

1. Tipo de Cliente - Produtos são categorizados como:
   • Individual (Residencial): Produtos onde residential = true ou business = false
   • Empresarial: Produtos onde business = true
2. Categoria - Produtos são separados em:
   • Planos de Serviço: Produtos com category = standalone ou bundle
   • Complementos: Produtos com category = addon (exibidos em um carrossel separado)
3. Disponibilidade - Produtos são mostrados apenas se:
   • enabled = true - Produto está ativo e não desativado
   • A data atual está entre available_from e available_until - Produto está dentro de sua janela de disponibilidade
   • customer_can_purchase = true (se o cliente está comprando por conta própria) - Produto permite compra direta pelo cliente

Nota

Filtragem em Nível de API: A API filtra automaticamente produtos por status habilitado e datas de disponibilidade em dois níveis:

• Endpoints de Compra/Seleção (/crm/product/) - Usado pelo modal de Complementos e PlanList para seleção de produtos. Filtra automaticamente para mostrar APENAS produtos habilitados dentro de seu intervalo de datas de disponibilidade. Isso garante que clientes e funcionários só possam selecionar produtos que estão atualmente disponíveis para compra.
• Endpoints de Gerenciamento (/crm/product/paginated) - Usado pela página de Gerenciamento de Produtos. Mostra TODOS os produtos, incluindo desativados e fora das datas de disponibilidade, permitindo que administradores gerenciem o catálogo completo de produtos incluindo produtos inativos.

Passe include_disabled=true para o endpoint base do produto para ignorar a filtragem (apenas para uso administrativo).

A interface do usuário exibe carrosséis separados para:

• Planos de Serviço Individuais - Produtos residenciais para clientes consumidores
• Planos de Serviço Empresariais - Produtos comerciais para clientes empresariais
• Complementos Individuais - Pacotes de complementos residenciais
• Complementos Empresariais - Pacotes de complementos comerciais

Filtragem de Produtos para Serviços Adicionais

Ao adicionar um complemento a um serviço existente, uma filtragem adicional �� aplicada:

1. Correspondência de Tipo de Serviço - Apenas complementos com service_type correspondente são mostrados:
   • Se o serviço existente tem service_type = "mobile", apenas complementos com service_type = "mobile" são exibidos
   • Isso garante que clientes móveis vejam apenas complementos móveis, clientes de internet vejam apenas complementos de internet, etc.
2. Verificação de Dependências - Se um complemento tem uma relies_on_list:
   • O sistema verifica se o cliente possui os produtos/serviços necessários
   • Apenas complementos cujas dependências estão satisfeitas são mostrados
3. Filtro de Mesmo Tipo de Cliente - Os complementos ainda são filtrados por residential vs business para corresponder ao tipo de cliente

Exemplo de Cenário de Filtragem

Para um cliente empresarial com um serviço móvel existente (service_type = "mobile"):

• Produtos Autônomos Exibidos: Todos os produtos autônomos/agrupados empresariais (business = true, category != "addon")
• Produtos Adicionais Exibidos: Apenas complementos móveis empresariais (business = true, category = "addon", service_type = "mobile")
• Produtos Ocultos: Produtos residenciais, complementos para outros tipos de serviço (internet, voz, etc.), produtos desativados

Campos de Serviço

O modelo de Serviço contém campos que rastreiam a instância de serviço provisionada e sua relação com o cliente, produto e sistema de cobrança.

Informações Básicas do Serviço

• service_id - Identificador único atribuído automaticamente pelo sistema (somente leitura)
• customer_id - Link para o cliente que possui este serviço (somente leitura após a criação)
• product_id - Link para o produto a partir do qual este serviço foi criado (somente leitura após a criação)
• service_name - Nome exibido para os clientes (editável)
• service_type - Tipo de serviço: móvel, internet, voip, iptv, pacote, etc. (editável)
• service_uuid - Identificador único usado no OCS/CGRateS para cobrança (somente leitura, gerado automaticamente)
• icon - Classe de ícone FontAwesome para exibição no portal de autoatendimento (editável)

Status e Datas do Serviço

• service_status - Status atual: Ativo, Inativo, Suspenso, etc. (editável)
• service_provisioned_date - Quando o serviço foi provisionado pela primeira vez (definido automaticamente, somente leitura)
• service_active_date - Quando o serviço se tornou ativo (editável)
• service_deactivate_date - Quando o serviço expira ou será desativado (editável)
• contract_end_date - Data de término do compromisso contratual (editável)

Cobrança e Preços

• retail_cost - Custo mensal recorrente para o cliente (editável)
• wholesale_cost - Seu custo para fornecer o serviço (editável)
• service_billed - Se este serviço aparece nas faturas (editável, padrão: verdadeiro)
• service_taxable - Se os impostos se aplicam a este serviço (editável, padrão: verdadeiro)
• invoiced - Se o serviço foi faturado (definido automaticamente pelo sistema de cobrança)
• promo_code - Código promocional usado quando o serviço foi criado (editável)

Visibilidade do Cliente

• service_visible_to_customer - Se o cliente pode ver este serviço no portal de autoatendimento (editável, padrão: verdadeiro)
• service_usage_visible_to_customer - Se o cliente pode visualizar detalhes de uso/saldo (editável, padrão: verdadeiro)

Configuração de Provisionamento

• provisioning_play - Playbook Ansible usado para provisionar este serviço (herdado do produto, somente leitura)
• provisioning_json_vars - Variáveis passadas para o playbook de provisionamento (herdadas do produto, somente leitura)
• deprovisioning_play - Playbook Ansible a ser executado quando o serviço é desprovisionado (somente leitura)
• deprovisioning_json_vars - Variáveis para o playbook de desprovisionamento (somente leitura)

Relações de Serviço

• bundled_parent - Se este serviço é parte de um pacote, o service_id do serviço pai (somente leitura)
• site_id - Link para o local físico onde o serviço é entregue (editável)

Notas e Metadados

• service_notes - Notas internas sobre o serviço para referência dos funcionários (editável)
• created - Timestamp quando o serviço foi criado (definido automaticamente, somente leitura)
• last_modified - Timestamp da última atualização (atualizado automaticamente, somente leitura)

Campos Editáveis vs Somente Leitura

Editáveis via API/UI:

Os serviços podem ser atualizados via PATCH /crm/service/{service_id} com estes 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

Somente Leitura (Definido Automaticamente):

Esses campos não podem ser modificados diretamente após a criação:

• service_id, customer_id, product_id
• service_uuid (gerado durante o provisionamento)
• service_provisioned_date
• provisioning_play, provisioning_json_vars
• deprovisioning_play, deprovisioning_json_vars
• bundled_parent
• invoiced (gerenciado pelo sistema de cobrança)
• created, last_modified (gerenciado automaticamente)

Provisionando Produtos em Serviços

O processo de provisionamento converte um Produto (modelo) em um Serviço (instância específica do cliente) através de uma série de etapas coordenadas envolvendo a interface Web, API e playbooks Ansible.

Fluxo de Provisionamento de Alto Nível

1. Configuração Pré-Provisionamento - Produto criado na API com configuração de provisionamento, e playbooks Ansible correspondentes escritos e testados
2. Seleção de Serviço - A partir da Página do Cliente, funcionários ou clientes selecionam "Adicionar Serviço"
3. Filtragem de Produtos - Produtos exibidos filtrados com base em:
   • Tipo de cliente (residencial/empresarial)
   • Serviços existentes (para dependências de complementos em relies_on_list)
   • Datas de disponibilidade (available_from/available_until)
   • Flags enabled e customer_can_purchase
4. Personalização - Opção de substituir variáveis de provisionamento (para ajustes de preço, configurações personalizadas, etc.)
5. Seleção de Inventário - Se o produto requer inventário (inventory_items_list não está vazio), o usuário seleciona itens específicos (por exemplo, qual cartão SIM, qual número de telefone)
6. Início do Provisionamento - Quando o botão "Provisionar" é clicado, a API cria um trabalho de provisionamento

Fluxo Detalhado de Integração da API e Ansible

Quando um serviço é provisionado, a seguinte sequência ocorre:

Passo 1: Criação do Trabalho de Provisionamento (/routes/service.py)

A API recebe a solicitação de provisionamento e chama create_provisioning_job() de services/provisioning_service.py com:

• provisioning_play - Nome do playbook Ansible (por exemplo, play_psim_only)
• provisioning_json_vars - String JSON de variáveis do produto ou substituídas pela solicitação
• customer_id - ID do cliente que está solicitando o serviço
• product_id - ID do produto sendo provisionado
• service_id - (Opcional) ID do serviço existente para complementos
• Seleções de Inventário - IDs dos itens de inventário selecionados

Passo 2: Montagem de Variáveis (services/provisioning_service.py)

O serviço de provisionamento mescla variáveis de várias fontes nesta ordem:

1. provisioning_json_vars do Produto (padrões da definição do produto)
2. Parâmetros do corpo da solicitação (podem substituir os padrões do produto)
3. Variáveis adicionadas pelo sistema:
   • access_token - Token JWT para autenticação da API de volta ao CRM
   • initiating_user - ID do usuário que acionou o provisionamento
   • customer_id, product_id, service_id
4. Seleções de Inventário - Adicionadas como pares {inventory_type: inventory_id}

Exemplo de variáveis mescladas:

{
    "customer_id": 123,
    "product_id": 456,
    "service_id": 789,          # Apenas para complementos
    "SIM Card": 1001,           # Da seleção de inventário
    "Mobile Number": 1002,      # Da seleção de inventário
    "monthly_cost": 30,         # Da provisioning_json_vars
    "data_gb": 50,              # Da provisioning_json_vars
    "access_token": "eyJ...",   # Adicionado pelo sistema para callbacks da API
    "initiating_user": 5        # Adicionado pelo sistema
}

Passo 3: Criação do Registro de Provisionamento (models.py - Modelo de Provisionamento)

Um registro de Provision é criado no banco de dados com:

• provision_id - Identificador único para rastreamento
• provisioning_play - Nome do arquivo do playbook
• provisioning_json_vars - Variáveis mescladas como string JSON
• task_count - Número de tarefas no playbook (extraído do YAML)
• provisioning_status - Código de status (inicialmente definido como 1 = em execução, depois atualizado para 0 = sucesso, 2 = falhou, ou pode permanecer 1 se ainda estiver em progresso)
• product_id, customer_id, service_id - Referências de contexto

Passo 4: Execução do Playbook em Segundo Plano (Provisioners/playbook_runner_v2.py)

A API cria uma thread em segundo plano que:

1. Carrega o YAML do playbook de OmniCRM-API/Provisioners/plays/{playbook_name}.yaml
2. Chama ansible_runner.run() com:
   • playbook - Caminho para o arquivo YAML carregado
   • extravars - Todas as variáveis mescladas (passadas para o Ansible)
   • inventory - Definido como 'localhost,' (execução local)
   • event_handler - Manipulador personalizado para capturar eventos de execução de tarefas
3. Monitora a execução do playbook em tempo real

Passo 5: Captura de Eventos e Registro (ProvisioningEventHandler)

À medida que cada tarefa Ansible é executada, eventos são capturados e armazenados como registros de Provision_Event:

• event_name - Nome da tarefa do playbook
• event_number - Número da sequência
• provisioning_status - Código de status indicando o resultado da tarefa:
  • 0 = Sucesso - Tarefa concluída com sucesso
  • 1 = Em Execução - Tarefa está atualmente em execução
  • 2 = Falhou - Falha crítica que interrompe o provisionamento
  • 3 = Falhou (ignorado) - Tarefa falhou, mas erros foram ignorados (ignore_errors: true no playbook)
• provisioning_result_json - Resultados da tarefa com dados sensíveis redigidos

O manipulador de eventos automaticamente remove senhas, chaves, segredos e outros dados sensíveis dos logs.

Passo 6: Execução do Playbook Ansible (Provisioners/plays/*.yaml)

O playbook Ansible é executado localmente e normalmente realiza estas ações:

1. Buscar Definição do Produto - Solicitação GET para /crm/product/product_id/{{ product_id }} usando {{ access_token }}

2. Buscar Informações do Cliente - Solicitação GET para /crm/customer/customer_id/{{ customer_id }}

3. Processar Itens de Inventário (se necessário) - Solicitação GET para /crm/inventory/inventory_id/{{ inventory_id }} para cada item selecionado para recuperar detalhes completos (ICCID, MSISDN, números de série, etc.)

4. Configurar Sistemas Externos - Fazer chamadas de API para:

   • HSS (Home Subscriber Server) para provisionamento de assinantes
   • IMS (IP Multimedia Subsystem) para registro de voz
   • CGRateS/OCS para criação de conta, configuração de cobrança, planos de tarifas
   • Servidores ENUM para mapeamento de números de telefone
   • Equipamentos de rede (roteadores, switches, etc.)

5. Adicionar Custos de Configuração (se aplicável) - POST para /crm/transaction/ para registrar cobranças únicas

6. Cobrar o Cliente - POST para OCS/CGRateS para cobrar retail_setup_cost se configurado

7. Criar Conta OCS - POST para OCS/CGRateS para criar conta de cobrança com UUID

8. Configurar Cobranças Recorrentes - Criar Ações e Planos de Ação em OCS/CGRateS para cobranças mensais recorrentes

9. Criar Registro de Serviço - PUT/POST para /crm/service/ para criar o registro de serviço no 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": "{...}"
   }

10. Atribuir Inventário - PATCH para /crm/inventory/inventory_id/{{ inventory_id }} para marcar o inventário como "Atribuído" ao serviço

11. Enviar Notificações (opcional) - Email ou SMS para o cliente com detalhes do serviço

Passo 7: Conclusão e Atualização de Status

Quando o playbook é concluído:

• Sucesso: Provision.provisioning_status atualizado para 0 (Sucesso)
• Falha Crítica: Provision.provisioning_status atualizado para 2 (Falhou), e email de falha enviado para crm_config.provisioning.failure_list
• Falhas Não Críticas: Tarefas que falham com ignore_errors: true são marcadas com status 3 (Falhou, mas ignorado) e não interrompem o provisionamento

O serviço provisionado agora é visível no CRM e ativo para o cliente (se o provisionamento foi bem-sucedido).

Principais Diferenças: Provisionamento Autônomo vs Adicional vs Agrupado

Produtos Autônomos (category: standalone):

• Recebem customer_id e product_id
• Normalmente requerem itens de inventário (cartões SIM, números de telefone, modens)
• Criam um registro de serviço novo via API PUT /crm/service/
• Provisionam novos recursos em sistemas externos (HSS, OCS, equipamentos de rede)
• Exemplo: Ativação de novo SIM móvel, nova conexão de internet

Produtos Adicionais (category: addon):

• Recebem customer_id, product_id e service_id (serviço existente a ser modificado)
• Normalmente NÃO requerem inventário (ou inventário mínimo)
• Modificam um serviço existente ou adicionam cobranças à conta OCS existente
• Podem executar ações no OCS (adicionar pacote de dados, adicionar crédito, habilitar recurso)
• Não criam novos registros de serviço (ou criam registros de serviço filhos vinculados ao pai)
• Exemplo: Recarga de plano de dados mensal, pacote de roaming internacional, crédito extra

Produtos Agrupados (category: bundle):

• Semelhante aos complementos em termos de variáveis recebidas
• Podem requerer alguns itens de inventário (por exemplo, modem para pacote residencial)
• Criam múltiplos registros de serviço relacionados (Internet + TV + Telefone)
• Provisionam múltiplos recursos em diferentes sistemas
• Vinculam serviços no CRM para faturamento/gerenciamento unificados
• Exemplo: Pacote residencial (Internet + IPTV + telefone VoIP)

Requisitos do Playbook de Provisionamento

Para que um playbook funcione corretamente, ele deve:

1. Estar localizado em OmniCRM-API/Provisioners/plays/{playbook_name}.yaml
2. Aceitar variáveis via extravars do Ansible (acessadas como {{ variable_name }})
3. Autenticar chamadas de API usando Authorization: Bearer {{ access_token }} header
4. Lidar com falhas de forma adequada usando blocos rescue e ignore_errors onde apropriado
5. Criar registro de serviço para produtos autônomos, ou modificar serviço existente para complementos
6. Atribuir inventário se itens de inventário foram selecionados
7. Retornar mensagens de erro significativas via módulo fail quando erros críticos ocorrem

Variáveis Comuns Disponíveis em Playbooks

Todo playbook recebe essas variáveis:

• customer_id - Inteiro, cliente que está solicitando o serviço
• product_id - Inteiro, produto sendo provisionado
• service_id - Inteiro (apenas complementos/pacotes), serviço existente a ser modificado
• access_token - String, token JWT para autenticação da API do CRM
• initiating_user - Inteiro, usuário que acionou o provisionamento
• Além de quaisquer IDs de itens de inventário: {{ inventory_type }}: inventory_id
• Além de quaisquer variáveis de provisioning_json_vars
• Além de quaisquer variáveis passadas na solicitação de provisionamento

Os playbooks podem usar essas para:

• Buscar detalhes completos do produto: GET /crm/product/product_id/{{ product_id }}
• Buscar detalhes do cliente: GET /crm/customer/customer_id/{{ customer_id }}
• Buscar detalhes do inventário: GET /crm/inventory/inventory_id/{{ SIM_Card }}
• Criar transações: POST /crm/transaction/
• Criar serviços: PUT /crm/service/
• Atualizar serviços: PATCH /crm/service/{{ service_id }}
• Atribuir inventário: PATCH /crm/inventory/inventory_id/{{ inventory_id }}

Exemplo: Fluxo de Playbook de Complemento Simples

Para um complemento de recarga de dados móveis:

1. O playbook recebe: customer_id, product_id, service_id, access_token
2. Buscar detalhes do serviço: GET /crm/service/{{ service_id }} para obter service_uuid
3. Buscar detalhes do produto: GET /crm/product/product_id/{{ product_id }} para obter preços e quantidade de dados
4. Cobrar o cliente no OCS: POST para CGRateS para deduzir retail_cost do saldo
5. Adicionar crédito de dados no OCS: POST para CGRateS para adicionar saldo de dados com expiração
6. Registrar transação no CRM: POST /crm/transaction/ com detalhes da cobrança
7. Completar com sucesso

Todo o processo é rastreado nas tabelas Provision e Provision_Event para fins de depuração e auditoria.

Envolvimento do OCS

OCS (Sistema de Cobrança Online), implementado via CGRateS, lida com toda cobrança em tempo real e rastreamento de uso para serviços. O registro de serviço do CRM atua como um ponteiro para a conta OCS, que gerencia:

• Cobranças recorrentes - Taxas mensais, aluguel de DID, cobranças de assinatura
• Cobrança baseada em uso - Chamadas de voz por minuto, dados por MB, cobranças por SMS
• Gerenciamento de saldo - Saldos monetários (crédito pré-pago) e saldos unitários (dados GB, minutos de voz, contagem de SMS)
• Conversões de saldo - Convertendo saldos monetários em saldos unitários (por exemplo, gastando $30 para obter um pacote de dados de 10GB)
• Estado da conta - Ativo, suspenso, desativado com base em limites de crédito e limites

O registro de serviço do CRM contém metadados e configuração (cliente, produto, preços, visibilidade), enquanto o OCS contém o estado de cobrança ao vivo (saldos, uso, cobranças).

Recuperando Uso e Saldos do Serviço

As informações de uso do serviço são recuperadas do OCS/CGRateS e exibidas para clientes e funcionários em tempo real.

Como o Uso é Recuperado

Quando o uso de um serviço é solicitado (via UI ou API), o seguinte fluxo ocorre:

1. Solicitação da API - O frontend chama GET /crm/service/{service_id} ou visualiza detalhes do serviço na UI

2. Busca do Serviço - A API recupera o registro do serviço do banco de dados, extrai service_uuid

3. Chamadas da API CGRateS - O módulo cgrates_service.py faz duas chamadas para CGRateS:

   1. Get_Balance(service_uuid) - Recupera saldo da conta com BalanceMap
      • Retorna saldos organizados por tipo: DADOS, VOZ, SMS, MONETÁRIO, DADOS_DONGLE
      • Cada saldo inclui: ID, Valor, Data de Expiração, Peso, DestinationIDs
      • O sistema adiciona campos legíveis por humanos: custom_Name_hr, custom_Expiration, custom_Description_String
   2. Get_ActionPlans(service_uuid) - Recupera planos de ação de auto-renovação ativos (coberto na próxima seção)

4. Mesclagem de Resposta - Os dados do CGRateS são mesclados na resposta do serviço:

   {
     "service_id": 123,
     "service_name": "Serviço Móvel",
     "service_uuid": "abc-123-def",
     "cgrates": {
       "BalanceMap": {
         "DATA": [{
           "ID": "DATA_10GB",
           "Value": 5368709120,
           "ExpirationDate": "2025-02-01T00:00:00Z",
           "custom_Name_hr": "Pacote de Dados de 10GB",
           "custom_Expiration": "1 de Fevereiro de 2025",
           "custom_Description_String": "5 GB restantes"
         }],
         "VOICE": [{
           "ID": "VOICE_UNLIMITED",
           "Value": 999999999,
           "custom_Name_hr": "Chamadas Ilimitadas",
           "custom_Description_String": "Minutos ilimitados"
         }],
         "MONETARY": [{
           "ID": "PREPAID_CREDIT",
           "Value": 25.50,
           "custom_Description_String": "Crédito de \$25.50"
         }]
       },
       "ActionPlans": [...]
     }
   }

5. Exibição na UI - Componentes do frontend exibem os dados de uso:

   • ServiceUsage.js - Componente principal de exibição de uso com atualização automática a cada 3 segundos
   • UsageCard.js - Cartões de resumo para cada tipo de saldo
   • UsageProgress.js - Barras de progresso mostrando porcentagem usada/restante
   • Os saldos são codificados por cores e formatados para legibilidade

Estrutura de Dados de Uso

Cada saldo no BalanceMap contém:

Campos Nativos do CGRateS:

• ID - Identificador único para o saldo (por exemplo, "DATA_10GB_2025_01")
• Value - Montante do saldo:
  • Para DADOS: bytes (5368709120 = 5 GB)
  • Para VOZ: segundos (3600 = 1 hora)
  • Para SMS: contagem (100 = 100 mensagens)
  • Para MONETÁRIO: unidades de moeda (25.50 = $25.50)
• ExpirationDate - Timestamp ISO 8601 quando o saldo expira
• Weight - Prioridade para consumo de saldo (peso maior consumido primeiro)
• DestinationIDs - Destinos aos quais este saldo se aplica (por exemplo, ["AU", "INTERNATIONAL"])

Campos Legíveis por Humanos (adicionados pelo CRM):

• custom_Name_hr - Nome legível por humanos extraído do ID
• custom_Expiration - Data de expiração formatada (por exemplo, "15 de Jan, 2025" ou "em 11 dias")
• custom_Description_String - Descrição do saldo legível por humanos:
  • DADOS: "5 GB restantes" ou "10 GB totais"
  • VOZ: "60 minutos restantes" ou "Ilimitado"
  • SMS: "50 SMS restantes"
  • MONETÁRIO: "$25.50 de crédito"

Controle de Visibilidade de Uso

A visibilidade do uso do serviço é controlada por dois campos:

• service_visible_to_customer - Se falso, o serviço é ocultado completamente do portal de autoatendimento do cliente
• service_usage_visible_to_customer - Se falso, o serviço é visível mas detalhes de uso/saldo são ocultados (o cliente pode ver que tem o serviço, mas não quanto usou)

Isso permite que os operadores:

• Oculte serviços internos/testes dos clientes
• Mostre que o serviço existe sem revelar o uso (útil para planos ilimitados ou serviços sensíveis)
• Exibição totalmente transparente do uso (padrão)

Atualizações de Uso em Tempo Real

A interface Web atualiza automaticamente os dados de uso:

• Intervalo: A cada 3 segundos (configurável no componente ServiceUsage)
• Método: Faz polling GET /crm/service/{service_id} que busca dados ao vivo do CGRateS
• Eficiência: Apenas visualizações de serviços ativos são atualizadas; visualizações de lista usam dados em cache

Isso garante que clientes e funcionários vejam atualizações de saldo em tempo quase real à medida que o uso ocorre.

Cobranças Recorrentes / AutoRenovação

Cobranças recorrentes, como uma Taxa de Serviço Mensal ou uma Cobrança por DID, são primeiro criadas como Ações dentro do OCS e seguem o formato Action_ServiceUUID_ServiceName_WhatitDoes.

Por exemplo, para um serviço GPON de $60 por mês que inclui 1TB de uso, a Ação seria algo como:

Action_kj49-adsf-1234-9742_60_GPON_1TB_MonthlyExpiry

1. Redefinir Saldo Monetário para $0
2. Enviar um POST HTTP para /simple_provision no CRM para provisionar algo
3. Adicionar um Crédito para 1TB de Uso expirando em 1 mês

Se quisermos que a MRC seja recorrente (queremos), então criaríamos um ActionPlan chamado ActionPlan_{{ service_uuid }}_Monthly_Charge que teria o tempo definido para mensal para acionar todo mês, e atribuir o ActionPlan à conta.

Podemos definir com base no parâmetro Ano / Meses / Dias uma data de expiração para quando a MRC também parará, por exemplo, para um serviço fixo de 12 meses que parou após esse ponto.

Como as Ações e ActionPlans são únicas para o serviço, elas não compartilham nada com outros serviços.

Isso significa que podemos provisioná-los com valores ajustados, e isso não impactará outros serviços.

Complementos e Adicionais

Complementos / Adicionais, como comprar dados extras, pacotes de roaming, minutos internacionais, etc., são tratados de maneira muito semelhante. Uma Ação é criada para fazer o que é necessário, como cobrar um valor monetário e depois conceder um saldo unitário com uma expiração definida.

Em vez de usar ActionPlans para adicionar isso automaticamente à conta, simplesmente acionamos ExecuteAction para a Ação que acabamos de criar uma vez a partir do Ansible.

Adicionando Saldos Monetários Pré-Pagos

Para saldos monetários pré-pagos, como um plano PAYG de $10, isso é adicionado como um saldo monetário, mas com uma prioridade maior.

O limite de crédito nesses serviços para o saldo padrão seria $0.

Limites de Crédito / Prevenindo Gastos Excessivos

ThresholdS são usados em cada conta para definir o gasto máximo para um dado período de tempo.

Para clientes PAYG / Pré-pagos, isso é $0.

Interagindo com OCS via CRM

Para cada Serviço, você pode ver os Balances e ActionPlans, Actions e ThresholdS do OCS a partir da API do CRM.

ActionPlans podem ser removidos conforme necessário da API do CRM, acionados via Playbooks Ansible. ActionPlans podem ser adicionados conforme necessário, a partir do CRM, adicionando um Complemento/Serviço e acionados via Playbooks Ansible.

Contas OCS podem ser desativadas, o que interromperá a execução de ActionPlans e a capacidade de consumir serviços.

Para Limites de Crédito, um valor de ThresholdS é definido conforme a política para o produto.

Visualizando e Gerenciando ActionPlans no CRM

ActionPlans (configurações de auto-renovação) são exibidos e gerenciados através da interface do CRM, permitindo que funcionários e clientes vejam renovações automáticas futuras e as gerenciem.

Como ActionPlans são Recuperados e Exibidos

Ao visualizar um serviço no CRM, ActionPlans são automaticamente buscados e exibidos:

1. Chamada da API - Quando GET /crm/service/{service_id} é chamado, a API:

   • Recupera o registro do serviço do banco de dados
   • Extrai o service_uuid (identificador da conta OCS)
   • Chama get_cgrates_action_plans_by_service_uuid(service_uuid) de cgrates_service.py
   • Isso internamente chama ocs.Get_ActionPlans(service_uuid) para buscar ActionPlans do CGRateS

2. Estrutura de Dados do ActionPlan - Cada ActionPlan retornado contém:

   {
       "ActionPlanId": "ServiceID_abc-123-def__ProductID_456__...",
       "PlanName": "Plano de Renovação Mensal",
       "NextExecTime": "2025-02-01T00:00:00Z",
       "custom_NextExecTime_hr": "em 11 dias",
       "ActionPlanId_split_dict": {
           "ServiceID": "abc-123-def",
           "ProductID": 456,
           "CustomerID": 789,
           ...
       }
   }

   • ActionPlanId - Identificador único contendo informações codificadas de serviço/produto/cliente
   • PlanName - Nome do plano de ação (tipicamente o nome do playbook de renovação)
   • NextExecTime - Timestamp ISO quando o ActionPlan será executado a seguir
   • custom_NextExecTime_hr - Tempo legível por humanos até a execução (por exemplo, "em 11 dias", "amanhã", "1 de Fevereiro de 2025")
   • ActionPlanId_split_dict - Dicionário com componentes analisados do ActionPlanId

3. Exibição na UI - ActionPlans são mostrados no componente ActionPlansTable:

   Colunas da Tabela:

   • Nome do Produto - Recuperado buscando ProductID do ActionPlanId
   • Custo - Mostra retail_cost da definição do produto
   • Data de Renovação - Exibe custom_NextExecTime_hr (legível por humanos)
   • Ações - Dois botões:
     • Renovar Agora - Provisionar imediatamente o complemento/renovação (ignora a espera pela execução agendada)
     • Remover Auto Renovação - Cancela a renovação automática

   Quando Nenhum ActionPlan Existe:

   • A tabela mostra a mensagem: "Nenhuma auto-renovação habilitada para este serviço"
   • O cliente pode adicionar complementos de renovação automática para habilitar a auto-renovação

Gerenciando ActionPlans

Funcionários e clientes podem gerenciar ActionPlans através da interface:

Removendo um ActionPlan (Cancelando Auto-Renovação):

1. Clique no botão "Remover Auto Renovação" na ActionPlansTable
2. Modal de confirmação aparece: "Você tem certeza de que deseja remover esta auto-renovação?"
3. Ao confirmar, o frontend chama: DELETE /crm/oam/remove_action_plan/{action_plan_id}
4. A API remove o ActionPlan do CGRateS via ocs.Remove_ActionPlan()
5. A atividade é registrada: "Removed ActionPlan {ActionPlanId} from service {service_id}"
6. ActionPlan desaparece da tabela

Renovando Imediatamente (Renovação Manual):

1. Clique no botão "Renovar Agora" na ActionPlansTable
2. Modal de confirmação aparece: "Você tem certeza de que deseja renovar isso agora?"
3. Ao confirmar, o sistema:
   • Extrai product_id do ActionPlanId
   • Cria um novo trabalho de provisionamento para esse produto
   • Provisiona o complemento imediatamente (executa o playbook de provisionamento)
   • O serviço recebe os benefícios do complemento sem esperar pela renovação agendada
4. Modal de status de provisionamento mostra progresso
5. Ao sucesso, saldos são atualizados imediatamente

Adicionando Auto-Renovação:

A auto-renovação é habilitada ao provisionar um produto complementar que tem auto_renew definido:

• Produtos com auto_renew = "true" - Criam automaticamente ActionPlans durante o provisionamento
• Produtos com auto_renew = "prompt" - Perguntam ao cliente se ele deseja auto-renovação (diálogo modal)
• Produtos com auto_renew = "false" - Nunca criam ActionPlans (compra única)

O playbook de provisionamento cria o ActionPlan no CGRateS com:

• ActionPlanId único codificando os IDs de serviço, produto e cliente
• Cronograma de renovação (mensal, anual, intervalo personalizado)
• Ação a ser executada (tipicamente reprovisionamento do mesmo complemento)
• Data de expiração (se o contrato tiver um prazo fixo)

Convenção de Nomenclatura de ActionPlan

ActionPlans seguem uma convenção de nomenclatura padronizada para codificar metadados:

Formato:

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

Exemplo:

ServiceID_abc-123-def__ProductID_456__CustomerID_789__MonthlyRenewal

Essa codificação permite que o CRM:

• Identifique a qual serviço o ActionPlan pertence
• Busque detalhes do produto (nome, preços) para exibição
• Rastreie a propriedade do cliente
• Analise o tipo de renovação e cronograma

O CRM analisa automaticamente esses componentes em ActionPlanId_split_dict para fácil acesso.

ActionPlans na Visualização do Serviço

Ao visualizar um serviço no CRM, a tabela de ActionPlans é exibida nos detalhes do serviço:

Visualização do Funcionário (ServiceView.js):

• Mostra a tabela completa de ActionPlans com todas as opções de gerenciamento
• Exibe nomes de produtos, custos, datas de renovação
• Permite remoção e renovação imediata

Visualização de Autoatendimento do Cliente:

• Mostra renovações futuras em uma visualização simplificada
• Exibe a próxima data de renovação e valor
• Pode permitir que clientes desativem a auto-renovação (configurável por produto)

Estado Vazio:

• Se nenhum ActionPlan existir: "Nen