Referência da API OmniHSS

Índice

Visão Geral da API
Gerenciamento de Conjuntos de Chaves
Gerenciamento de Assinantes
Dados do Repositório Sh (Dados Transparentes)
Gerenciamento de MSISDN
Gerenciamento de SIM
Gerenciamento de Conjuntos de Chaves
Gerenciamento de Perfis
Gerenciamento de IPs Estáticos
Gerenciamento de Roaming
Gerenciamento de EIR
Status e Saúde
Tratamento de Erros
Exemplos de Uso da API

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ódigo	Significado	Caso de Uso
200	OK	GET, PUT, DELETE bem-sucedidos
201	Criado	POST bem-sucedido
400	Requisição Inválida	Dados de entrada inválidos
404	Não Encontrado	Recurso não existe
422	Entidade Não Processável	Erro de validação
500	Erro Interno do Servidor	Erro 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âmetro	Tipo	Descrição
`enabled`	boolean	Filtrar por status habilitado
`ims_enabled`	boolean	Filtrar 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âmetro	Tipo	Descrição
`id`	string (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âmetro	Tipo	Descrição	Formato
`imsi`	string	Identidade do Assinante Móvel Internacional	14-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âmetro	Tipo	Descrição	Formato
`msisdn`	string	Número ISDN da Estação Móvel	1-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 a um cartão SIM
ims_profile_id - Referência a um Perfil IMS (obrigatório para serviços IMS)
roaming_profile_id - Referência a um 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
custom_attributes - Pares chave-valor personalizados

Veja Também:

Exemplo Completo de Provisionamento de Assinante - Fluxo de trabalho de ponta a ponta
Documentação Multi-MSISDN - Atribuindo números de telefone a assinantes
Gerenciamento de IP Estático - Atribuindo IPs estáticos a APNs

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âmetro	Tipo	Descrição
`id`	string (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:

enabled - Habilitar/desabilitar todos os serviços
ims_enabled - Habilitar/desabilitar serviços IMS
sim_id - Alterar atribuição de cartão SIM
key_set_id - Alterar chaves criptográficas (cuidado!)
epc_profile_id - Alterar perfil de serviço de dados
ims_profile_id - Alterar perfil de serviço de voz
roaming_profile_id - Alterar política de roaming
msisdns - Atualizar números de telefone atribuídos ao assinante
static_ips - Atualizar atribuições de IP estático para APNs
custom_attributes - Atualizar dados personalizados

Não Atualizável:

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

Veja Também:

Gerenciamento de Perfis - Gerenciando perfis de serviço

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)

Deletar Assinante

Remover um assinante do sistema.

Endpoint: DELETE /api/subscriber/:id

Parâmetros de Caminho:

Parâmetro	Tipo	Descrição
`id`	string (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

Aviso: 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 registrado atualmente.

Endpoint: POST /api/subscriber/cancel_location

Corpo da Requisição:

{
  "imsi": "001001123456789"
}

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`imsi`	string	Sim	IMSI 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 é 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 de 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 sobre Multi-IMSI:

Ao usar CLR com cenários multi-MSISDN:

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)

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 que o MME esteja 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, …) — os mesmos documentos opacos que um Servidor de Aplicação lê e escreve através da interface Diameter Sh — 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 do 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 múltiplos números a um único assinante.

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

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.

Deletar 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 SIM

Os registros de cartões 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 ser opcionalmente vinculados a assinantes.

Veja Também:

Documentação Multi-IMSI - Múltiplos assinantes em um único SIM físico

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 booleana 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 hexadecimal)

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

Modificar 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": "Nome do Lote Atualizado"
    }
  }'

Deletar SIM

Remover 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 excluir.

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 algoritmo Milenage. Cada assinante deve referenciar um conjunto de chaves.

Veja Também:

Fluxos de Protocolo - Procedimentos de autenticação usando conjuntos de chaves

Listar Conjuntos de Chaves

Recuperar 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

Recuperar 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

