Pular para o conteúdo principal

Referência da API OmniHSS

← Voltar ao Guia de Operações

Índice​

Visão Geral da API​

URL Base​

https://[hostname]:8443/api

Formato da Requisição​

  • Content-Type: application/json
  • Protocolo: Apenas HTTPS
  • Porta: 8443 (configurável)

Importante: Todos os endpoints da API esperam payloads JSON "planos" sem objetos de wrapper.

Formato Correto:

{
  "name": "value",
  "field": "value"
}

Formato Incorreto (Não Use):

{
  "subscriber": {
    "name": "value",
    "field": "value"
  }
}

Exemplo:

# ✓ Correto
curl -X POST https://hss.example.com:8443/api/ims/profile \
  -H "Content-Type: application/json" \
  -d '{"name": "default", "ifc_template": "..."}'

# ✗ Incorreto
curl -X POST https://hss.example.com:8443/api/ims/profile \
  -H "Content-Type: application/json" \
  -d '{"ims_profile": {"name": "default", "ifc_template": "..."}}'

Formato da Resposta​

Todas as respostas são JSON com a seguinte estrutura:

Resposta de Sucesso:

{
  "status": "success",
  "response": { ... }
}

Resposta de Erro:

{
  "status": "error",
  "response": {
    "invalid_fields": {
      "field_name": "mensagem de erro"
    }
  }
}

Códigos de Status HTTP​

CódigoSignificadoCaso de Uso
200OKGET, PUT, DELETE bem-sucedidos
201CriadoPOST bem-sucedido
400Requisição InválidaDados de entrada inválidos
404Não EncontradoRecurso não existe
422Entidade Não ProcessávelErro de validação
500Erro Interno do ServidorErro do lado do servidor

Fluxo de Requisição da API​

Gerenciamento de Assinantes​

Listar Assinantes​

Recuperar todos os assinantes ou filtrar por critérios.

Endpoint: GET /api/subscriber

Parâmetros de Consulta:

ParâmetroTipoDescrição
enabledbooleanFiltrar por status habilitado
ims_enabledbooleanFiltrar por status habilitado IMS

Exemplo de Requisição:

curl -k https://hss.example.com:8443/api/subscriber

Exemplo de Resposta:

{
  "data": [
    {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "imsi": "001001123456789",
      "enabled": true,
      "ims_enabled": true,
      "sim_id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
      "key_set_id": "6ba7b810-9dad-41d1-80b4-00c04fd430c8",
      "epc_profile_id": "e58ed763-928c-4155-bee9-fdbaaadc15f3",
      "ims_profile_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "roaming_profile_id": "9c858901-8a57-4791-81fe-4c455b099bc9",
      "custom_attributes": {},
      "inserted_at": "2025-10-15T10:30:00Z",
      "updated_at": "2025-10-15T10:30:00Z"
    }
  ]
}

Obter Assinante por ID​

Recuperar um assinante específico pelo ID do banco de dados.

Endpoint: GET /api/subscriber/:id

Parâmetros de Caminho:

ParâmetroTipoDescrição
idstring (UUID)ID do assinante no banco de dados

Exemplo de Requisição:

curl -k https://hss.example.com:8443/api/subscriber/d290f1ee-6c54-4b01-90e6-d701748f0851

Obter Assinante por IMSI​

Recuperar um assinante pelo seu IMSI.

Endpoint: GET /api/subscriber/imsi/:imsi

Parâmetros de Caminho:

ParâmetroTipoDescriçãoFormato
imsistringIdentidade Internacional do Assinante Móvel14-15 dígitos

Exemplo de Requisição:

curl -k https://hss.example.com:8443/api/subscriber/imsi/001001123456789

Caso de Uso: Solucionar problemas de um assinante específico pelo seu IMSI.

Obter Assinante por MSISDN​

Recuperar um assinante pelo seu número de telefone.

Endpoint: GET /api/subscriber/msisdn/:msisdn

Parâmetros de Caminho:

ParâmetroTipoDescriçãoFormato
msisdnstringNúmero ISDN da Estação Móvel1-15 dígitos (E.164)

Exemplo de Requisição:

curl -k https://hss.example.com:8443/api/subscriber/msisdn/14155551234

Caso de Uso: Procurar informações do assinante quando você só tem o número de telefone.

Criar Assinante​

Provisionar um novo assinante.

Endpoint: POST /api/subscriber

Corpo da Requisição:

{
  "subscriber": {
    "imsi": "001001123456789",
    "enabled": true,
    "ims_enabled": true,
    "sim_id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
    "key_set_id": "6ba7b810-9dad-41d1-80b4-00c04fd430c8",
    "epc_profile_id": "e58ed763-928c-4155-bee9-fdbaaadc15f3",
    "ims_profile_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "roaming_profile_id": "9c858901-8a57-4791-81fe-4c455b099bc9",
    "custom_attributes": {
      "note": "Assinante de teste"
    }
  }
}

Campos Obrigatórios:

  • imsi - Deve ter 14-15 dígitos, único
  • key_set_id - Deve referenciar um Conjunto de Chaves existente
  • epc_profile_id - Deve referenciar um Perfil EPC existente

Campos Opcionais:

  • enabled - Padrão: true
  • ims_enabled - Padrão: true
  • sim_id - Referência ao cartão SIM
  • ims_profile_id - Referência ao Perfil IMS (obrigatório para serviços IMS)
  • roaming_profile_id - Referência ao Perfil de Roaming (obrigatório para controle de roaming)
  • msisdns - Array de IDs de MSISDN (números de telefone)
  • static_ips - Array de IDs de IP Estático para atribuições de APN
  • ims_subscription_id - Referência a uma Assinatura IMS para agrupar vários assinantes sob uma identidade pública compartilhada e S-CSCF
  • custom_attributes - Pares chave-valor personalizados

Veja Também:

Exemplo de Requisição:

curl -k -X POST https://hss.example.com:8443/api/subscriber \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber": {
      "imsi": "001001123456789",
      "key_set_id": "6ba7b810-9dad-41d1-80b4-00c04fd430c8",
      "epc_profile_id": "e58ed763-928c-4155-bee9-fdbaaadc15f3"
    }
  }'

