Visão Geral do Inventário no OmniCRM

O sistema de Inventário no OmniCRM é projetado para gerenciar e rastrear tanto itens físicos quanto virtuais usados por operadores de rede e clientes.

Isso significa que podemos rastrear todos os tipos de itens, como modems, números de telefone, blocos de endereços IP ou até mesmo hardware físico como ONTs GPON ou CPEs de Wireless Fixo.

Veja também: Atributos do Cliente para armazenar metadados personalizados, e Tags do Cliente para categorização visual.

Para apoiar clientes com uma pegada de rede fixa, o sistema de inventário também pode rastrear residências atendidas para um determinado serviço, permitindo que os operadores realizem a qualificação de serviço remotamente, e para aqueles que operam uma rede wireless fixa, podemos rastrear os CPEs implantados em campo com suas localizações.

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

Os itens de inventário estão vinculados a produtos durante o provisionamento através do campo inventory_items_list. Para um guia completo de como o inventário se integra ao provisionamento de produtos, incluindo a interface do usuário do seletor de inventário e a integração do playbook do Ansible, veja Guia Completo do Ciclo de Vida do Produto - Requisitos de Inventário. :::

Propósito

O Inventário do OmniCRM serve a vários propósitos principais:

1. Provisionamento de Serviços: Quando um cliente se inscreve para um serviço, itens como modems, cartões SIM ou números de telefone podem precisar ser alocados. O sistema de inventário rastreia esses itens e os associa aos clientes.
2. Gerenciamento de Estoque: Para estoque físico, como hardware ou outros equipamentos, o inventário ajuda os operadores a manter visibilidade sobre o que está disponível, onde está armazenado e o que foi alocado ou vendido para os clientes.
3. Alocação de Clientes: O sistema permite que itens sejam alocados a clientes, seja para uso em um serviço (por exemplo, atribuindo um modem à conta de internet de um cliente) ou para venda direta.
4. Qualificação de Serviço / Pegada de Rede: Ao armazenar informações sobre a pegada da rede, como cada residência atendida para um serviço GPON, ou cada CPE de Wireless Fixo implantado, permite que a equipe faça a qualificação de serviço remotamente e veja se há uma pegada de rede em uma área específica.

Exemplo do Ciclo de Vida do Inventário

Para ilustrar como o sistema de Inventário funciona, considere os seguintes exemplos.

Exemplo de Cartão SIM

Um lote de 1000 cartões SIM é encomendado da Omnitouch. Primeiramente, um Modelo de Inventário é criado para cartões SIM (se ainda não existir) e os SIMs encomendados são carregados no Inventário no estado Em Trânsito.

Uma vez que os SIMs são recebidos, eles são marcados como Em Estoque, e podem ser alocados para diferentes lojas de varejo, com a Localização do item de inventário atualizada para refletir em qual loja de varejo cada cartão SIM está - Isso é útil para rastrear os níveis de estoque em cada loja e garantir que cada loja tenha estoque suficiente para atender à demanda dos clientes.

Quando um cliente se inscreve para um serviço móvel na loja, um cartão SIM é alocado ao cliente e o status é alterado para Alocado. O item de inventário do cartão SIM é então atribuído ao cliente, e o status é atualizado para Em Uso.

Se o cliente cancelar o serviço ou o serviço ficar inativo, o cartão SIM é marcado como Descomissionado.

Exemplo de Residências Atendidas GPON

Para uma rede GPON, o sistema de inventário pode rastrear cada residência atendida para um determinado serviço.

Quando uma nova área é construída, cada endereço atendido pode ser adicionado ao inventário.

Isso permite que os operadores vejam quais residências são atendidas para um determinado serviço e quais residências ainda não foram atendidas.

Quando um cliente se inscreve para um serviço, o OmniCRM pode automaticamente executar uma qualificação de serviço contra o endereço do cliente, para ver se o endereço está no inventário de residências atendidas e quais serviços podem ser oferecidos.

Modelos de Inventário

O recurso InventoryTemplate permite a criação de qualquer número de tipos de itens com campos predefinidos. Esses modelos atuam como plantas que definem as características essenciais de diferentes itens, como:

• Modems com um endereço MAC (itemtext1) e um número de série (itemtext2).
• Residências Atendidas para um determinado serviço, com uma localização e status (por exemplo, atendido ou não atendido).
• Números de Telefone com um número principal (itemtext1) e uma localização geográfica (itemtext2).
• Recursos Virtuais como blocos de endereços IP, com identificadores mapeados através do modelo.

Cada modelo de inventário define até 20 campos de texto personalizáveis (itemtext1 a itemtext20) com rótulos correspondentes (itemtext1_label a itemtext20_label) que descrevem o que cada campo representa. Por exemplo, um modelo de Modem pode definir itemtext1_label como "Endereço MAC" e itemtext2_label como "Número de Série".

Os operadores podem personalizar os campos para cada tipo de item usando InventoryTemplates. Esses modelos permitem que os itens sejam categorizados e gerenciados de forma estruturada, garantindo consistência em como os itens são rastreados.

Vinculando a Produtos:

Os nomes dos modelos de inventário são referenciados nas definições de produtos através do campo inventory_items_list. Ao provisionar um produto, o sistema exibe um seletor de inventário mostrando apenas itens que correspondem aos tipos de modelos exigidos.

Exemplo: Um produto com inventory_items_list: "['Cartão SIM', 'Número Móvel']" requer que dois modelos de inventário com os nomes exatamente "Cartão SIM" e "Número Móvel" existam. Os nomes dos modelos são sensíveis a maiúsculas e minúsculas.

Para detalhes completos sobre como os modelos de inventário se conectam ao provisionamento de produtos, veja Produto Ciclo de Vida - Requisitos de Inventário.

Criando Modelos de Inventário via a UI

Para criar um novo modelo de inventário:

1. Navegue até Inventário → Modelos no menu principal

2. Clique no botão Adicionar Modelo

3. Preencha os campos obrigatórios:

   Informações Básicas:

   • Ícone (opcional): Nome da classe do ícone para identificação visual (por exemplo, fa-solid fa-sim-card)
   • Item (obrigatório): O nome do modelo (deve corresponder exatamente ao que é usado em inventory_items_list para produtos)

   Informações de Custo (Obrigatório):

   • Custo por Atacado (obrigatório): Seu custo para comprar ou provisionar este tipo de item
   • Custo de Varejo (obrigatório): Preço de varejo padrão se vendido separadamente para clientes

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

   Os custos por atacado e de varejo definidos aqui servem como valores padrão ao criar novos itens de inventário a partir deste modelo. Itens de inventário individuais podem ter custos diferentes, se necessário. :::

   Rótulos de Campo:

   • Rótulo do Texto do Item 1 (obrigatório): Rótulo para o primeiro campo personalizável (padrão para "Número do Modelo")
     • Exemplos comuns: "ICCID" para cartões SIM, "Endereço MAC" para modems, "Número de Telefone" para números
   • Rótulo do Texto do Item 2 (obrigatório): Rótulo para o segundo campo personalizável (padrão para "Número de Série")
     • Exemplos comuns: "IMSI" para cartões SIM, "Número de Série" para hardware, "Região Geográfica" para números
   • Rótulos do Texto do Item 3-20 (opcional): Rótulos de campo adicionais conforme necessário
     • Clique em Adicionar Campo para adicionar mais campos personalizados
     • Adicione apenas campos que você realmente usará para este tipo de item

   Configurações de Visibilidade:

   • Permitir Dropdown para Funcionários: Permitir que os funcionários selecionem este tipo de inventário em dropdowns
   • Permitir Dropdown para Clientes: Permitir que os clientes vejam/selecionem este tipo de inventário (portal do cliente)

4. Clique em Salvar para criar o modelo

Editando Modelos de Inventário

Para editar um modelo existente:

1. Navegue até Inventário → Modelos
2. Encontre o modelo na lista
3. Clique no botão Editar
4. Modifique os campos conforme necessário
5. Clique em Salvar

::: warning ::: title Aviso :::

