Provisionamento de Cartões SIM

OmniCRM oferece suporte abrangente para o provisionamento de cartões SIM físicos e eSIMs (SIMs embutidos) para operadores de rede móvel e MVNOs. O sistema gerencia todo o ciclo de vida, desde a gestão de inventário até a ativação, atribuição e desprovisionamento.

Veja também: Sistema de Provisionamento para conceitos gerais de provisionamento, Inventário para gestão de inventário, Playbooks Ansible para automação de provisionamento.

Visão Geral

O provisionamento de SIMs no OmniCRM envolve vários sistemas integrados trabalhando juntos:

1. Gestão de Inventário - Rastreia cartões SIM disponíveis (físicos e perfis de eSIM)
2. Integração HSS/IMS - Provisões de credenciais de assinante e serviços de voz
3. Integração OCS - Configura cobrança e tarifação para o serviço
4. Automação Ansible - Orquestra o fluxo de trabalho de provisionamento
5. Suporte a Auto-Cadastro - Permite que os clientes ativem seus próprios SIMs

Provisionamento de Cartão SIM Físico

Os cartões SIM físicos são cartões SIM removíveis tradicionais que os clientes inserem em seus dispositivos. O OmniCRM gerencia esses cartões através do sistema de inventário e os provisiona para o HSS/IMS para acesso à rede.

Fluxo de Trabalho do SIM Físico

1. Configuração do Inventário

Os cartões SIM devem ser carregados no sistema de inventário:

• ICCID (Identificador de Circuito Integrado do Cartão) - Identificador único do cartão SIM
• IMSI (Identidade Internacional do Assinante Móvel) - Identidade do assinante para a rede

Esses dados são armazenados nos campos de itens do inventário:

• itemtext1: ICCID
• itemtext2: IMSI
• itemtext3: Tipo de SIM (Físico/eSIM) - opcional

Exemplo de Item de Inventário de SIM Físico:

{
  "inventory_id": 1001,
  "item": "SIM Card",
  "itemtext1": "8961234567890123456",  // ICCID
  "itemtext2": "310120123456789",      // IMSI
  "itemtext3": "Physical",              // Tipo de SIM
  "item_location": "Warehouse A, Shelf 3",
  "item_state": "New",
  "wholesale_cost": 2.50,
  "retail_cost": 10.00
}

Para uma explicação completa de todos os campos de inventário (itemtext1-20, valores de item_state, campos de endereço, management_url, etc.), veja Visão Geral do Inventário - Campos de Itens do Inventário.

Armazenamento de Credenciais de Autenticação

As credenciais de autenticação para cartões SIM são armazenadas no HSS AuC (Centro de Autenticação), não no inventário do CRM:

• Ki (Chave de Autenticação) - Chave secreta para autenticação (armazenada no HSS)
• OPC (Código do Operador) - Parâmetro de autenticação específico do operador (armazenado no HSS)
• PIN1/PIN2 - Códigos PIN do usuário (armazenados no HSS)
• PUK1/PUK2 - Códigos de desbloqueio PIN (armazenados no HSS)

O inventário do CRM rastreia qual SIM (por ICCID/IMSI) está atribuído a qual cliente, enquanto o HSS lida com a autenticação real da rede usando as credenciais Ki/OPC que correspondem ao cartão SIM físico.

2. Atribuição de Serviço

Quando um cliente solicita um serviço móvel:

1. O funcionário ou cliente seleciona um cartão SIM disponível do inventário
2. Um número de telefone (MSISDN) é selecionado do inventário de números de telefone
3. O playbook de provisionamento do produto é acionado (por exemplo, play_psim_only.yaml)

3. Provisionamento HSS

O playbook Ansible provisiona o assinante para o Servidor de Assinantes Doméstico (HSS):

Primeiro, ele recupera o auc_id (referência às credenciais de autenticação já armazenadas no HSS):

- name: Get AuC ID for IMSI
  uri:
    url: "{{ item }}/auc/imsi/{{ imsi }}"
    method: GET
  loop: "{{ hss_peers }}"
  register: auc_lookup

- name: Extract auc_id
  set_fact:
    auc_id: "{{ auc_lookup.results[0].json.auc_id }}"

Em seguida, cria o registro do assinante referenciando esse auc_id:

- name: Provision subscriber on HSS
  uri:
    url: "{{ item }}/subscriber/"
    method: PUT
    body_format: json
    body:
      enabled: true
      roaming_enabled: true
      auc_id: "{{ auc_id }}"
      msisdn: "{{ phone_number }}"
      imsi: "{{ imsi }}"
      ue_ambr_dl: 9999999
      ue_ambr_ul: 9999999
      apn_list: "1,2,3"
      default_apn: 1
  loop: "{{ hss_peers }}"

As credenciais de autenticação (Ki, OPC) permanecem no HSS AuC e nunca são expostas ao CRM ou aos playbooks de provisionamento.

4. Provisionamento IMS (para Serviços de Voz)

Para a capacidade de chamadas de voz, um assinante IMS é criado:

- name: Create IMS subscriber for voice services
  uri:
    url: "{{ item }}/ims_subscriber/"
    method: PUT
    body_format: json
    body:
      imsi: "{{ imsi }}"
      msisdn: "{{ phone_number }}"
      msisdn_list: "{{ phone_number }}"
      ifc_path: "default_ifc.xml"
      sh_profile: "{{ sh_profile_xml }}"
  loop: "{{ hss_peers }}"

5. Configuração do Sistema de Cobrança

O OCS (Sistema de Cobrança Online) é configurado com:

• Criação de conta
• Mapeamento IMSI/MSISDN via perfis de atributos
• Regras de filtro para identificar o assinante
• Limites de recursos (sessões simultâneas)
• Saldo inicial

6. Criação de Serviço e Atribuição de Inventário

Finalmente:

• Um registro de serviço é criado no CRM
• O item de inventário do cartão SIM é atribuído ao cliente (customer_id definido)
• O cartão SIM é vinculado ao serviço (service_id definido)
• O estado do inventário é atualizado para "Assigned"