Criar 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 hexadecimais)
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 hexadecimais (128 bits)
AMF: 4 caracteres hexadecimais (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: Conjuntos de chaves contêm material criptográfico altamente sensível. Proteja o acesso à API de acordo.

Atualizar Conjunto de Chaves

Modificar 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

Remover 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 excluir. 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:

Campo	Descrição	Unidades	Valores Típicos
`name`	Nome do perfil	Texto	Identificador único
`ue_ambr_dl_kbps`	Limite de largura de banda de download	Kbps	10000-1000000
`ue_ambr_ul_kbps`	Limite de largura de banda de upload	Kbps	5000-500000
`network_access_mode`	Tipo de acesso	String	"packet_only" ou "packet_and_circuit"
`tracking_area_update_interval_seconds`	Timer TAU	Segundos	600 (típico)
`apn_profiles`	Lista de IDs de perfis APN	Array	[] 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:

Documentação de Perfis - Guia detalhado de configuração de perfil
Provisionamento Completo de Assinantes - Usando perfis EPC no provisionamento

Atualizar Perfil EPC

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

Nota: Alterações 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 excluir.

Perfis IMS

Os perfis IMS (IP Multimedia Subsystem) definem parâmetros de serviço de voz e Critérios de Filtro Inicial (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": "Padrão VoLTE",
  "ifc_template": "<IMS-XML-Template-Here>"
}

Campos Obrigatórios:

name - Nome do perfil (deve ser único)
ifc_template - Template IFC (Critérios de Filtro Inicial) XML 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ável	Descrição	Valor Exemplo
`{{ imsi }}`	IMSI do assinante	`001001123456789`
`{{ msisdns }}`	Array de MSISDNs (para loops)	`["14155551234", "14155555678"]`
`{{ mcc }}`	Código do País Móvel	`001`
`{{ mnc }}`	Código da Rede Móvel	`001`

Como Funciona a Renderização do Template:

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

Armazenamento: Quando você cria um perfil IMS, o template é armazenado como está com variáveis como {{ imsi }} e {% for msisdn in msisdns %}
Validação: A API valida o template renderizando-o com dados de teste para garantir a sintaxe XML válida
Renderização em Tempo de Execução: Quando um assinante realiza 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ável -->
{{ 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 que 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:

Documentação de Perfis - Detalhes e exemplos do template IFC
Fluxos de Protocolo - Fluxos de registro IMS e chamadas
Template IFC Padrão - Implementação de referência

Perfis APN

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

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

Veja Documentação PCRF para configuração detalhada de políticas, gerenciamento de QoS e reautenticação automática. Veja também 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 (dual stack)
"ipv4_or_ipv6" - IPv4 ou IPv6 (escolha da rede)

Listar Perfis QoS do APN

Endpoint: GET /api/apn/qos_profile

Criar Perfil QoS do 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 da Internet"
}

Campos Obrigatórios:

apn_identifier_id - Deve referenciar um Identificador APN existente
apn_qos_profile_id - Deve referenciar um Perfil QoS do APN existente

Veja Também:

Provisionamento Completo de Assinantes - Exemplo completo incluindo configuração de APN
Perfis EPC - Perfis APN estão vinculados a perfis EPC

Gerenciamento de IPs Estáticos

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:

Observações Chave:

Identificador de Contexto: Índice sequencial (0, 1, 2...) para cada APN no perfil
Seleção de Serviço: Vem diretamente de apn_identifier.apn (por exemplo, "internet", "ims")
Tipo de PDN: Codificado a partir de apn_identifier.ip_version (ipv4=0, ipv6=1, ipv4v6=2, ipv4_or_ipv6=3)
Parâmetros de QoS: Todos da tabela apn_qos_profile
Largura de Banda AMBR: Valores são multiplicados por 1000 (kbps → bps)
Endereço IP do Parte Servida: Incluído apenas se um IP estático existir para esta combinação assinante+APN
- Processo de busca: subscriber.static_ips → filtrar por apn_profile_id → extrair IPs
- Compatibilidade da versão IP verificada em relação a apn_identifier.ip_version
VPLMN-Dynamic-Address-Allowed: Codificado como 0 (não permitido) - força o uso de IP estático se fornecido

Hierarquia de Relacionamento:

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 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 IP estático no sistema
- O mesmo endereço IPv4 ou IPv6 não pode ser atribuído a múltiplos assinantes (mesmo em APNs diferentes)
- Isso evita 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
Relacionamento 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 exige rastreamento de endereços IP

Listar IPs Estáticos

Recuperar todas as atribuições de IP estático.

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": "APN da Internet",
        "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âmetro	Tipo	Descrição
`id`	string (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 de 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 (por exemplo, 100.64.1.1)
IPv6: Formato padrão hexadecimal separado por dois pontos (por exemplo, 2606:4700:4700::1111)
Ambos os endereços IPv4 e IPv6 devem ser globalmente únicos em todos os registros de IP estático
- Isso evita conflitos de endereço IP na rede
- O mesmo IP não pode ser atribuído a múltiplos assinantes, mesmo em APNs diferentes
- Esta é uma restrição de nível de banco de dados imposta por índices únicos

Opções de Configuração:

Configuração	IPv4	IPv6	Exemplo
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:

Atribuir IP Estático a Assinante - Como vincular isso a um assinante
Perfis APN - Gerenciando configurações de APN

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âmetro	Tipo	Descrição
`id`	string (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 para 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âmetro	Tipo	Descrição
`id`	string (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 eles recebam um IP dinâmico em sua próxima conexão PDN. Certifique-se de que os assinantes estejam offline ou envie uma Requisiçã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:

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

Criar Assinante com IP Estático:

# Passo 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')

# Passo 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\": {

Índice​

Visão Geral da API​

URL Base​

Formato da Requisição​

Formato da Resposta​

Códigos de Status HTTP​

Fluxo de Requisição da API​

Gerenciamento de Assinantes​

Listar Assinantes​

Obter Assinante por ID​

Obter Assinante por IMSI​

Obter Assinante por MSISDN​

Criar Assinante​

Atualizar Assinante​

Deletar Assinante​

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

Dados do Repositório Sh (Dados Transparentes)​

Gerenciamento de MSISDN​

Listar MSISDNs​

Obter MSISDN​

Criar MSISDN​

Atribuir MSISDN a Assinante​

Deletar MSISDN​

Gerenciamento de SIM​

Listar SIMs​

Obter SIM​

Criar SIM​

Atualizar SIM​

Deletar SIM​

Gerenciamento de Conjuntos de Chaves​

Listar Conjuntos de Chaves​

Obter Conjunto de Chaves​

Criar Conjunto de Chaves​

Atualizar Conjunto de Chaves​

Deletar Conjunto de Chaves​

Gerenciamento de Perfis​

Perfis EPC​

Listar Perfis EPC​

Obter Perfil EPC​

Criar Perfil EPC​

Atualizar Perfil EPC​

Deletar Perfil EPC​

Perfis IMS​

Listar Perfis IMS​

Criar Perfil IMS​

Perfis APN​

Listar Identificadores APN​

Criar Identificador APN​

Listar Perfis QoS do APN​

Criar Perfil QoS do APN​

Listar Perfis APN​

Criar Perfil APN​

Gerenciamento de IPs Estáticos​

Listar IPs Estáticos​

Obter IP Estático​

Criar IP Estático​

Atualizar IP Estático​

Deletar IP Estático​

Atribuir IP Estático a Assinante​

Índice

Visão Geral da API

URL Base

Formato da Requisição

Formato da Resposta

Códigos de Status HTTP

Fluxo de Requisição da API

Gerenciamento de Assinantes

Listar Assinantes

Obter Assinante por ID

Obter Assinante por IMSI

Obter Assinante por MSISDN

Criar Assinante

Atualizar Assinante

Deletar Assinante

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

Dados do Repositório Sh (Dados Transparentes)

Gerenciamento de MSISDN

Listar MSISDNs

Obter MSISDN

Criar MSISDN

Atribuir MSISDN a Assinante

Deletar MSISDN

Gerenciamento de SIM

Listar SIMs

Obter SIM

Criar SIM

Atualizar SIM

Deletar SIM

Gerenciamento de Conjuntos de Chaves

Listar Conjuntos de Chaves

Obter Conjunto de Chaves

Criar Conjunto de Chaves

Atualizar Conjunto de Chaves

Deletar Conjunto de Chaves

Gerenciamento de Perfis

Perfis EPC

Listar Perfis EPC

Obter Perfil EPC

Criar Perfil EPC

Atualizar Perfil EPC

Deletar Perfil EPC

Perfis IMS

Listar Perfis IMS

Criar Perfil IMS

Perfis APN

Listar Identificadores APN

Criar Identificador APN

Listar Perfis QoS do APN

Criar Perfil QoS do APN

Listar Perfis APN

Criar Perfil APN

Gerenciamento de IPs Estáticos

Listar IPs Estáticos

Obter IP Estático

Criar IP Estático

Atualizar IP Estático

Deletar IP Estático

Atribuir IP Estático a Assinante