Fluxo de Provisionamento:

Atualizar Assinante​

Modificar um assinante existente.

Endpoint: PUT /api/subscriber/:id

Parâmetros de Caminho:

ParâmetroTipoDescrição
idstring (UUID)ID do assinante no banco de dados

Corpo da Requisição:

{
  "subscriber": {
    "enabled": false,
    "ims_enabled": false,
    "epc_profile_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "custom_attributes": {
      "note": "Temporariamente desativado"
    }
  }
}

Campos Atualizáveis:

Não Atualizável:

  • imsi - Não é possível alterar o IMSI (excluir e recriar em vez disso)

Veja Também:

Exemplo de Requisição:

curl -k -X PUT https://hss.example.com:8443/api/subscriber/d290f1ee-6c54-4b01-90e6-d701748f0851 \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber": {
      "enabled": false
    }
  }'

Casos de Uso:

  • Desativar temporariamente o assinante: {"enabled": false}
  • Desativar apenas os serviços de voz: {"ims_enabled": false}
  • Alterar perfil de serviço: {"epc_profile_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"} (veja Perfis EPC)
  • Atualizar política de roaming: {"roaming_profile_id": "1b671a64-40d5-491e-99b0-da01ff1f3341"} (veja Gerenciamento de Roaming)

Excluir Assinante​

Remover um assinante do sistema.

Endpoint: DELETE /api/subscriber/:id

Parâmetros de Caminho:

ParâmetroTipoDescrição
idstring (UUID)ID do assinante no banco de dados

Exemplo de Requisição:

curl -k -X DELETE https://hss.example.com:8443/api/subscriber/d290f1ee-6c54-4b01-90e6-d701748f0851

Atenção: Isso exclui permanentemente o assinante e todos os dados de estado associados (sessões PDN, chamadas, etc.). O IMSI pode ser reutilizado após a exclusão.

Nota: Excluir um assinante NÃO exclui o associado:

  • Conjunto de Chaves - Pode ser reutilizado para outros assinantes
  • SIM - Pode ser reatribuído a um novo assinante
  • Perfis - Recursos compartilhados usados por vários assinantes
  • MSISDNs - Devem ser excluídos separadamente, se desejado

Cancelar Requisição de Localização (Desconexão Forçada)​

Enviar uma Requisição de Cancelamento de Localização (CLR) para forçar a desconexão de um assinante de seu MME atualmente registrado.

Endpoint: POST /api/subscriber/cancel_location

Corpo da Requisição:

{
  "imsi": "001001123456789"
}

Parâmetros:

ParâmetroTipoObrigatórioDescrição
imsistringSimIMSI do assinante a ser desconectado (14-15 dígitos)

Exemplo de Requisição:

curl -k -X POST https://hss.example.com:8443/api/subscriber/cancel_location \
  -H "Content-Type: application/json" \
  -d '{"imsi": "001001123456789"}'

Resposta de Sucesso (200 OK):

{
  "data": {
    "message": "Requisição de Cancelamento de Localização enviada com sucesso",
    "imsi": "001001123456789",
    "destination_host": "mme01.operator.com",
    "destination_realm": "epc.operator.com"
  }
}

Resposta de Erro (404 Não Encontrado):

{
  "error": "Assinante não encontrado ou não registrado atualmente em nenhum MME"
}

Comportamento:

  • Envia S6a CLR para o MME onde o assinante está atualmente registrado (subscriber_state.last_seen_mme)
  • Usa Cancellation-Type: subscription_withdrawal (força desconexão total)
  • Define CLR-Flags: {s6a_indicator: 1, reattach_required: 1} (UE deve reautenticar)
  • Retorna 404 se o assinante nunca se registrou ou last_seen_mme for nulo
  • Afeta todos os MSISDNs associados ao IMSI (mesmo dispositivo físico/SIM)

Casos de Uso:

  • Prevenção de Fraude: Desconectar imediatamente assinante suspeito
  • Término de Assinatura: Forçar logout quando a conta é desativada
  • Solução de Problemas: Limpar registro MME obsoleto para depuração
  • Migração: Forçar reautenticação para aplicar novas configurações de perfil
  • Segurança: Desconectar imediatamente assinante comprometido

Considerações Multi-IMSI:

Ao usar CLR com cenários multi-MSISDN:

  1. Múltiplos MSISDNs, Um IMSI:

    // Assinante tem IMSI 001001123456789 com MSISDNs ["+1234567890", "+9876543210"]
    POST /api/subscriber/cancel_location
    {"imsi": "001001123456789"}

    // Resultado: Um CLR enviado, ambos os MSISDNs afetados (mesmo dispositivo)

  2. IMSI Diferentes (Dispositivos Diferentes):

    // Dois assinantes com o mesmo MSISDN, mas IMSIs diferentes (cenário de portabilidade de número)
    // Assinante A: IMSI 001001111111111, MSISDN "+1234567890"
    // Assinante B: IMSI 001001222222222, MSISDN "+1234567890"

    POST /api/subscriber/cancel_location
    {"imsi": "001001111111111"}

    // Resultado: Apenas Assinante A desconectado, Assinante B não afetado

Notas Importantes:

  • Baseado em IMSI: CLR é sempre enviado por IMSI, não por MSISDN
  • Assíncrono: CLR é enviado de forma assíncrona; a resposta de sucesso significa que o CLR foi enviado, não que o MME o processou
  • Sem validação do status do MME: CLR é enviado mesmo se o MME estiver inacessível (comportamento padrão do HSS)
  • Idempotente: Seguro chamar várias vezes para o mesmo IMSI

Documentação Relacionada:

Dados do Repositório Sh (Dados Transparentes)​

Provisionamento de acesso aos documentos transparentes Sh de um assinante (MMTEL-Services, IMS-ODB-Information e outros). Estes são os mesmos documentos opacos que um Servidor de Aplicação lê e escreve pela interface Diameter Sh. O acesso é via GET/PUT/DELETE /api/subscriber/repository_data/:imsi.