Autenticação de SIM Físico

Os SIMs físicos usam credenciais do AuC (Centro de Autenticação) armazenadas no HSS:

• Ki e OPC são usados para autenticação 4G/5G (algoritmo MILENAGE)
• Essas credenciais são pré-carregadas no banco de dados AuC do HSS durante a importação do SIM
• O cartão SIM físico contém valores correspondentes de Ki/OPC
• Durante o provisionamento, o playbook referencia o auc_id para vincular o assinante a essas credenciais
• A autenticação na rede ocorre por meio de desafio-resposta entre o SIM e o HSS
• O CRM nunca vê ou manipula os valores reais de Ki/OPC

Provisionamento de eSIM

eSIMs (SIMs embutidos) são perfis de SIM baseados em software que podem ser baixados para dispositivos compatíveis sem cartões SIM físicos. O OmniCRM suporta o provisionamento de eSIM com códigos de ativação LPA (Assistente de Perfil Local).

Recursos do eSIM

Códigos de Ativação LPA

Os eSIMs usam códigos LPA para ativação:

LPA:1$smdp.example.com$ACTIVATION-CODE-ABC123XYZ

Onde:

• LPA:1 - Identificador da versão LPA
• smdp.example.com - Endereço do servidor SM-DP+ (Gerenciamento de Dados de Assinatura)
• ACTIVATION-CODE-ABC123XYZ - Código de ativação exclusivo para este perfil de eSIM

Geração de QR Code

O OmniCRM gera automaticamente QR codes a partir dos códigos de ativação LPA:

• Armazenados no campo management_url do inventário
• Exibidos na interface como QR code escaneável
• Os clientes escaneiam com a câmera de seus dispositivos para instalar o perfil de eSIM
• Não é necessário digitar manualmente longos códigos de ativação

Exemplo de Item de Inventário de eSIM:

{
  "inventory_id": 1002,
  "item": "eSIM",
  "itemtext1": "8961234567890123457",
  "itemtext2": "310120123456790",
  "itemtext3": "eSIM",
  "management_url": "LPA:1$smdp.example.com$ACTIVATION-CODE-ABC123XYZ",
  "item_location": "Virtual Inventory",
  "item_state": "New",
  "wholesale_cost": 0.00,
  "retail_cost": 0.00
}

Ao visualizar este item de inventário na interface, um QR code é gerado automaticamente e exibido para fácil escaneamento.

Fluxo de Trabalho de Provisionamento de eSIM

O fluxo de trabalho de provisionamento de eSIM é quase idêntico ao provisionamento de SIM físico, com algumas diferenças principais:

1. Atribuição Automática de eSIM

Se um produto requer um SIM, mas nenhum SIM físico é selecionado, o sistema pode atribuir automaticamente um eSIM disponível:

# Pesquisa automática de eSIM
search_filters = {
    "customer_id": [None],
    "item_state": ["New"],
    "itemtext3": ["eSIM"]  # Filtro para tipo eSIM
}
available_esim = search_inventory("SIM Card", filters=search_filters)

2. Provisionamento HSS/IMS

Os eSIMs são provisionados para HSS/IMS exatamente como os SIMs físicos:

• Mesmo provisionamento IMSI
• Mesma criação de assinante IMS
• Mesmas credenciais de autenticação (Ki, OPC)

3. Ativação do Cliente

Após o provisionamento:

1. O cliente recebe os detalhes de ativação do eSIM por e-mail ou no portal do cliente
2. O QR code é exibido para escaneamento
3. O cliente escaneia o QR code com seu dispositivo
4. O dispositivo baixa o perfil de eSIM do servidor SM-DP+
5. O eSIM é instalado e pronto para uso

API Pública do Emissor de eSIM

O OmniCRM fornece um endpoint de API pública para solicitações de eSIM de autoatendimento, permitindo que os clientes solicitem um eSIM diretamente de um site ou aplicativo móvel sem intervenção da equipe.

Endpoint: POST /crm/oam/issue-esim

Parâmetros da Solicitação

Parâmetro	Tipo	Requerido	Padrão	Descrição
email	String	Sim	-	Endereço de e-mail do cliente para entrega do eSIM. Deve ser um formato de e-mail válido.
name	String	Não	Derivado do e-mail	Nome do cliente para personalização do e-mail. Se não fornecido, a parte local do endereço de e-mail é usada.
customer_id	Inteiro	Não	null	ID de cliente existente. Quando fornecido, cria um registro de atividade vinculado ao cliente para rastreamento.
device_info	Objeto	Não	{}	Informações do dispositivo para análise e rastreamento de compatibilidade.
device_info.compatibility_status	String	Não	"unknown"	Status de compatibilidade do eSIM: supported, may-support ou unknown. Usado para análise.
device_info.user_agent	String	Não	Cabeçalho de solicitação	String do agente do usuário. Capturado automaticamente dos cabeçalhos de solicitação se não fornecido.

Limitação de Taxa

O endpoint implementa limitação de taxa dupla para prevenir abusos:

Limite	Janela	Escopo	Descrição
10 solicitações	1 minuto	Por endereço IP	Limite de taxa geral aplicado via decorador
3 solicitações	24 horas	Por endereço de e-mail	Previne solicitações excessivas de eSIM para o mesmo e-mail

Quando os limites de taxa são excedidos, o endpoint retorna HTTP 429 com error_type: "RateLimitExceeded".

Formato de Resposta

Resposta de Sucesso (HTTP 200):

{
  "result": "Success",
  "message": "eSIM request received. You will receive your eSIM QR code via email shortly.",
  "esim_id": 8472,
  "iccid": "8944200000001234567",
  "email_sent": true
}

Campo	Tipo	Descrição
result	String	Sempre "Success" para respostas HTTP 200
message	String	Mensagem de confirmação legível por humanos
esim_id	Inteiro	O ID do inventário do eSIM atribuído
iccid	String	O ICCID do eSIM atribuído
email_sent	Booleano	Se o e-mail de entrega foi enviado com sucesso

Respostas de Erro