Alterar rótulos de campo (por exemplo, itemtext1_label) afeta apenas novos itens criados após a alteração. Itens de inventário existentes mantêm seus dados, mas serão exibidos com os novos nomes de rótulo. :::

::: caution ::: title Cuidado :::

Nomes de modelos referenciados nos campos inventory_items_list de produtos são sensíveis a maiúsculas e minúsculas. Renomear um modelo quebrará o link para produtos que usam o nome antigo. :::

Exemplos Comuns de Modelos

Modelo de Cartão SIM:

• Item: "Cartão SIM"
• Custo por Atacado: 2.50
• Custo de Varejo: 10.00
• Rótulo do Texto do Item 1: "ICCID"
• Rótulo do Texto do Item 2: "IMSI"
• Rótulo do Texto do Item 3: "Tipo de SIM" (Físico/eSIM)

Modelo de Número Móvel:

• Item: "Número Móvel"
• Custo por Atacado: 1.00
• Custo de Varejo: 0.00
• Rótulo do Texto do Item 1: "Número de Telefone"
• Rótulo do Texto do Item 2: "Região Geográfica"
• Rótulo do Texto do Item 3: "Tipo de Número" (Móvel/Fixo)

Modelo de CPE Wireless Fixo:

• Item: "CPE Wireless Fixo"
• Custo por Atacado: 250.00
• Custo de Varejo: 450.00
• Rótulo do Texto do Item 1: "Endereço MAC"
• Rótulo do Texto do Item 2: "Número de Série"
• Rótulo do Texto do Item 3: "Versão do Firmware"
• Rótulo do Texto do Item 4: "Fabricante"
• Rótulo do Texto do Item 5: "Modelo"

Modelo de ONT GPON:

• Item: "ONT GPON"
• Custo por Atacado: 45.00
• Custo de Varejo: 0.00 (incluído com o serviço)
• Rótulo do Texto do Item 1: "Número de Série"
• Rótulo do Texto do Item 2: "Endereço MAC"
• Rótulo do Texto do Item 3: "Localização PON"
• Rótulo do Texto do Item 4: "Modelo"

Criando e Gerenciando Itens de Inventário

Uma vez que um InventoryTemplate é definido, itens individuais de Inventário podem ser criados. Cada item de inventário representa uma instância específica de um tipo de item (por exemplo, um modem ou número de telefone específico) que pode ser:

• Alocado a Clientes: Itens estão vinculados a clientes para provisionamento de serviço (por exemplo, atribuindo hardware para uma conexão de internet).
• Rastreado para Estoque: Os operadores podem monitorar o inventário disponível, como itens não vendidos ou não atribuídos.
• Vendidos ou Descomissionados: Uma vez vendidos, os itens são marcados com timestamps relevantes (por exemplo, sold_date) e não podem mais ser considerados estoque disponível.

Através deste sistema, o OmniCRM facilita o gerenciamento eficiente de estoque, ajuda a alocar recursos para clientes e fornece visibilidade detalhada sobre o status e a história de cada item.

Serviços podem ser vinculados a um determinado item de Inventário, permitindo um rastreamento fácil de quais itens estão associados a quais clientes ou serviços.

Uma vez que um item de inventário foi atribuído a um cliente, os plays do Ansible podem atualizar o status e a história do item para refletir a alocação. Isso garante que os operadores tenham um registro preciso de quais itens estão em uso e quais estão disponíveis para alocação, além de saber qual cliente está usando qual item.

Podemos visualizar itens alocados a um cliente a partir da página de perfil do cliente na aba Inventário.

Para itens de Inventário vinculados a um Serviço, podemos ver isso editando o serviço, para ver os itens de Inventário vinculados.

Campos do Item de Inventário

Cada item de inventário contém informações abrangentes organizadas em várias categorias:

Informações Básicas do Item