Veja Dados do Repositório Sh (Dados Transparentes) para o modelo de dados, fluxos de mensagens, regras de concorrência de SequenceNumber e a referência completa da API REST.

Gerenciamento de MSISDN​

MSISDNs (números de telefone) podem ser atribuídos a assinantes para habilitar serviços de voz. Veja Documentação Multi-MSISDN para detalhes sobre a atribuição de vários números a um único assinante.

A bandeira shared​

Respostas que carregam um MSISDN incluem um shared booleano calculado e somente leitura. Ele é true quando o número é mantido por mais de um assinante (um número compartilhado multi-IMSI, por exemplo, um telefone e um smartwatch em SIMs separados), e false caso contrário. Ele aparece na entidade MSISDN (GET /api/msisdn e GET /api/msisdn/:id), em cada número embutido em um assinante (GET /api/subscriber/:id), e nos números de assinantes retornados por GET /api/subscriber/msisdn/:msisdn. Ele nunca é aceito em gravações; o HSS o calcula. Veja Resolução de MSISDN Através de Interfaces.

Listar MSISDNs​

Recuperar todos os números de telefone.

Endpoint: GET /api/msisdn

Exemplo de Requisição:

curl -k https://hss.example.com:8443/api/msisdn

Obter MSISDN​

Recuperar um número de telefone específico.

Endpoint: GET /api/msisdn/:id

Exemplo de Requisição:

curl -k https://hss.example.com:8443/api/msisdn/16fd2706-8baf-433b-82eb-8c7fada847da

Exemplo de Resposta:

{
  "status": "success",
  "response": {
    "id": "16fd2706-8baf-433b-82eb-8c7fada847da",
    "msisdn": "14155551234",
    "shared": false
  }
}

Criar MSISDN​

Criar um novo número de telefone.

Endpoint: POST /api/msisdn

Corpo da Requisição:

{
  "msisdn": {
    "msisdn": "14155551234"
  }
}

Validação:

  • Deve ter 1-15 dígitos
  • Deve ser único
  • Deve seguir o formato E.164 (formato internacional sem sinal de +)

Exemplo de Requisição:

curl -k -X POST https://hss.example.com:8443/api/msisdn \
  -H "Content-Type: application/json" \
  -d '{
    "msisdn": {
      "msisdn": "14155551234"
    }
  }'

Atribuir MSISDN a Assinante​

Para atribuir um número de telefone a um assinante, você precisa criar um registro de junção. Isso é tipicamente feito através do endpoint de atualização do assinante ou via manipulação direta do banco de dados.

Padrão Multi-MSISDN:

Veja Recursos Multi-MSISDN e Multi-IMSI para uso detalhado.

Excluir MSISDN​

Remover um número de telefone.

Endpoint: DELETE /api/msisdn/:id

Exemplo de Requisição:

curl -k -X DELETE https://hss.example.com:8443/api/msisdn/16fd2706-8baf-433b-82eb-8c7fada847da

Gerenciamento de Assinaturas IMS​

Uma Assinatura IMS agrupa vários assinantes (IMSIs / IMPIs) em uma única assinatura IMS que compartilha uma identidade pública e um único S-CSCF de atendimento. Veja Identidade Pública Compartilhada do Usuário.

Listar Assinaturas IMS​

Endpoint: GET /api/ims_subscription

curl -k https://hss.example.com:8443/api/ims_subscription

Obter Assinatura IMS​

Endpoint: GET /api/ims_subscription/:id

curl -k https://hss.example.com:8443/api/ims_subscription/16fd2706-8baf-433b-82eb-8c7fada847da

Criar Assinatura IMS​

Endpoint: POST /api/ims_subscription

curl -k -X POST https://hss.example.com:8443/api/ims_subscription \
  -H "Content-Type: application/json" \
  -d '{"name": "Família Smith - número compartilhado"}'

Campos:

  • name - Nome legível por humanos (obrigatório, único)
  • ims_profile_id - Perfil IMS compartilhado opcional para as identidades compartilhadas do grupo

assigned_scscf e last_seen_scscf_timestamp são estados em tempo de execução escritos pelo HSS e não são definidos pelo cliente.

Atualizar Assinatura IMS​

Endpoint: PATCH /api/ims_subscription/:id

Excluir Assinatura IMS​

Endpoint: DELETE /api/ims_subscription/:id

Excluir uma Assinatura IMS não exclui seus assinantes; seu ims_subscription_id é limpo. Para adicionar um assinante a um grupo, defina ims_subscription_id no assinante (veja Atualizar Assinante).

Gerenciamento de SIM​

Registros de cartão SIM armazenam informações físicas do cartão SIM, incluindo ICCID, detalhes do fornecedor, códigos PIN/PUK e chaves OTA. Os registros de SIM podem opcionalmente ser vinculados a assinantes.

Veja Também:

Listar SIMs​

Recuperar todos os cartões SIM.

Endpoint: GET /api/sim

Exemplo de Requisição:

curl -k https://hss.example.com:8443/api/sim

Obter SIM​

Recuperar um cartão SIM específico.

Endpoint: GET /api/sim/:id

Exemplo de Requisição:

curl -k https://hss.example.com:8443/api/sim/3f2504e0-4f89-41d3-9a0c-0305e82c3301

Criar SIM​

Criar um novo registro de cartão SIM.

Endpoint: POST /api/sim

Corpo da Requisição:

{
  "sim": {
    "iccid": "8991101200003204510",
    "sim_vendor": "Gemalto",
    "batch_name": "2025-Q1-Batch-01",
    "is_esim": false,
    "pin1": "1234",
    "pin2": "5678",
    "puk1": "12345678",
    "puk2": "87654321",
    "adm1": "admin-code-1",
    "kic": "0123456789ABCDEF0123456789ABCDEF",
    "kid": "FEDCBA9876543210FEDCBA9876543210"
  }
}

Campos Obrigatórios:

  • iccid - 19-20 dígitos, único