Código HTTP	Tipo de Erro	Descrição
400	-	Endereço de e-mail inválido ou ausente
429	RateLimitExceeded	Limite de taxa por e-mail ou por IP excedido
503	NoInventory	Sem eSIMs disponíveis no inventário
500	-	Erro interno do servidor

Formato de Resposta de Erro:

{
  "result": "Failed",
  "reason": "Error description",
  "error_type": "ErrorType"
}

Entrega de E-mail

O endpoint envia um e-mail de entrega de eSIM via Mailjet contendo:

• ICCID
• QR code (se disponível em itemtext2)
• Código de ativação/string LPA (se disponível em itemtext3 ou management_url)
• Instruções de ativação passo a passo

Configure o modelo Mailjet em crm_config.yaml:

mailjet:
  api_crmCommunicationEsimDelivery:
    from_email: "support@aimobile.ac"
    from_name: "Ascension Island Mobile"
    template_id: 1234567
    subject: "Your eSIM is Ready"

Parâmetro	Tipo	Requerido	Descrição
from_email	String	Sim	Endereço de e-mail do remetente
from_name	String	Sim	Nome de exibição do remetente
template_id	Inteiro	Não	ID do modelo Mailjet. Se não fornecido, um e-mail HTML padrão é gerado.
subject	String	Sim	Linha de assunto do e-mail

Se nenhum modelo estiver configurado, o sistema gera um e-mail HTML com marca da empresa contendo:

• Marca e logotipo da empresa
• QR code para ativação do eSIM (se disponível)
• Instruções de código de ativação manual
• Orientações de configuração específicas para iOS e Android

Registro de Atividades

Cada solicitação de eSIM cria um registro de atividade com:

• Tipo de atividade: esim_request
• Vínculo ao ID do cliente (se fornecido)
• Status de compatibilidade do dispositivo
• Informações do agente do usuário

Isso permite o rastreamento de solicitações de eSIM e análises de conversão.

4. Estrutura de Dados do eSIM no HSS

Os eSIMs no HSS AuC (Centro de Autenticação) são marcados com uma flag esim: true:

{
  "esim": true,
  "lpa": "LPA:1$smdp.example.com$ACTIVATION-CODE-ABC123XYZ",
  "iccid": "8961234567890123457",
  "imsi": "310120123456790",
  "ki": "00112233445566778899AABBCCDDEEFF",
  "opc": "FFEEDDCCBBAA99887766554433221100",
  "pin1": "1234",
  "pin2": "5678",
  "puk1": "12345678",
  "puk2": "87654321",
  "batch_name": "eSIM_Batch_2024_Q1",
  "sim_vendor": "Thales"
}

Processo de Importação de eSIM

Os eSIMs são normalmente importados em massa do provedor de eSIM:

Script de Importação: /OmniCRM-API/Provisioners/customer_product_creation/import_keys_esim.py

O processo de importação:

1. Lê os dados do eSIM de arquivos Excel fornecidos pelo fornecedor
2. Carrega códigos de ativação LPA de arquivos CSV
3. Atualiza o HSS com credenciais de eSIM
4. Cria itens de inventário correspondentes no CRM
5. Vincula perfis de eSIM ao sistema de inventário

Isso garante que os perfis de eSIM estejam disponíveis para atribuição enquanto mantém o rastreamento adequado do inventário.

Integração de Inventário

O sistema de inventário é central para o provisionamento de SIMs, rastreando tanto recursos físicos quanto virtuais necessários para serviços móveis.

Modelo de Inventário de Cartão SIM

Um modelo típico de inventário de Cartão SIM define:

{
  "item": "SIM Card",
  "itemtext1_label": "ICCID",
  "itemtext2_label": "IMSI",
  "itemtext3_label": "SIM Type",
  "wholesale_cost": 2.50,
  "retail_cost": 10.00
}

Nota: As credenciais de autenticação (Ki, OPC, PIN, PUK) são armazenadas no HSS AuC, não no inventário do CRM.

Para informações detalhadas sobre como criar e gerenciar modelos de inventário, incluindo como definir campos personalizados (itemtext1-20) e vincular modelos a produtos, veja a seção Gestão de Inventário - Modelos de Inventário.

Inventário de Números Móveis

Os números de telefone são gerenciados como itens de inventário separados:

{
  "inventory_id": 4001,
  "item": "Mobile Number",
  "itemtext1": "+61412345678",
  "itemtext2": "Melbourne",
  "itemtext3": "Mobile",
  "item_location": "Australia - VIC",
  "item_state": "New",
  "wholesale_cost": 1.00,
  "retail_cost": 0.00
}

Estados de Inventário para SIMs

Os cartões SIM progridem através de vários estados de inventário:

• New - SIM não utilizado, disponível para atribuição
• Assigned - Atualmente ativo com um cliente
• Used - Anteriormente atribuído, retornado ao inventário (pode ser reutilizado)
• Internal Use - Para testes ou uso da equipe
• Damaged - Não funcional, requer substituição
• Lost - Não pode ser localizado
• Stolen - Reportado como roubado

Integração de Produtos

Os produtos especificam o inventário necessário através de inventory_items_list:

{
  "product_id": 1,
  "product_slug": "Mobile-SIM",
  "product_name": "Mobile SIM Only",
  "provisioning_play": "play_psim_only",
  "inventory_items_list": "['SIM Card', 'Mobile Number']"
}

Ao provisionar este produto:

1. A interface exibe um seletor de inventário com duas listas suspensas
2. O usuário seleciona um Cartão SIM disponível (físico ou eSIM)
3. O usuário seleciona um Número Móvel disponível
4. Os IDs do inventário são passados para o playbook Ansible
5. O playbook recupera os detalhes completos do inventário via API
6. O provisionamento prossegue com os recursos selecionados

Para uma explicação completa de como os produtos impulsionam o provisionamento, como os requisitos de inventário são definidos e como as variáveis são passadas para os playbooks, veja Sistema de Provisionamento - Como os Produtos Impulsionam o Provisionamento.

Fluxo de Atribuição de Inventário

O playbook Ansible lida com a atribuição de inventário.