• inventory_id - Identificador único para o item de inventário (gerado automaticamente)
• item - Tipo de item (corresponde ao nome do Modelo de Inventário, por exemplo, "Cartão SIM", "Modem", "Número de Telefone")
• inventory_template_id - Link para o Modelo de Inventário que define este tipo de item
• customer_id - Se atribuído a um cliente, o ID do cliente (nulo)
• service_id - Se vinculado a um serviço específico, o ID do serviço (nulo)
• item_location - Localização física ou lógica do item:
  • Para itens físicos: prédio, armazém, localização da prateleira, nome da loja, etc.
  • Para itens virtuais: localização geográfica, localização do bloco IP, região de faixa de número, etc.
• item_state - Estado atual do item de inventário (valores enumerados):
  • Novo - Item novo, não utilizado
  • Usado - Anteriormente usado, mas funcional
  • Uso Interno - Alocado para testes internos ou uso da equipe
  • Atribuído - Atualmente atribuído a um cliente ou serviço
  • Danificado - Não funcional, requer reparo ou descarte
  • Fora de Serviço - Temporariamente indisponível
  • Perdido - Item não pode ser localizado
  • Roubado - Item foi roubado

Campos Personalizáveis do Item (do Modelo)

O sistema de inventário suporta até 20 campos de texto personalizáveis cujo significado é definido pelo Modelo de Inventário:

• itemtext1 - Primeiro campo personalizável (obrigatório, rótulo definido pelo itemtext1_label do modelo)
  • Exemplo: Para modems, pode ser "Endereço MAC"
  • Exemplo: Para cartões SIM, pode ser "ICCID"
  • Exemplo: Para números de telefone, pode ser "Número de Telefone"
• itemtext2 até itemtext20 - Campos personalizáveis adicionais (opcional, rótulos definidos pelo modelo)
  • Exemplo: itemtext2 para modems pode ser "Número de Série"
  • Exemplo: itemtext2 para cartões SIM pode ser "IMSI"
  • Exemplo: itemtext3 para modems pode ser "Versão do Firmware"

Cada Modelo de Inventário define quais desses campos são usados e o que representam através dos campos de rótulo correspondentes (itemtext1_label, itemtext2_label, etc.).

Informações de Custo

• wholesale_cost - Seu custo para comprar/provisionar este item (float)
• retail_cost - Preço cobrado ao cliente se vendido separadamente (float)
• sold_date - Timestamp quando o item foi vendido ou atribuído ao cliente

Endereço Físico (para Equipamentos e Locais de Rede)

Usado para rastrear locais de implantação física, particularmente para equipamentos de rede fixa (CPEs, ONTs, modems) ou residências atendidas:

• address_line_1 - Endereço da rua, número do prédio, número da unidade
• address_line_2 - Informações adicionais do endereço (suíte, apartamento, andar)
• city - Cidade ou município
• state - Estado, província ou região
• zip_code - Código postal/ZIP
• country - Nome do país

Localização Geográfica (Preenchido Automaticamente pela Web UI)

Ao criar itens de inventário via a Web UI com autocomplete de endereço, esses campos são preenchidos automaticamente:

• google_maps_place_id - Google Maps Place ID para o endereço
• plus_code - Google Maps Plus Code (Open Location Code) para localização precisa
• latitude - Latitude geográfica (graus decimais)
• longitude - Longitude geográfica (graus decimais)

Esses campos possibilitam:

• Mapeamento de locais de inventário em uma visualização de mapa
• Cálculos de proximidade para qualificação de serviço
• Análise de cobertura para planejamento de rede
• Otimização de rotas para despacho de técnicos de campo

Gerenciamento de Dispositivos e URLs de Acesso

O campo management_url fornece acesso rápido às interfaces de dispositivos e URLs de provisionamento:

• management_url - URL de acesso para o item de inventário

  • Equipamentos de Rede: URL da interface web (por exemplo, https://192.168.1.1 para roteadores, switches, ONTs, CPEs)
  • Perfis eSIM: endereço LPA (Local Profile Assistant) para ativação de eSIM (por exemplo, LPA:1$smdp.example.com$ACTIVATION-CODE-HERE)
  • Outros Casos de Uso: Qualquer URL que precise ser facilmente acessível via dispositivo móvel

  Geração de QR Code

  Ao visualizar itens de inventário com um management_url, o sistema gera automaticamente um QR code escaneável:

  • Visualização de detalhes do item de inventário: QR code 128x128 exibido ao lado da URL
  • Tabela de inventário de serviços: QR code 64x64 mostrado para itens atribuídos
  • Formato: Tanto o QR code quanto o hyperlink clicável exibidos juntos

  Casos de Uso Comuns

  • Técnicos de Rede: Escaneie o QR code para acessar a interface de gerenciamento do dispositivo sem digitar endereços IP
  • Ativação de eSIM: Clientes escaneiam o QR code do CRM para instalar o perfil eSIM em seu dispositivo
  • Autoatendimento do Cliente: Fornecer fácil acesso à configuração do dispositivo ou portais de clientes

• management_username - Nome de usuário admin para acesso ao dispositivo

• management_password - Senha admin para acesso ao dispositivo (criptografada em repouso)

Gerenciamento de Configuração

Para dispositivos com arquivos de configuração:

• config_content - Conteúdo completo do arquivo de configuração (armazenado como texto)
  • Útil para backup, versionamento e recuperação de desastres
  • Pode armazenar configurações de roteadores, configurações de switches, configurações de CPEs, etc.
• config_file_path - Caminho para o arquivo de configuração externo se armazenado separadamente
  • Alternativa ao armazenamento da configuração completa no banco de dados
  • Caminho para compartilhamento de rede, repositório de controle de versão ou sistema de gerenciamento de configuração

Notas e Metadados

• inventory_notes - Notas em formato livre sobre o item de inventário
  • Notas de instalação
  • Histórico de manutenção
  • Particularidades ou requisitos especiais de manuseio
  • Informações do fornecedor
  • Detalhes da garantia
• created - Timestamp quando o item de inventário foi criado no sistema (definido automaticamente)
• last_modified - Timestamp da última atualização do item de inventário (atualizado automaticamente)

Exemplos de Uso de Campo

Exemplo 1: Cartão SIM Móvel

{
  "inventory_id": 1001,
  "item": "Cartão SIM",
  "inventory_template_id": 5,
  "itemtext1": "8961234567890123456",
  "itemtext2": "310120123456789",
  "itemtext3": "Físico",
  "item_location": "Armazém A, Prateleira 3",
  "item_state": "Atribuído",
  "customer_id": 456,
  "service_id": 789,
  "wholesale_cost": 2.50,
  "retail_cost": 10.00,
  "sold_date": "2025-01-15T10:30:00Z",
  "inventory_notes": "Ativado em 2025-01-15"
}

Exemplo 2: Perfil eSIM Móvel

{
  "inventory_id": 1002,
  "item": "eSIM",
  "inventory_template_id": 6,
  "itemtext1": "8961234567890123457",
  "itemtext2": "310120123456790",
  "itemtext3": "eSIM",
  "item_location": "Inventário Virtual",
  "item_state": "Atribuído",
  "customer_id": 457,
  "service_id": 790,
  "management_url": "LPA:1$smdp.example.com$ACTIVATION-CODE-ABC123XYZ",
  "wholesale_cost": 0.00,
  "retail_cost": 0.00,
  "sold_date": "2025-01-16T14:20:00Z",
  "inventory_notes": "Perfil eSIM pronto para ativação"
}

Ao visualizar este item de inventário eSIM, a UI exibe um QR code contendo o endereço LPA. Os clientes escaneiam este QR code com seu dispositivo móvel para instalar o perfil eSIM.

Exemplo 3: Equipamento de Cliente (CPE) - Wireless Fixo

{
  "inventory_id": 2001,
  "item": "CPE Wireless Fixo",
  "inventory_template_id": 10,
  "itemtext1": "AA:BB:CC:DD:EE:FF",
  "itemtext2": "FW2024-12345",
  "itemtext3": "v2.4.1",
  "itemtext4": "Ubiquiti",
  "itemtext5": "LiteBeam AC Gen2",
  "item_location": "Local do Cliente",
  "item_state": "Atribuído",
  "customer_id": 789,
  "service_id": 1234,
  "address_line_1": "123 Main Street",
  "address_line_2": "Apt 4B",
  "city": "Sydney",
  "state": "NSW",
  "zip_code": "2000",
  "country": "Austrália",
  "latitude": "-33.8688",
  "longitude": "151.2093",
  "management_url": "https://192.168.100.1",
  "management_username": "admin",
  "management_password": "encrypted_password_here",
  "config_file_path": "/configs/cpe/fw2024-12345.conf",
  "inventory_notes": "Instalado em 2025-01-10. Cliente relata excelente sinal. Direcionamento: Azimute 45°, Elevação 15°"
}

Exemplo 4: ONT GPON com Endereço Completo

{
  "inventory_id": 3001,
  "item": "ONT GPON",
  "inventory_template_id": 15,
  "itemtext1": "ALCL12345678",
  "itemtext2": "AA:BB:CC:DD:EE:FF",
  "itemtext3": "OLT-1, PON 3, ONT 42",
  "itemtext4": "Nokia G-010G-A",
  "item_location": "Instalações do Cliente",
  "item_state": "Atribuído",
  "customer_id": 321,
  "service_id": 654,
  "address_line_1": "456 Fiber Lane",
  "city": "Melbourne",
  "state": "VIC",
  "zip_code": "3000",
  "country": "Austrália",
  "google_maps_place_id": "ChIJ1234567890",
  "plus_code": "4RRH+2C Melbourne VIC",
  "latitude": "-37.8136",
  "longitude": "144.9631",
  "management_url": "https://192.168.1.1",
  "management_username": "admin",
  "config_content": "# Configuração do ONT\nwlan-ssid: HomeNetwork\nwlan-password: encrypted...",
  "wholesale_cost": 45.00,
  "retail_cost": 0.00,
  "inventory_notes": "Provisionado em 2025-01-20. Potência óptica: -22dBm"
}

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

Ao visualizar itens de inventário com um management_url (como os Exemplos 2, 3 e 4 acima), a UI exibe automaticamente:

• Um QR code escaneável contendo a URL ou endereço LPA
• Um hyperlink clicável (para URLs da web)

Casos de Uso:

• Ativação de eSIM (Exemplo 2): Clientes escaneiam o QR code para instalar o perfil eSIM em seu dispositivo
• Acesso a Equipamentos de Rede (Exemplos 3 e 4): Técnicos escaneiam para acessar interfaces de gerenciamento de dispositivos sem digitar manualmente endereços IP :::

Exemplo 5: Número de Telefone (Inventário Virtual)

{
  "inventory_id": 4001,
  "item": "Número de Telefone",
  "inventory_template_id": 20,
  "itemtext1": "+61412345678",
  "itemtext2": "Melbourne",
  "itemtext3": "Móvel",
  "item_location": "Austrália - VIC",
  "item_state": "Atribuído",
  "customer_id": 555,
  "service_id": 888,
  "wholesale_cost": 1.00,
  "retail_cost": 0.00,
  "inventory_notes": "Portado da Telstra em 2025-01-05"
}

Estados do Item de Inventário Explicados

O campo item_state rastreia o ciclo de vida dos itens de inventário:

• Novo → Atribuído - Fluxo normal ao provisionar para um cliente
• Atribuído → Usado - Após a desativação do serviço, o item pode ser reutilizado
• Novo → Uso Interno - Alocado para testes, demonstrações ou uso da equipe
• Atribuído → Danificado - O item falhou, requer RMA ou descarte
• Qualquer Estado → Perdido - O item não pode ser localizado (gera auditoria)
• Qualquer Estado → Roubado - O item foi roubado (gera relatório de segurança)
• Danificado/Usado → Novo - Após reforma ou reparo

Filtrar e pesquisar inventário por estado permite que os operadores:

• Rastrear estoque disponível (itens Novos)
• Identificar itens atribuídos a clientes (Atribuído)
• Encontrar itens disponíveis para reutilização (Usado)
• Monitorar problemas de equipamentos (Danificado, Fora de Serviço)
• Auditar itens faltantes (Perdido, Roubado)