Campos Opcionais, mas Importantes:

  • sim_vendor - Nome do fabricante
  • batch_name - Para rastreamento
  • is_esim - Flag booleano para eSIM
  • pin1, pin2 - Códigos PIN do usuário final
  • puk1, puk2 - Códigos de desbloqueio PIN
  • adm1-adm10 - Códigos administrativos
  • kic, kid - Chaves de segurança OTA (string hex)

Exemplo de Requisição:

curl -k -X POST https://hss.example.com:8443/api/sim \
  -H "Content-Type: application/json" \
  -d '{
    "sim": {
      "iccid": "8991101200003204510",
      "sim_vendor": "Gemalto"
    }
  }'

Atualizar SIM​

Modifique os dados do cartão SIM.

Endpoint: PUT /api/sim/:id

Exemplo de Requisição:

curl -k -X PUT https://hss.example.com:8443/api/sim/3f2504e0-4f89-41d3-9a0c-0305e82c3301 \
  -H "Content-Type: application/json" \
  -d '{
    "sim": {
      "batch_name": "Updated-Batch-Name"
    }
  }'

Deletar SIM​

Remova um registro de cartão SIM.

Endpoint: DELETE /api/sim/:id

Aviso: Certifique-se de que nenhum assinante faça referência a este SIM antes de deletar.

Gerenciamento de Conjuntos de Chaves​

Os conjuntos de chaves contêm o material criptográfico (Ki, OPC/OP, AMF, SQN) usado para autenticação de assinantes via o algoritmo Milenage. Cada assinante deve referenciar um conjunto de chaves.

Veja Também:

Listar Conjuntos de Chaves​

Recupere todos os conjuntos de chaves criptográficas.

Endpoint: GET /api/key_set

Exemplo de Requisição:

curl -k https://hss.example.com:8443/api/key_set

Obter Conjunto de Chaves​

Recupere um conjunto de chaves específico.

Endpoint: GET /api/key_set/:id

Exemplo de Requisição:

curl -k https://hss.example.com:8443/api/key_set/6ba7b810-9dad-41d1-80b4-00c04fd430c8

Exemplo de Resposta:

{
  "data": {
    "id": "6ba7b810-9dad-41d1-80b4-00c04fd430c8",
    "ki": "0123456789ABCDEF0123456789ABCDEF",
    "opc": "FEDCBA9876543210FEDCBA9876543210",
    "op": null,
    "amf": "8000",
    "sqn": 0,
    "authentication_algorithm": "milenage",
    "ota_counter": 0
  }
}

Criar Conjunto de Chaves​

Crie um novo conjunto de chaves criptográficas.

Endpoint: POST /api/key_set

Corpo da Requisição:

{
  "key_set": {
    "ki": "0123456789ABCDEF0123456789ABCDEF",
    "opc": "FEDCBA9876543210FEDCBA9876543210",
    "amf": "8000",
    "sqn": 0,
    "authentication_algorithm": "milenage"
  }
}

Campos Obrigatórios:

  • ki - Chave de 128 bits (32 caracteres hex)
  • Ou opc OU op (OPC pode ser derivado de OP)
  • authentication_algorithm - Atualmente apenas "milenage"

Campos Opcionais:

  • amf - Padrão: "8000"
  • sqn - Padrão: 0
  • ota_counter - Padrão: 0

Formato da Chave:

  • Todas as chaves são strings hexadecimais
  • Ki, OPC, OP: 32 caracteres hex (128 bits)
  • AMF: 4 caracteres hex (16 bits)

Exemplo de Requisição:

curl -k -X POST https://hss.example.com:8443/api/key_set \
  -H "Content-Type: application/json" \
  -d '{
    "key_set": {
      "ki": "0123456789ABCDEF0123456789ABCDEF",
      "opc": "FEDCBA9876543210FEDCBA9876543210",
      "authentication_algorithm": "milenage"
    }
  }'

Aviso de Segurança: Os conjuntos de chaves contêm material criptográfico altamente sensível. Proteja o acesso à API de acordo.

Atualizar Conjunto de Chaves​

Modifique um conjunto de chaves existente.

Endpoint: PUT /api/key_set/:id

Aviso: Alterar chaves para um assinante ativo causará falhas de autenticação. Atualize as chaves apenas durante janelas de manutenção ou para novos assinantes.

Impacto: Atualizações afetam todos os assinantes que usam este conjunto de chaves imediatamente. Assinantes ativos falharão na autenticação na próxima tentativa de conexão.

Deletar Conjunto de Chaves​

Remova um conjunto de chaves.

Endpoint: DELETE /api/key_set/:id

Aviso: Certifique-se de que nenhum assinante faça referência a este conjunto de chaves antes de deletar. Consulte os assinantes primeiro para verificar referências.

Gerenciamento de Perfis​

Perfis EPC​

Os perfis EPC (Evolved Packet Core) definem parâmetros de serviço de dados para assinantes. Esses perfis são referenciados ao criar assinantes.

Listar Perfis EPC​

Endpoint: GET /api/epc/profile

Obter Perfil EPC​

Endpoint: GET /api/epc/profile/:id

Criar Perfil EPC​

Endpoint: POST /api/epc/profile

Corpo da Requisição:

{
  "apn_profiles": [],
  "name": "Plano de Dados Padrão",
  "network_access_mode": "packet_only",
  "tracking_area_update_interval_seconds": 600,
  "ue_ambr_dl_kbps": 100000,
  "ue_ambr_ul_kbps": 50000
}

Campos:

CampoDescriçãoUnidadesValores Típicos
nameNome do perfilTextoIdentificador único
ue_ambr_dl_kbpsLimite de largura de banda de downloadKbps10000-1000000
ue_ambr_ul_kbpsLimite de largura de banda de uploadKbps5000-500000
network_access_modeTipo de acessoString"packet_only" ou "packet_and_circuit"
tracking_area_update_interval_secondsTemporizador TAUSegundos600 (típico)
apn_profilesLista de IDs de perfis APNArray[] ou [1, 2, 3]