Para mais detalhes sobre como os playbooks se autenticam com a API do CRM (tokens Bearer, chaves de API, tokens de atualização), veja Sistema de Provisionamento - Autenticação e Autorização.

- name: Get SIM Card details from inventory
  uri:
    url: "{{ crm_config.crm.base_url }}/crm/inventory/inventory_id/{{ inventory_id_sim_card }}"
    method: GET
    headers:
      Authorization: "Bearer {{ access_token }}"
  register: sim_inventory_response

- name: Extract SIM identifiers
  set_fact:
    iccid: "{{ sim_inventory_response.json.itemtext1 }}"
    imsi: "{{ sim_inventory_response.json.itemtext2 }}"

- name: Get AuC ID from HSS (reference to authentication credentials)
  uri:
    url: "{{ item }}/auc/imsi/{{ imsi }}"
    method: GET
  loop: "{{ hss_peers }}"
  register: auc_response

- name: Extract AuC ID
  set_fact:
    auc_id: "{{ auc_response.results[0].json.auc_id }}"

# ... provision to HSS/IMS/OCS ...

- name: Assign SIM to customer
  uri:
    url: "{{ crm_config.crm.base_url }}/crm/inventory/inventory_id/{{ inventory_id_sim_card }}"
    method: PATCH
    headers:
      Authorization: "Bearer {{ access_token }}"
    body_format: json
    body:
      customer_id: "{{ customer_id }}"
      service_id: "{{ service_id }}"
      item_state: "Assigned"

Isso garante:

• O SIM é marcado como atribuído ao cliente
• O ID do serviço é vinculado para rastreamento
• O estado do inventário reflete o status atual
• Outros sistemas podem consultar o inventário para encontrar o SIM do cliente

Auto-Cadastro com Provisionamento de SIM

O OmniCRM suporta o autoatendimento de cadastro, onde os clientes podem ativar seus próprios cartões SIM ou eSIMs sem intervenção da equipe.

Fluxo de Auto-Cadastro

1. O Cliente Inicia o Cadastro

O cliente visita a página de auto-cadastro e começa a criação da conta:

• Fornece informações pessoais
• Seleciona um plano de serviço (produto)
• Insere os detalhes de pagamento

2. Validação do Número SIM

O cliente pode fornecer seu próprio número SIM (opcional):

GET /auth/self-signup/validate-itemtext1/{sim_number}

Este endpoint verifica se:

• O SIM existe no inventário
• O SIM está disponível (não está atribuído)
• O SIM está no estado correto ("New" ou "Used")

3. Atribuição Automática de SIM (Se Nenhum SIM For Fornecido)

Se o cliente não tiver um SIM, o sistema atribui automaticamente um disponível:

def _populate_base_plan_inventory(sim_number, plan):
    if sim_number:
        # Cliente forneceu SIM - verificar se existe
        sim_inventory = get_inventory_by_itemtext1(session, sim_number, None)
        if not sim_inventory:
            # Verificar se há um serviço inativo com este número
            service = get_inactive_service_by_sim(sim_number)
            if service:
                sim_inventory = get_sim_for_service(service.service_id)
    else:
        # Atribuir automaticamente SIM dispon��vel do inventário
        sim_inventory = get_first_available_inventory_by_item_name(
            session,
            "SIM Card",
            filters={"item_state": ["New"], "customer_id": [None]}
        )

    # Obter ICCID e MSISDN
    iccid = sim_inventory.itemtext1

    # Atribuir automaticamente número de telefone
    number_inventory = get_first_available_inventory_by_item_name(
        session,
        "Mobile Number"
    )
    msisdn = number_inventory.itemtext1

    return {
        "SIM Card": sim_inventory.inventory_id,
        "Mobile Number": number_inventory.inventory_id
    }

4. Criação de Conta e Provisionamento

Uma vez que o pagamento é autorizado:

def _post_signup_tasks(customer_id, plan, payment_method):
    # 1. Salvar método de pagamento
    save_stripe_payment_method(customer_id, payment_method)

    # 2. Cobrar o cartão do cliente
    charge_customer_card(customer_id, plan.retail_setup_cost)

    # 3. Fazer login do usuário (obter tokens JWT)
    tokens = login_customer(customer_id)

    # 4. Preencher inventário (SIM e número de telefone)
    inventory_vars = _populate_base_plan_inventory(sim_number, plan)

    # 5. Criar trabalho de provisionamento
    provision_vars = {
        "product_id": plan.product_id,
        "customer_id": customer_id,
        **inventory_vars  # Incluir IDs do Cartão SIM e do Número Móvel
    }

    # Opcional: Encadear produtos adicionais
    if plan.addon_chain:
        provision_vars["addon_chain"] = plan.addon_chain

    provision_id = create_provisioning_job(provision_vars)

    # 6. Retornar sucesso com tokens
    return {
        "access_token": tokens.access_token,
        "refresh_token": tokens.refresh_token,
        "customer_id": customer_id,
        "provision_id": provision_id
    }

5. O Cliente Recebe os Detalhes de Ativação

Após a conclusão do provisionamento:

• SIM Físico: E-mail de boas-vindas com número de telefone e instruções de ativação
• eSIM: O e-mail inclui QR code para download do perfil de eSIM, ou o cliente pode visualizar o QR code no portal do cliente

6. Permissões Especiais para Auto-Cadastro

Durante o cadastro, o token JWT inclui uma reivindicação especial:

{
  "sub": "customer_123",
  "signup_process": true,
  "permissions": ["VIEW_OWN_PROVISION", "UPDATE_OWN_INVENTORY"]
}

Isso permite:

• O cliente ler/atualizar o inventário durante o cadastro
• Restrito apenas à sua própria conta de cliente
• Impede a atribuição de SIMs pertencentes a outros clientes

Segurança do Auto-Cadastro

Verificações de Validação:

• O SIM deve existir no inventário
• O SIM não deve estar atribuído a outro cliente
• O SIM deve estar em um estado aceitável ("New", "Used")
• O cliente só pode atribuir SIMs à sua própria conta
• O pagamento deve ser autorizado antes do provisionamento

