Provisionamento de Cartões SIM

OmniCRM oferece suporte abrangente para o provisionamento de cartões SIM físicos e eSIMs (SIMs embutidos) para operadoras de rede móvel e MVNOs. O sistema gerencia o ciclo de vida completo, 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 os 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 à Autoinscrição - Permite que os clientes ativem seus próprios SIMs

Provisionamento de Cartões SIM Físicos

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 primeiro 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 do 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 os 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 de PIN (armazenados no HSS)

O inventário do CRM rastreia qual SIM (por ICCID/IMSI) está atribuído a qual cliente, enquanto o HSS gerencia 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 Residenciais (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 capacidade de chamada 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 via desafio-resposta entre o SIM e o HSS
• O CRM nunca vê ou manipula os valores reais de Ki/OPC

Provisionamento de eSIM

Os 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 único para este perfil de eSIM

Geração de Código QR

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

• Armazenados no campo management_url do inventário
• Exibidos na interface como código QR 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 código QR é 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 do 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
• Mesmo 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 código QR é exibido para escaneamento
3. O cliente escaneia o código QR 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	Obrigatório	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álises 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álises.
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
• Código QR (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 do Mailjet em crm_config.yaml:

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

Parâmetro	Tipo	Obrigatório	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 for configurado, o sistema gera um e-mail HTML com marca registrada contendo:

• Marca e logotipo da empresa
• Código QR 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
• Vinculação 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 AuC do HSS (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 tipicamente importados em massa do fornecedor 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 as credenciais do 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 do Inventário para SIMs

Os cartões SIM progridem por 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 teste 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 via 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 dois menus suspensos
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 de inventário são passados para o playbook Ansible
5. O playbook recupera todos os detalhes 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 gerencia 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

Autoinscrição com Provisionamento de SIM

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

Fluxo de Autoinscrição

1. O Cliente Inicia a Inscrição

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

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

2. Validação do Número do SIM

O cliente pode fornecer seu próprio número de 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 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 esse 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 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 de Cartão SIM e 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 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: E-mail inclui código QR para download do perfil de eSIM, ou o cliente pode visualizar o código QR no portal do cliente

6. Permissões Especiais para Autoinscrição

Durante a inscrição, 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 a inscrição
• Restrito apenas à sua própria conta de cliente
• Impede a atribuição de SIMs pertencentes a outros clientes

Segurança da Autoinscrição

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 inscrição simultâneas são prevenidas via bloqueios de banco de dados
• Mudanças de estado do 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 móveis de voz e dados
• 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ão simultânea

        - 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
          # Remove 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 do OCS
- 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 Melhores Práticas.

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 asserçã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 asserção passa (status 0 = sucesso)
• Se action não estiver definido, a asserção falha (status 2 = provisionamento falhado)
• 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 a um Servidor de Assinantes Residenciais (HSS) externo 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 a Múltiplos HSS

O OmniCRM suporta o provisionamento para vários 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 precisa apenas 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 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: "mnc001.mcc001.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ão

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 - Rastreio 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 do 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 CGRateS JSON-RPC"""

Reconciliação do 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:

• Identificar SIMs no HSS, mas não no inventário (orfãos)
• Encontrar SIMs atribuídos que não estão provisionados no HSS
• Validar formatos de MSISDN
• Gerar relatórios em HTML

Verificações Realizadas:

1. SIMs Vendidos no HSS:

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

2. SIMs Provisionados no Inventário:

   • Consultar todos os assinantes do HSS
   • Verificar se cada IMSI existe no inventário
   • Relatar entradas orfãs do HSS

3. Validação de MSISDN:

   • Validar formatos de números de telefone
   • Verificar conformidade com números australianos
   • Relatar números malformados

Executando a Reconciliação:

python hss_reconcile.py

Saída:

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

Melhores Práticas:

• Executar a reconciliação semanalmente
• Investigar discrepâncias prontamente
• Usar relatórios para identificar falhas de provisionamento
• Limpar entradas orfãs para liberar recursos

Soluçã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:
  • Excluir o assinante existente se estiver órfão
  • Atualizar o assinante existente em vez de criar um novo
  • Executar a reconciliação para identificar o conflito

Problema: Código QR do eSIM não gerando

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

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

• Causa: 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 ao pool

Problema: 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 re-execute o playbook

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

• Causa: Desvio 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 AuC do HSS com as credenciais corretas

Problema: Autoinscrição falha ao atribuir SIM

• Causa: Nenhum SIM disponível no inventário
• Solução: Verifique o inventário para SIMs com estado "New" e customer_id NULL
• Correção: Importar novo lote de SIMs ou marcar 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": "mnc001.mcc001.3gppnetwork.org",
      "Account": "Service_abc123"
    }
  ]
}

4. Consultar Status do Inventário:

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

Pesquise por IMSI para encontrar o item de inventário e verificar 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 do 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 falha
3. Notificações: Envie instruções de ativação claras aos clientes
4. Testes: Teste o provisionamento em desenvolvimento antes da produção
5. Monitoramento: Rastreie taxas de sucesso de provisionamento e razões para falhas

Específico para eSIM

1. Formato LPA: Valide o formato do código LPA antes de armazenar
2. Teste de QR: Teste códigos QR 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 de 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 aos clientes com problemas de SIM
• Recarga e Top-Up - Adicionando saldo a serviços móveis