Exemplo de Requisição:

curl -k -X POST https://hss.example.com:8443/api/epc/profile \
  -H "Content-Type: application/json" \
  -d '{
    "apn_profiles": [],
    "name": "Premium 100Mbps",
    "network_access_mode": "packet_only",
    "tracking_area_update_interval_seconds": 600,
    "ue_ambr_dl_kbps": 100000,
    "ue_ambr_ul_kbps": 50000
  }'

Veja Também:

Atualizar Perfil EPC​

Endpoint: PUT /api/epc/profile/:id

Nota: Mudanças nos perfis EPC afetam todos os assinantes que usam este perfil. Sessões ativas podem precisar ser restabelecidas.

Deletar Perfil EPC​

Endpoint: DELETE /api/epc/profile/:id

Aviso: Certifique-se de que nenhum assinante faça referência a este perfil antes de deletar.

Perfis IMS​

Os perfis IMS (IP Multimedia Subsystem) definem parâmetros de serviço de voz e Critérios de Filtro Iniciais (IFC) para assinantes. Esses perfis são referenciados ao criar assinantes com serviços IMS habilitados.

Listar Perfis IMS​

Endpoint: GET /api/ims/profile

Criar Perfil IMS​

Endpoint: POST /api/ims/profile

Corpo da Requisição:

{
  "name": "VoLTE Padrão",
  "ifc_template": "<IMS-XML-Template-Here>"
}

Campos Obrigatórios:

  • name - Nome do perfil (deve ser único)
  • ifc_template - Template XML IFC (Critérios de Filtro Iniciais) com variáveis de template Liquid

Variáveis do Template IFC:

O template IFC suporta as seguintes variáveis de template Liquid que são substituídas dinamicamente:

VariávelDescriçãoValor Exemplo
{{ imsi }}IMSI do assinante001001123456789
{{ msisdns }}Array de MSISDNs (para loops)["14155551234", "14155555678"]
{{ mcc }}Código do País Móvel001
{{ mnc }}Código da Rede Móvel001

Como Funciona a Renderização do Template:

O template IFC é armazenado como um template Liquid (semelhante ao Jinja2) e é renderizado dinamicamente durante as operações IMS:

  1. Armazenamento: Quando você cria um perfil IMS, o template é armazenado como está com variáveis como {{ imsi }} e {% for msisdn in msisdns %}
  2. Validação: A API valida o template renderizando-o com dados de teste para garantir a sintaxe XML válida
  3. Renderização em Tempo de Execução: Quando um assinante realiza o registro IMS (MAA/SAA), o HSS:
    • Recupera o perfil IMS do assinante
    • Renderiza o template com os dados reais do assinante:
      • {{ imsi }} → IMSI do assinante
      • {{ msisdns }} → números de telefone do assinante
      • {{ mcc }} → Código do País Móvel configurado
      • {{ mnc }} → Código da Rede Móvel configurado
    • Retorna o XML renderizado para o S-CSCF via Cx/Diameter

Sintaxe do Template:

<!-- Substituição simples de variáveis -->
{{ imsi }}

<!-- Laços para arrays -->
{% for msisdn in msisdns %}
  <MSISDN>{{ msisdn }}</MSISDN>
{% endfor %}

<!-- Combinando variáveis -->
{{ imsi }}@ims.mnc{{ mnc }}.mcc{{ mcc }}.3gppnetwork.org

Exemplo de Template IFC:

<?xml version="1.0" encoding="UTF-8"?>
<IMSSubscription>
<PrivateID>{{ imsi }}@ims.mnc{{ mnc }}.mcc{{ mcc }}.3gppnetwork.org</PrivateID>
<ServiceProfile>
{% for msisdn in msisdns %}
<PublicIdentity>
<Identity>sip:{{ msisdn }}@ims.mnc{{ mnc }}.mcc{{ mcc }}.3gppnetwork.org</Identity>
<Extension>
<IdentityType>0</IdentityType>
</Extension>
</PublicIdentity>
<PublicIdentity>
<Identity>tel:{{ msisdn }}</Identity>
<Extension>
<IdentityType>0</IdentityType>
</Extension>
</PublicIdentity>
{% endfor %}
<InitialFilterCriteria>
<Priority>10</Priority>
<TriggerPoint>
<ConditionTypeCNF>0</ConditionTypeCNF>
<SPT>
<ConditionNegated>0</ConditionNegated>
<Group>0</Group>
<Method>REGISTER</Method>
</SPT>
</TriggerPoint>
<ApplicationServer>
<ServerName>sip:as.ims.mnc{{ mnc }}.mcc{{ mcc }}.3gppnetwork.org</ServerName>
<DefaultHandling>0</DefaultHandling>
</ApplicationServer>
</InitialFilterCriteria>
</ServiceProfile>
</IMSSubscription>

Exemplo de Requisição (curl):

curl -k -X POST https://hss.example.com:8443/api/ims/profile \
  -H "Content-Type: application/json" \
  -d '{
    "name": "default",
    "ifc_template": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><IMSSubscription><ServiceProfile>...</ServiceProfile></IMSSubscription>"
  }'

Exemplo de Requisição (Python):

import requests

response = requests.post(
    "https://hss.example.com:8443/api/ims/profile",
    json={
        "name": "default",
        "ifc_template": ifc_template_string
    },
    verify=False  # Para certificados autoassinados
)

Resposta de Sucesso (201 Criado):

{
  "status": "success",
  "response": {
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "name": "default",
    "ifc_template": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>..."
  }
}

Validação:

  • A API valida se o template IFC é um XML válido
  • Variáveis do template são renderizadas com dados de teste para verificar a sintaxe
  • O campo name deve ser único e não vazio

Veja Também:

Perfis APN​

Os perfis APN (Access Point Name) consistem em três componentes que trabalham juntos:

  1. Identificador APN - Define o nome do APN e a versão IP
  2. Perfil QoS APN - Define parâmetros de Qualidade de Serviço
  3. Perfil APN - Combina identificador e QoS, vinculado aos Perfis EPC