Salvaguardas de Inventário:

• Transações de banco de dados garantem atribuição atômica
• Tentativas de cadastro simultâneas são prevenidas via bloqueios de banco de dados
• Mudanças de estado de inventário são registradas para auditoria

Provisionamento Baseado em Ansible

Todo o provisionamento de SIM é orquestrado através de playbooks Ansible, proporcionando um processo consistente, auditável e repetível.

Para documentação abrangente sobre a estrutura do playbook Ansible, o padrão block/rescue, como os playbooks interagem com produtos e melhores práticas, veja Playbooks Ansible: Guia Detalhado.

Playbook Principal de Provisionamento de SIM

Arquivo: /OmniCRM-API/Provisioners/plays/play_psim_only.yaml

Este é o playbook principal para provisionamento de SIM móvel (tanto físico quanto eSIM). Ele lida com:

• Serviços de voz e dados móveis
• Serviços apenas de dados
• Assinantes IMS apenas de voz

Estrutura do Playbook (1.561 linhas):

Para explicação detalhada dos cabeçalhos do playbook, as diretivas hosts/gather_facts/become e a estrutura geral, veja Playbooks Ansible - Estrutura e Anatomia do Playbook.

- name: OmniCore Service Provisioning 2024
  hosts: localhost
  gather_facts: no
  become: False

  tasks:
    - name: Main provisioning block
      block:
        # --- PRE-PROVISIONING (Linhas 240-396) ---
        - name: Get SIM information from inventory
          # Recupera IMSI, ICCID, etc.

        - name: Validate IMSI length
          # Deve ter exatamente 15 dígitos

        - name: Check if IMSI exists in HSS
          # Previne provisionamento duplicado

        - name: Get AuC ID for IMSI
          # Recupera referência auc_id do HSS

        # --- HSS PROVISIONING (Linhas 398-534) ---
        - name: Create/Update HSS Subscriber
          # Provisões para todos os pares HSS

        - name: Create IMS Subscriber
          # Habilita chamadas de voz

        # --- OCS SETUP (Linhas 536-837) ---
        - name: Create ENUM entry
          # Mapeamento de número E.164

        - name: Create FilterS rule
          # Identificação de conta

        - name: Create AttributeS profile
          # Mapeamento IMSI/MSISDN

        - name: Create ResourceS profile
          # Limites de sessões simultâneas

        - name: Create OCS account
          # Criação de conta de cobrança

        # --- SERVICE & INVENTORY (Linhas 865-946) ---
        - name: Create service record
          # No banco de dados CRM

        - name: Assign SIM to service
          # Atualiza o inventário

        - name: Send welcome SMS
          # Notificação ao cliente

      rescue:
        # --- CLEANUP/DEPROVISIONING (Linhas 975-1562) ---
        - name: Return inventory to pool
          # Redefinir customer_id, service_id para nulo

        - name: Delete OCS account
          # Remover conta de cobrança

        - name: Remove HSS subscribers
          # Ou definir como estado dormente

        - name: Determine success/failure
          assert:
            that:
              - action == "deprovision"

Principais Etapas de Provisionamento

1. Validação Pré-Provisionamento

- name: Get SIM information from CRM inventory
  uri:
    url: "{{ crm_config.crm.base_url }}/crm/inventory/inventory_id/{{ inventory_id_sim_card }}"
    method: GET
    headers:
      Authorization: "Bearer {{ access_token }}"
  register: api_response_sim

- name: Extract and validate IMSI
  set_fact:
    imsi: "{{ api_response_sim.json.itemtext2 }}"

- name: Validate IMSI format
  assert:
    that:
      - imsi | length == 15
      - imsi is match('^[0-9]+$')
    fail_msg: "IMSI must be exactly 15 digits"

2. Recuperar AuC ID do HSS

- name: Get AuC ID for IMSI from HSS
  uri:
    url: "{{ item }}/auc/imsi/{{ imsi }}"
    method: GET
  loop: "{{ crm_config.hss.hss_peers }}"
  register: auc_lookup

- name: Extract auc_id from first HSS response
  set_fact:
    auc_id: "{{ auc_lookup.results[0].json.auc_id }}"

3. Provisionamento de Assinante HSS

- name: Create subscriber in each HSS peer
  uri:
    url: "{{ item }}/subscriber/"
    method: PUT
    body_format: json
    body:
      enabled: true
      roaming_enabled: true
      auc_id: "{{ auc_id }}"
      msisdn: "{{ phone_number }}"
      imsi: "{{ imsi }}"
      ue_ambr_dl: 9999999  # Limite de velocidade de download
      ue_ambr_ul: 9999999  # Limite de velocidade de upload
      apn_list: "1,2,3"
      default_apn: 1
    status_code: [200, 201]
  loop: "{{ crm_config.hss.hss_peers }}"
  register: hss_responses

4. Provisionamento de Assinante IMS (Voz)

- name: Create IMS subscriber for voice services
  uri:
    url: "{{ item }}/ims_subscriber/"
    method: PUT
    body_format: json
    body:
      imsi: "{{ imsi }}"
      msisdn: "{{ phone_number }}"
      msisdn_list: "{{ phone_number }}"
      ifc_path: "default_ifc.xml"
      sh_profile: |
        <?xml version="1.0"?>
        <IMSSubscription>
          <PrivateID>{{ imsi }}@ims.mnc{{ mnc }}.mcc{{ mcc }}.3gppnetwork.org</PrivateID>
          <ServiceProfile>
            <PublicIdentity>
              <Identity>sip:{{ phone_number }}@ims.mnc{{ mnc }}.mcc{{ mcc }}.3gppnetwork.org</Identity>
            </PublicIdentity>
          </ServiceProfile>
        </IMSSubscription>
    status_code: [200, 201]
  loop: "{{ crm_config.hss.hss_peers }}"

5. Configuração de Cobrança do OCS