Veja a Documentação PCRF para configuração detalhada de políticas, gerenciamento de QoS e reautenticação automática. Veja também a Documentação de Perfis para exemplos de configuração de APN.

Listar Identificadores APN​

Endpoint: GET /api/apn/identifier

Criar Identificador APN​

Endpoint: POST /api/apn/identifier

Corpo da Requisição:

{
  "apn": "internet",
  "ip_version": "ipv4v6"
}

Valores da Versão IP:

  • "ipv4" - Apenas IPv4
  • "ipv6" - Apenas IPv6
  • "ipv4v6" - IPv4v6 (pilha dupla)
  • "ipv4_or_ipv6" - IPv4 ou IPv6 (escolha da rede)

Listar Perfis QoS APN​

Endpoint: GET /api/apn/qos_profile

Criar Perfil QoS APN​

Endpoint: POST /api/apn/qos_profile

Corpo da Requisição:

{
  "name": "Internet de Melhor Esforço",
  "allocation_retention_priority": 8,
  "apn_ambr_dl_kbps": 50000,
  "apn_ambr_ul_kbps": 25000,
  "pre_emption_capability": false,
  "pre_emption_vulnerability": true,
  "qci": 9
}

Listar Perfis APN​

Endpoint: GET /api/apn/profile

Criar Perfil APN​

Endpoint: POST /api/apn/profile

Corpo da Requisição:

{
  "apn_identifier_id": "4fa85f64-5717-4562-b3fc-2c963f66afa6",
  "apn_qos_profile_id": "8d8ac610-566d-4ef0-9c22-186b2a5ed793",
  "name": "APN de Internet"
}

Campos Obrigatórios:

Veja Também:

Gerenciamento de IP Estático​

Endereços IP estáticos podem ser atribuídos a APNs específicos para assinantes individuais. Isso permite que os assinantes recebam um endereço IPv4 e/ou IPv6 predeterminado ao se conectar a um APN específico, em vez de receber um endereço dinâmico de um pool DHCP.

Arquitetura:

Fluxo de Dados Quando o Assinante Conecta:

Resposta de Atualização de Localização - Mapeamento de Dados de Configuração do APN:

Este diagrama mostra exatamente de onde cada campo no AVP de Configuração do APN da Resposta de Atualização de Localização S6a vem no banco de dados:

Conceitos Chave:

  • Atribuição por APN: Cada IP Estático está vinculado a um Perfil APN específico
  • Um IP por APN por Assinante: Um assinante pode ter apenas uma atribuição de IP estático por APN
  • Suporte a IPv4 e IPv6: IPs estáticos podem ser apenas IPv4, apenas IPv6 ou dual-stack
  • Unicidade Global do IP: Cada endereço IP deve ser globalmente único em todos os registros de IPs estáticos no sistema
    • O mesmo endereço IPv4 ou IPv6 não pode ser atribuído a múltiplos assinantes (mesmo em APNs diferentes)
    • Isso previne conflitos de roteamento e ambiguidade de endereço IP
    • Imposto por índices únicos no banco de dados nos campos ipv4_static_ip e ipv6_static_ip
  • Relação Muitos-para-Muitos: Assinantes e IPs Estáticos estão vinculados através de uma tabela de junção

Casos de Uso:

  • Endereços IP fixos para dispositivos IoT
  • Hospedagem de servidores em dispositivos móveis (requer IP estático para conexões de entrada)
  • Aplicações legadas que requerem endereços IP específicos
  • Roteamento de políticas de rede com base no IP de origem
  • Conformidade regulatória que requer rastreamento de endereços IP

Listar IPs Estáticos​

Recuperar todas as atribuições de IPs estáticos.

Endpoint: GET /api/epc/static_ip

Exemplo de Requisição:

curl -k https://hss.example.com:8443/api/epc/static_ip

Exemplo de Resposta:

{
  "data": [
    {
      "id": "c56a4180-65aa-42ec-a945-5fd21dec0538",
      "apn_profile_id": "a1b2c3d4-e5f6-4a3b-8c2d-1e0f9a8b7c6d",
      "ipv4_static_ip": "100.64.1.1",
      "ipv6_static_ip": "2606:4700:4700::1111",
      "apn_profile": {
        "id": "a1b2c3d4-e5f6-4a3b-8c2d-1e0f9a8b7c6d",
        "name": "Internet APN",
        "apn_identifier": {
          "apn": "internet",
          "ip_version": "ipv4v6"
        }
      },
      "inserted_at": "2025-11-15T10:30:00Z",
      "updated_at": "2025-11-15T10:30:00Z"
    }
  ]
}

Obter IP Estático​

Recuperar uma atribuição de IP estático específica.

Endpoint: GET /api/epc/static_ip/:id

Parâmetros de Caminho:

ParâmetroTipoDescrição
idstring (UUID)ID do banco de dados do IP estático

Exemplo de Requisição:

curl -k https://hss.example.com:8443/api/epc/static_ip/c56a4180-65aa-42ec-a945-5fd21dec0538

Criar IP Estático​

Criar uma nova atribuição de IP estático para um APN.

Endpoint: POST /api/epc/static_ip

Corpo da Requisição:

{
  "static_ip": {
    "apn_profile_id": "a1b2c3d4-e5f6-4a3b-8c2d-1e0f9a8b7c6d",
    "ipv4_static_ip": "100.64.1.1",
    "ipv6_static_ip": "2606:4700:4700::1111"
  }
}

Campos Obrigatórios:

  • apn_profile_id - Deve referenciar um Perfil APN existente
  • Pelo menos um dos campos ipv4_static_ip OU ipv6_static_ip deve ser especificado

Campos Opcionais:

  • ipv4_static_ip - Endereço IPv4 (notação decimal pontuada)
  • ipv6_static_ip - Endereço IPv6 (notação padrão)

Validação do Formato do IP:

  • IPv4: Formato padrão decimal pontuado (ex: 100.64.1.1)
  • IPv6: Formato padrão hexadecimal separado por dois pontos (ex: 2606:4700:4700::1111)
  • Ambos os endereços IPv4 e IPv6 devem ser globalmente únicos em todos os registros de IPs estáticos
    • Isso previne conflitos de endereços IP na rede
    • O mesmo IP não pode ser atribuído a múltiplos assinantes, mesmo em APNs diferentes
    • Esta é uma restrição a nível de banco de dados imposta por índices únicos

Opções de Configuração:

ConfiguraçãoIPv4IPv6Exemplo
Apenas IPv4✓-{"ipv4_static_ip": "100.64.1.1"}
Apenas IPv6-✓{"ipv6_static_ip": "2606:4700:4700::1111"}
Dual Stack✓✓Ambos os campos especificados

Exemplos de Requisições:

IP Estático apenas IPv4:

curl -k -X POST https://hss.example.com:8443/api/epc/static_ip \
  -H "Content-Type: application/json" \
  -d '{
    "static_ip": {
      "apn_profile_id": "a1b2c3d4-e5f6-4a3b-8c2d-1e0f9a8b7c6d",
      "ipv4_static_ip": "100.64.1.1"
    }
  }'

IP Estático apenas IPv6:

curl -k -X POST https://hss.example.com:8443/api/epc/static_ip \
  -H "Content-Type: application/json" \
  -d '{
    "static_ip": {
      "apn_profile_id": "b2c3d4e5-f6a7-4b1c-9d2e-3f4a5b6c7d8e",
      "ipv6_static_ip": "2606:4700:4700::1111"
    }
  }'

IP Estático dual-stack:

curl -k -X POST https://hss.example.com:8443/api/epc/static_ip \
  -H "Content-Type: application/json" \
  -d '{
    "static_ip": {
      "apn_profile_id": "a1b2c3d4-e5f6-4a3b-8c2d-1e0f9a8b7c6d",
      "ipv4_static_ip": "100.64.1.1",
      "ipv6_static_ip": "2606:4700:4700::1111"
    }
  }'

Resposta de Sucesso (201 Criado):

{
  "data": {
    "id": "c56a4180-65aa-42ec-a945-5fd21dec0538",
    "apn_profile_id": "a1b2c3d4-e5f6-4a3b-8c2d-1e0f9a8b7c6d",
    "ipv4_static_ip": "100.64.1.1",
    "ipv6_static_ip": "2606:4700:4700::1111",
    "inserted_at": "2025-11-15T10:30:00Z",
    "updated_at": "2025-11-15T10:30:00Z"
  }
}

Veja Também:

Atualizar IP Estático​

Modificar uma atribuição de IP estático existente.

Endpoint: PUT /api/epc/static_ip/:id

Parâmetros de Caminho:

ParâmetroTipoDescrição
idstring (UUID)ID do banco de dados do IP estático

Corpo da Requisição:

{
  "static_ip": {
    "ipv4_static_ip": "100.64.1.2",
    "ipv6_static_ip": "2606:4700:4700::1112"
  }
}

Campos Atualizáveis:

  • ipv4_static_ip - Alterar endereço IPv4
  • ipv6_static_ip - Alterar endereço IPv6
  • apn_profile_id - Alterar atribuição de APN

Não Atualizável:

  • id - Chave primária (somente leitura)

Aviso: Alterar o endereço IP de um assinante ativo afetará sua próxima conexão PDN. Sessões PDN ativas continuarão a usar o IP antigo até desconectar e reconectar.

Exemplo de Requisição:

curl -k -X PUT https://hss.example.com:8443/api/epc/static_ip/c56a4180-65aa-42ec-a945-5fd21dec0538 \
  -H "Content-Type: application/json" \
  -d '{
    "static_ip": {
      "ipv4_static_ip": "100.64.1.2"
    }
  }'

Deletar IP Estático​

Remover uma atribuição de IP estático.

Endpoint: DELETE /api/epc/static_ip/:id

Parâmetros de Caminho:

ParâmetroTipoDescrição
idstring (UUID)ID do banco de dados do IP estático

Exemplo de Requisição:

curl -k -X DELETE https://hss.example.com:8443/api/epc/static_ip/c56a4180-65aa-42ec-a945-5fd21dec0538

Comportamento:

  • Remove a atribuição de IP estático
  • NÃO afeta o Perfil APN (APN permanece disponível para outros assinantes)
  • Assinantes usando este IP estático receberão IPs dinâmicos na próxima conexão
  • O endereço IP se torna disponível para reutilização após a exclusão

Aviso: Se um assinante estiver usando ativamente este IP estático, excluí-lo fará com que receba um IP dinâmico em sua próxima conexão PDN. Certifique-se de que os assinantes estejam offline ou envie uma Solicitação de Cancelamento de Localização antes de excluir.

Atribuir IP Estático a Assinante​

Para atribuir um IP estático a um assinante, você precisa associar o registro de IP Estático ao Assinante durante a criação ou atualização.

Padrão de Atribuição:

  1. Criar o IP Estático (veja Criar IP Estático)
  2. Atribuir ao Assinante usando o campo static_ips

Criar Assinante com IP Estático:

# Etapa 1: Criar IP estático para APN "internet"
STATIC_IP_ID=$(curl -k -X POST https://hss.example.com:8443/api/epc/static_ip \
  -H "Content-Type: application/json" \
  -d '{
    "static_ip": {
      "apn_profile_id": "a1b2c3d4-e5f6-4a3b-8c2d-1e0f9a8b7c6d",
      "ipv4_static_ip": "100.64.1.1",
      "ipv6_static_ip": "2606:4700:4700::1111"
    }
  }' | jq -r '.data.id')

# Etapa 2: Criar assinante com IP estático atribuído
curl -k -X POST https://hss.example.com:8443/api/subscriber \
  -H "Content-Type: application/json" \
  -d "{
    \"subscriber\": {
      \"imsi\": \"001001123456789\",
      \"key_set_id\": \"6ba7b810-9dad-41d1-80b4-00c04fd430c8\",
      \"epc_profile_id\": \"e58ed763-928c-4155-bee9-fdbaaadc15f3\",
      \"static_ips\": [$STATIC_IP_ID]
    }
  }"