# Criar filtros de conta (identificar assinante por IMSI/MSISDN)
- name: Create FilterS for IMSI identification
  uri:
    url: "{{ crm_config.ocs.ocsApi }}/jsonrpc"
    method: POST
    body_format: json
    body:
      method: "ApierV1.SetFilter"
      params:
        - ID: "FILTER_IMSI_{{ service_uuid }}"
          Type: "*string"
          Element: "~*req.OriginHost"
          Values: ["{{ imsi }}"]

# Criar perfil de atributos (mapear IMSI para conta)
- name: Create AttributeS profile
  uri:
    url: "{{ crm_config.ocs.ocsApi }}/jsonrpc"
    method: POST
    body_format: json
    body:
      method: "ApierV1.SetAttributeProfile"
      params:
        - ID: "ATTR_ACCOUNT_{{ service_uuid }}"
          FilterIDs: ["FILTER_IMSI_{{ service_uuid }}"]
          Attributes:
            - Path: "*req.Account"
              Value: "{{ service_uuid }}"

# Criar conta de cobrança
- name: Create OCS account
  uri:
    url: "{{ crm_config.ocs.ocsApi }}/jsonrpc"
    method: POST
    body_format: json
    body:
      method: "ApierV2.SetAccount"
      params:
        - Tenant: "{{ crm_config.ocs.ocsTenant }}"
          Account: "{{ service_uuid }}"
          ActionPlanIds: []
          ExtraOptions:
            AllowNegative: false
            Disabled: false

# Adicionar saldo inicial
- name: Add initial monetary balance
  uri:
    url: "{{ crm_config.ocs.ocsApi }}/jsonrpc"
    method: POST
    body_format: json
    body:
      method: "ApierV1.AddBalance"
      params:
        - Tenant: "{{ crm_config.ocs.ocsTenant }}"
          Account: "{{ service_uuid }}"
          BalanceType: "*monetary"
          Balance:
            Value: 0
            ExpiryTime: "+8760h"  # 1 ano

6. Criação de Serviço

- name: Create service record in CRM
  uri:
    url: "{{ crm_config.crm.base_url }}/crm/service/"
    method: PUT
    headers:
      Authorization: "Bearer {{ access_token }}"
    body_format: json
    body:
      customer_id: "{{ customer_id }}"
      product_id: "{{ product_id }}"
      service_name: "Mobile Service - {{ phone_number }}"
      service_uuid: "{{ service_uuid }}"
      service_status: "Active"
      retail_cost: "{{ monthly_cost }}"
    status_code: 200
  register: service_creation_response

- name: Extract service_id
  set_fact:
    service_id: "{{ service_creation_response.json.service_id }}"

7. Atribuição de Inventário

- name: Assign SIM card to customer and service
  uri:
    url: "{{ crm_config.crm.base_url }}/crm/inventory/inventory_id/{{ inventory_id_sim_card }}"
    method: PATCH
    headers:
      Authorization: "Bearer {{ access_token }}"
    body_format: json
    body:
      customer_id: "{{ customer_id }}"
      service_id: "{{ service_id }}"
      item_state: "Assigned"
      sold_date: "{{ ansible_date_time.iso8601 }}"

- name: Assign phone number to customer and service
  uri:
    url: "{{ crm_config.crm.base_url }}/crm/inventory/inventory_id/{{ inventory_id_phone_number }}"
    method: PATCH
    headers:
      Authorization: "Bearer {{ access_token }}"
    body_format: json
    body:
      customer_id: "{{ customer_id }}"
      service_id: "{{ service_id }}"
      item_state: "Assigned"
      sold_date: "{{ ansible_date_time.iso8601 }}"

Desprovisionamento e Reversão

O mesmo playbook lida tanto com a reversão de provisionamento falhado quanto com o desprovisionamento intencional usando o bloco rescue do Ansible.

Para uma explicação detalhada do padrão block/rescue e por que isso é uma prática recomendada, veja Sistema de Provisionamento - Reversão e Limpeza: Padrão de Melhor Prática.

rescue:
  # Esta seção é executada quando:
  # 1. Qualquer tarefa no bloco falha (limpeza automática)
  # 2. action == "deprovision" (limpeza intencional)

  - name: Get inventory items linked to service
    uri:
      url: "{{ crm_config.crm.base_url }}/crm/inventory/customer_id/{{ customer_id }}"
      method: GET
      headers:
        Authorization: "Bearer {{ access_token }}"
    register: inventory_items
    ignore_errors: true

  - name: Return inventory to available pool
    uri:
      url: "{{ crm_config.crm.base_url }}/crm/inventory/inventory_id/{{ item.inventory_id }}"
      method: PATCH
      headers:
        Authorization: "Bearer {{ access_token }}"
      body_format: json
      body:
        customer_id: null
        service_id: null
        item_state: "Used"
    loop: "{{ inventory_items.json.data }}"
    when: inventory_items.json.data is defined
    ignore_errors: true

  - name: Delete OCS account
    uri:
      url: "{{ crm_config.ocs.ocsApi }}/jsonrpc"
      method: POST
      body_format: json
      body:
        method: "ApierV1.RemoveAccount"
        params:
          - Tenant: "{{ crm_config.ocs.ocsTenant }}"
            Account: "{{ service_uuid }}"
    ignore_errors: true

  - name: Delete or disable HSS subscriber
    uri:
      url: "{{ item.key }}/subscriber/{{ item.value.subscriber_id }}"
      method: DELETE
    loop: "{{ hss_subscriber_data | dict2items }}"
    when: deprovision_subscriber | default(false) | bool
    ignore_errors: true

  # A afirmação final determina sucesso ou falha
  - name: Determine if this was intentional deprovision or failed provision
    assert:
      that:
        - action == "deprovision"
      fail_msg: "Provisioning failed and rollback completed"
      success_msg: "Deprovisioning completed successfully"

Pontos Chave:

• ignore_errors: true em todas as tarefas de limpeza garante que todas as tentativas de limpeza sejam feitas
• Se action == "deprovision", a afirmação passa (status 0 = sucesso)
• Se action não estiver definido, a afirmação falha (status 2 = falha no provisionamento)
• Isso garante operações atômicas: ou totalmente provisionado ou totalmente limpo