Atualizar Assinante Existente com IP Estático:

curl -k -X PUT https://hss.example.com:8443/api/subscriber/d290f1ee-6c54-4b01-90e6-d701748f0851 \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber": {
      "static_ips": ["c56a4180-65aa-42ec-a945-5fd21dec0538", "5a8f9c3e-2d4b-4e6f-8a1b-3c5d7e9f0a2b"]
    }
  }'

Múltiplos IPs Estáticos (APNs Diferentes):

Um assinante pode ter múltiplos IPs estáticos desde que cada um seja para um APN diferente:

# Criar IP estático para APN "internet"
INTERNET_IP=$(curl -k -X POST https://hss.example.com:8443/api/epc/static_ip \
  -H "Content-Type: application/json" \
  -d '{
    "static_ip": {
      "apn_profile_id": "a1b2c3d4-e5f6-4a3b-8c2d-1e0f9a8b7c6d",
      "ipv4_static_ip": "100.64.1.1"
    }
  }' | jq -r '.data.id')

# Criar IP estático para APN "ims"
IMS_IP=$(curl -k -X POST https://hss.example.com:8443/api/epc/static_ip \
  -H "Content-Type: application/json" \
  -d '{
    "static_ip": {
      "apn_profile_id": "b2c3d4e5-f6a7-4b1c-9d2e-3f4a5b6c7d8e",
      "ipv4_static_ip": "100.64.2.1"
    }
  }' | jq -r '.data.id')

# Atribuir ambos ao assinante
curl -k -X POST https://hss.example.com:8443/api/subscriber \
  -H "Content-Type: application/json" \
  -d "{
    \"subscriber\": {
      \"imsi\": \"001001123456789\",
      \"key_set_id\": \"6ba7b810-9dad-41d1-80b4-00c04fd430c8\",
      \"epc_profile_id\": \"e58ed763-928c-4155-bee9-fdbaaadc15f3\",
      \"static_ips\": [$INTERNET_IP, $IMS_IP]
    }
  }"

Regras de Validação:

  • ✓ Permitido: Múltiplos IPs estáticos para APNs diferentes
  • ✗ Rejeitado: Múltiplos IPs estáticos para o mesmo APN

Exemplo de Erro - APN Duplicado:

# Isso irá FALHAR se ambos os IPs estáticos referenciando o mesmo APN
curl -k -X POST https://hss.example.com:8443/api/subscriber \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber": {
      "imsi": "001001123456789",
      "static_ips": ["c56a4180-65aa-42ec-a945-5fd21dec0538", "5a8f9c3e-2d4b-4e6f-8a1b-3c5d7e9f0a2b"]
    }
  }'

# Resposta de Erro:
{
  "errors": {
    "static_ips": [
      "static ips per apn per subscriber must be unique. eg a subscriber may not be assigned static ip 100.64.1.1 for internet and also 100.64.1.2 for internet"
    ]
  }
}

Veja Também:

Gerenciamento de Roaming​

Perfis de roaming controlam se os assinantes podem acessar dados e serviços IMS em redes visitadas. Perfis são atribuídos a assinantes e consistem em regras correspondidas por MCC/MNC.

Listar Perfis de Roaming​

Endpoint: GET /api/roaming/profile

Criar Perfil de Roaming​

Endpoint: POST /api/roaming/profile

Corpo da Requisição:

{
  "roaming_profile": {
    "name": "Apenas Operadoras dos EUA",
    "data_action_if_no_rules_match": "deny",
    "ims_action_if_no_rules_match": "deny",
    "roaming_rules": []
  }
}

Valores de Ação:

  • "allow" - Permitir
  • "deny" - Negar

Ações Padrão:

  • data_action_if_no_rules_match - Ação quando nenhuma regra de roaming corresponde
  • ims_action_if_no_rules_match - Ação padrão específica para IMS

Listar Regras de Roaming​

Endpoint: GET /api/roaming/rule

Criar Regra de Roaming​

Endpoint: POST /api/roaming/rule

Corpo da Requisição:

{
  "roaming_rule": {
    "name": "Permitir AT&T",
    "mcc": "310",
    "mnc": "410",
    "data_action": "allow",
    "ims_action": "allow"
  }
}

Campos:

  • mcc - Código do País Móvel (3 dígitos)
  • mnc - Código da Rede Móvel (2-3 dígitos)
  • data_action - "allow" ou "deny" serviços de dados
  • ims_action - "allow" ou "deny" serviços IMS/vídeo

Veja Também:

Gerenciamento de EIR​

OmniHSS funciona como um Registro de Identidade de Equipamento (EIR) através da interface Diameter S13. Regras de EIR controlam o acesso de dispositivos com base em padrões de IMEI.

Veja Documentação de EIR para verificação detalhada da identidade do equipamento, fluxos da interface S13 e validação de IMEI.

Listar Regras de EIR​

Endpoint: GET /api/eir/rule

Criar Regra de EIR​

Endpoint: POST /api/eir/rule

Corpo da Requisição:

{
  "eir_rule": {
    "name": "Bloquear iPhone 6",
    "imei_regex": "^35[0-9]{6}0[0-9]{7}$",
    "action": 1
  }
}

Campos:

  • name - Nome descritivo para a regra
  • imei_regex - Expressão regular para corresponder números IMEI
  • action - Lista Branca (0), Lista Negra (1) ou Lista Cinza (2)

Valores de Ação:

  • 0 - Lista Branca (permitir)
  • 1 - Lista Negra (negar)
  • 2 - Lista Cinza (permitir, mas rastrear)

Casos de Uso:

  • Bloquear dispositivos roubados (lista negra de IMEIs específicos)
  • Restringir tipos de dispositivos (lista negra por padrão TAC)
  • Permitir apenas dispositivos aprovados (padrão de lista branca com negação padrão)

Veja Também:

Documentação Adicional​

Para mais informações, consulte a documentação a seguir:

← Voltar ao Guia de Operações | Próximo: Painel de Controle →

Última atualização em