Outros Playbooks Relacionados a SIM

Playbook de Desenvolvimento Local: play_local_mobile_sim.yaml - Versão de desenvolvimento que ignora dependências externas de HSS/OCS

Troca de MSISDN: play_swap_msisdn.yaml - Troca números de telefone entre serviços existentes

Playbooks de Recarga:

• play_topup_monetary.yaml - Adiciona saldo monetário
• play_topup_no_charge.yaml - Adiciona dados/minutos gratuitos
• play_topup_dongle.yaml - Recarga para dispositivos IoT/dados

Integração HSS e IMS

O OmniCRM integra-se ao PyHSS (servidor de assinantes doméstico de código aberto) para gerenciamento e autenticação de assinantes.

Funções do HSS

Arquivo: /OmniCRM-API/Provisioners/hss.py

Funções Principais:

def ProvisionMobileSIM(json_data, hss_urls):
    """
    Provisões um SIM móvel para HSS e IMS

    Args:
        json_data: Dict com IMSI, MSISDN, credenciais de autenticação
        hss_urls: Lista de URLs de pares HSS

    Returns:
        Dict com IDs de assinantes de cada par HSS
    """
    # Criar assinante HSS (para dados)
    # Criar assinante IMS (para voz)
    # Retornar IDs de assinantes para rastreamento

def get_subscriber_info_msisdn(msisdn, hss_urls):
    """
    Recupera detalhes do assinante pelo número de telefone

    Args:
        msisdn: Número de telefone a ser pesquisado
        hss_urls: Lista de URLs de pares HSS

    Returns:
        Informações do assinante do HSS
    """

Suporte Multi-HSS

O OmniCRM suporta o provisionamento para múltiplos pares HSS para redundância:

# crm_config.yaml
hss:
  hss_peers:
    - "http://10.12.64.140:8080"
    - "http://10.12.64.141:8080"
  apn_list: "1,2,3"
  default_apn: 1

O provisionamento ocorre em todas as instâncias HSS configuradas para garantir:

• Redundância geográfica
• Balanceamento de carga
• Capacidade de failover
• Dados de assinante sincronizados

Centro de Autenticação (AuC)

O AuC armazena credenciais de autenticação de assinantes. Durante o provisionamento, apenas o auc_id é recuperado:

Obter AuC ID para IMSI:

GET /auc/imsi/{imsi}

Resposta:

{
  "auc_id": 12345,
  "imsi": "310120123456789",
  "iccid": "8961234567890123456",
  "esim": false,
  "lpa": null
}

Para eSIMs, a flag esim é true e lpa contém o código de ativação para exibição aos clientes.

Nota: As credenciais de autenticação reais (Ki, OPC, PIN, PUK) permanecem no HSS e nunca são expostas via API. O sistema de provisionamento só precisa do auc_id para referenciar essas credenciais ao criar assinantes.

Integração OCS

O Sistema de Cobrança Online (OCS) lida com cobrança e tarifação em tempo real para serviços móveis. O OmniCRM usa o CGRateS como a plataforma OCS.

Configuração do OCS

Arquivo: /OmniCRM-API/Provisioners/ocs.py

Configuração:

# crm_config.yaml
ocs:
  cgrates: "10.64.12.160:2080"
  ocsTenant: "mnc380.mcc313.3gppnetwork.org"
  ocsApi: "http://10.64.12.160:2080"

Componentes do OCS para Serviços de SIM

1. Filtros - Identificação do Assinante

Filtros identificam o assinante a partir de solicitações de rede:

{
  "ID": "FILTER_IMSI_Service_abc123",
  "Type": "*string",
  "Element": "~*req.OriginHost",
  "Values": ["310120123456789"]
}

2. Atributos - Mapeamento de Conta

Atributos mapeiam o IMSI para a conta de cobrança:

{
  "ID": "ATTR_ACCOUNT_Service_abc123",
  "FilterIDs": ["FILTER_IMSI_Service_abc123"],
  "Attributes": [
    {
      "Path": "*req.Account",
      "Value": "Service_abc123"
    },
    {
      "Path": "*req.Bandwidth",
      "Value": "100000000"  // 100 Mbps
    }
  ]
}

3. Recursos - Limites de Sessões

Recursos controlam limites de sessões simultâneas:

{
  "ID": "RES_SESSIONS_Service_abc123",
  "FilterIDs": ["FILTER_IMSI_Service_abc123"],
  "Limit": 5,  // Máx 5 sessões simultâneas
  "UsageTTL": "-1"
}

4. Estatísticas - Rastreamento de Uso

Estatísticas rastreiam o uso para análises:

{
  "ID": "STATS_Service_abc123",
  "FilterIDs": ["FILTER_IMSI_Service_abc123"],
  "Metrics": [
    "*sum#~*req.Usage",
    "*tcc"  // Contagem total de chamadas
  ]
}

5. Planos de Ação - Cobranças Recorrentes

Planos de ação lidam com operações recorrentes, como cobranças mensais:

{
  "Id": "ActionPlan_Service_abc123_Monthly",
  "ActionsId": "Action_Add_Monthly_Data",
  "Timing": {
    "MonthDays": [1],  // 1º de cada mês
    "Time": "00:00:00Z"
  }
}

Funções da API OCS

Funções Principais do ocs.py:

async def async_get_balance(account, server, tenant):
    """Obter saldo atual da conta"""

async def async_topup_dongle(tenant, account, server, days):
    """Adicionar concessão de dados baseada em tempo"""

def Get_Account_Status(account, server, tenant):
    """Obter informações abrangentes da conta"""

def CGRateS_API_Call(method, params, server, tenant):
    """Chamada genérica da API JSON-RPC do CGRateS"""

Reconciliação de Inventário de SIM

O OmniCRM inclui ferramentas para garantir consistência entre o inventário do CRM e o HSS.

Script de Reconciliação

Arquivo: /OmniCRM-API/Provisioners/hss_reconcile.py

Propósito:

• Identifica SIMs no HSS, mas não no inventário (orfãos)
• Encontra SIMs atribuídos que não estão provisionados no HSS
• Valida formatos de MSISDN
• Gera relatórios em HTML

Verificações Realizadas:

1. SIMs Vendidos no HSS:

   • Consulta todos os SIMs atribuídos do inventário
   • Verifica se cada IMSI existe no HSS
   • Relata SIMs atribuídos a clientes, mas não no HSS

2. SIMs Provisionados no Inventário:

   • Consulta todos os assinantes do HSS
   • Verifica se cada IMSI existe no inventário
   • Relata entradas orfãs do HSS

3. Validação de MSISDN:

   • Valida formatos de números de telefone
   • Verifica conformidade com números australianos
   • Relata números malformados

Executando a Reconciliação:

python hss_reconcile.py

Saída:

• Relatório HTML com resultados codificados por cor
• Listas de discrepâncias para investigação
• Recomendações para limpeza

Melhores Práticas:

• Execute a reconciliação semanalmente
• Investigue discrepâncias prontamente
• Use relatórios para identificar falhas de provisionamento
• Limpe entradas orfãs para liberar recursos

Resolução de Problemas de Provisionamento de SIM

Problemas Comuns e Soluções

Problema: O provisionamento do SIM falha com "IMSI já existe no HSS"

• Causa: IMSI já está provisionado de uma tentativa anterior
• Solução: Verifique o HSS para assinante existente, seja:
  • Exclua o assinante existente se estiver órfão
  • Atualize o assinante existente em vez de criar um novo
  • Execute a reconciliação para identificar o conflito

Problema: QR code do eSIM não gerando

• Causa: Campo management_url não populado com código LPA
• Solução: Certifique-se de que o script de importação de eSIM define management_url corretamente
• Formato: Deve ser LPA:1$server$activation-code

Problema: Item de inventário mostra como "Disponível", mas está atribuído

• Causa: O provisionamento falhou antes da atribuição do inventário
• Solução: Verifique eventos de provisionamento para a razão da falha
• Correção: Complete o provisionamento ou retorne o inventário para a piscina

Problema: O cliente não consegue fazer chamadas (dados funcionam)

• Causa: Assinante IMS não provisionado
• Solução: Verifique se a etapa de provisionamento IMS foi concluída
• Correção: Provisione manualmente o assinante IMS ou reexecute o playbook

Problema: Falhas de autenticação (SIM não consegue se conectar)

• Causa: Mismatch de Ki/OPC entre o cartão SIM e o HSS
• Solução: Verifique se as credenciais do AuC correspondem ao SIM físico
• Correção: Atualize o HSS AuC com as credenciais corretas

Problema: Auto-cadastro falha ao atribuir SIM

• Causa: Sem SIMs disponíveis no inventário
• Solução: Verifique o inventário para SIMs com estado "New" e customer_id NULL
• Correção: Importe um novo lote de SIM ou marque SIMs retornados como "Used"

Dicas de Depuração

1. Verifique Eventos de Provisionamento:

GET /crm/provision/provision_id/{id}

Procure tarefas falhadas (status 2) e revise mensagens de erro.

2. Verifique Assinante HSS:

GET {hss_url}/subscriber/msisdn/{phone_number}

Verifique se o assinante existe e tem a configuração correta.

3. Verifique Conta OCS:

{
  "method": "ApierV2.GetAccount",
  "params": [
    {
      "Tenant": "mnc380.mcc313.3gppnetwork.org",
      "Account": "Service_abc123"
    }
  ]
}

4. Consulte o Status do Inventário:

GET /crm/inventory/?filters={"itemtext2":["310120123456789"]}

Pesquise por IMSI para encontrar o item de inventário e verifique seu estado.

5. Revise os Logs do Ansible:

Verifique /var/log/ansible/ ou detalhes do evento de provisionamento para a saída completa do playbook.

Melhores Práticas

Gestão de Inventário de SIM

1. Importação em Massa: Use scripts de importação para grandes lotes de SIMs
2. Reconciliação Regular: Execute a reconciliação semanal HSS/inventário
3. Gestão de Estado: Mantenha os estados de inventário precisos (New, Assigned, Used)
4. Rastreamento de Fornecedor: Registre informações de fornecedor e lote do SIM
5. Rastreamento de Custos: Mantenha custos de atacado/varejo precisos

Segurança

1. Separação de Credenciais: Credenciais de autenticação (Ki/OPC) permanecem apenas no HSS, nunca no CRM
2. Controle de Acesso: Limite quem pode atribuir/modificar o inventário de SIMs
3. Registro de Auditoria: Rastreie todas as atribuições e alterações de SIM
4. Gestão de PIN/PUK: Códigos PIN/PUK armazenados no HSS, fornecidos aos clientes por canais seguros
5. Processo de Perdido/Roubado: Suspenda imediatamente o serviço no HSS e marque o estado do inventário

Provisionamento

1. Validação: Sempre valide o formato e a exclusividade do IMSI
2. Reversão: Use block/rescue para limpeza automática em caso de falha
3. Notifica��ões: Envie instruções de ativação claras aos clientes
4. Teste: Teste o provisionamento em desenvolvimento antes da produção
5. Monitoramento: Rastreie taxas de sucesso de provisionamento e razões de falha

Específico para eSIM

1. Formato LPA: Valide o formato do código LPA antes de armazenar
2. Teste de QR: Teste QR codes em vários dispositivos
3. Instruções de Ativação: Forneça guias passo a passo claras
4. Gestão de Perfis: Rastreie downloads e instalações de perfis de eSIM
5. Códigos de Backup: Forneça códigos LPA manuais caso a digitalização do QR falhe

Documentação Relacionada

• Sistema de Provisionamento - Detalhes completos do fluxo de trabalho de provisionamento
• Playbooks Ansible - Estrutura do playbook e melhores práticas
• Gestão de Inventário - Visão geral do sistema de inventário
• Produtos e Serviços - Configuração de produtos
• Atendimento ao Cliente - Apoio a clientes com problemas de SIM
• Recarga e Recarregamento - Adicionando saldo a serviços móveis