Guia de Configuração do Cliente MAP

← Voltar para a Documentação Principal

Este guia cobre a operação do OmniSS7 como um Cliente MAP — conectando-se a uma rede SS7 como um Processo de Servidor de Aplicação (ASP) e emitindo operações MAP (Mobile Application Part) em direção a HLRs, MSC/VLRs, SGSNs, GMLCs e outros elementos da rede central. O comportamento do protocolo segue 3GPP TS 29.002.

Índice

1. O que é o Modo Cliente MAP?
2. Habilitando o Modo Cliente MAP
3. Referência de Operações MAP
4. Exemplos Comuns de Operações
5. Enviando Solicitações via API
6. Métricas e Monitoramento
7. Solução de Problemas

---

O que é o Modo Cliente MAP?

Modo Cliente MAP permite que o OmniSS7 se conecte como um Processo de Servidor de Aplicação (ASP) a um par M3UA (STP ou SGP) via SCTP e troque mensagens MAP. Cada operação é exposta como um endpoint HTTP: uma solicitação à API é codificada como um diálogo TCAP/MAP, transportado via SCCP e M3UA para a rede SS7, e a resposta da rede é decodificada e retornada de forma síncrona ao chamador.

Usos típicos incluem:

• Gerenciamento de mobilidade — Atualizar Localização, Cancelar Localização, Purgar MS, Fornecer Número de Roaming
• Tratamento de chamadas — Enviar Informações de Roteamento, Fornecer Informações do Assinante
• SMS — SRI-for-SM, MO/MT-ForwardSM, relatórios de status de entrega
• Autenticação — Enviar Informações de Autenticação
• Dados do assinante — Inserir/Excluir Dados do Assinante, Interrogação a Qualquer Momento
• Serviços suplementares — registrar/ apagar/ ativar/ interrogar SS, gerenciamento de senhas
• Serviços de localização (LCS) e roteamento GPRS

Arquitetura da Rede

---

Habilitando o Modo Cliente MAP

O modo Cliente MAP é configurado em config/runtime.exs. Para a referência completa de conexão M3UA, veja Parâmetros de Conexão M3UA.

config :omniss7,
  # Habilitar o modo Cliente MAP
  map_client_enabled: true,

  # Conexão M3UA para o Cliente MAP (conecta como um ASP a um STP/SGP remoto)
  map_client_m3ua: %{
    mode: "ASP",
    callback: {MapClient, :handle_payload, []},
    process_name: :map_client_asp,
    local_ip: {10, 0, 0, 100},
    local_port: 2905,
    remote_ip: {10, 0, 0, 1},
    remote_port: 2905,
    routing_context: 1
  }

Parâmetros map_client_m3ua

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
mode	String	Sim	-	Papel M3UA. "ASP" para modo cliente (conecta-se a um STP/SGP).
callback	Tupla	Sim	-	{Módulo, Função, Args} invocada para cada carga M3UA recebida. Para o Cliente MAP, isso é {MapClient, :handle_payload, []}.
process_name	Átomo	Sim	-	Nome registrado do processo M3UA ASP.
local_ip	Tupla	Sim	-	Endereço de ligação SCTP local como uma tupla IP, por exemplo, {10, 0, 0, 100}.
local_port	Inteiro	Não	2905	Porta SCTP local. 2905 é a porta M3UA registrada na IANA.
remote_ip	Tupla	Sim	-	Endereço IP remoto do STP/SGP como uma tupla.
remote_port	Inteiro	Não	2905	Porta SCTP remota do STP/SGP.
routing_context	Inteiro	Não	-	Valor do Contexto de Roteamento M3UA, quando o par requer um.

Chaves de nível superior: map_client_enabled (Booleano, padrão false) ativa o Cliente MAP; map_client_m3ua (Mapa) contém a conexão acima.

O endereçamento SCCP aplicado às operações de saída (Títulos Globais da Parte Chamadora/Chamado, SSNs, códigos de ponto) é configurado separadamente — veja a Referência de Configuração.

---

Referência de Operações MAP

Cada operação abaixo é acessível como POST /api/<endpoint>. Os opcodes são os códigos de operação MAP do 3GPP TS 29.002. As solicitações são síncronas: a API bloqueia até que a resposta SS7 chegue ou a solicitação expire (veja Códigos de Resposta).

Gerenciamento de Mobilidade

Operação	Endpoint	Opcode	Descrição
Atualizar Localização	/api/updateLocation	2	Registrar o VLR de atendimento de um assinante com o HLR.
Cancelar Localização	/api/cancelLocation	3	Instruir um VLR a excluir um registro de assinante.
Fornecer Número de Roaming	/api/prn	4	Obter um MSRN do MSC de atendimento.
Purgar MS	/api/purgeMS	67	Marcar um assinante como purgado no HLR.
Enviar Identificação	/api/sendIdentification	55	Recuperar IMSI/dados de autenticação do VLR anterior.
Resetar	/api/reset	37	Resetar iniciado pelo HLR em direção a um VLR.
Restaurar Dados	/api/restoreData	57	O VLR solicita a restauração dos dados do assinante do HLR.

Tratamento de Chamadas & Dados do Assinante

Operação	Endpoint	Opcode	Descrição
Enviar Informações de Roteamento	/api/sri	22	Consultar o HLR para informações de roteamento de chamadas de voz.
Fornecer Informações do Assinante	/api/provideSubscriberInfo	70	Solicitar estado/localizaç��o do assinante ao VLR.
Excluir Dados do Assinante	/api/deleteSubscriberData	8	Remover dados do assinante no VLR.
Interrogação a Qualquer Momento	/api/anyTimeInterrogation	71	gsmSCF consulta informações/localização do assinante no HLR.
Interrogação de Assinatura a Qualquer Momento	/api/anyTimeSubscriptionInterrogation	62	Consultar dados de assinatura no HLR.
Modificação a Qualquer Momento	/api/anyTimeModification	65	Modificar dados de assinatura no HLR.
Notificar Dados do Assinante Modificados	/api/noteSubscriberDataModified	5	HLR notifica o gsmSCF sobre dados alterados.
Notificar Evento MM	/api/noteMM-Event	89	Relatar um evento de gerenciamento de mobilidade ao gsmSCF.

SMS

Operação	Endpoint	Opcode	Descrição
Enviar Informações de Roteamento para SM	/api/sri-for-sm	45	Consultar o HLR para o nó de atendimento para entrega de SMS.
MT-Forward SM	/api/MT-forwardSM	44	Entregar um SM terminado em móvel ao MSC/SGSN de atendimento.
MO-Forward SM	/api/forwardSM	46	Enviar um SM originado em móvel ao SMSC.
Enviar SM (PDU)	/api/sendSM, /api/deliverPDU	44	Construir e entregar um PDU SMS-DELIVER.
Relatar Status de Entrega de SM	/api/reportSM-DeliveryStatus	47	Relatar o resultado da entrega de SM ao HLR.
Pronto para SM	/api/readyForSM	66	Notificar o HLR que um MS está acessível para SMS.
Alertar Centro de Serviço	/api/alertServiceCentre	64	Alertar um SMSC que um assinante está disponível.

Autenticação & Equipamento

Operação	Endpoint	Opcode	Descrição
Enviar Informações de Autenticação	/api/send-auth-info	56	Recuperar vetores de autenticação do HLR.
Enviar IMSI	/api/sendIMSI	58	Resolver um MSISDN para seu IMSI no HLR.
Verificar IMEI	/api/checkIMEI	43	Consultar status do equipamento no EIR.

Serviços Suplementares

Operação	Endpoint	Opcode	Descrição
Registrar SS	/api/registerSS	10	Registrar um serviço suplementar (por exemplo, desvio de chamada / CFU).
Apagar SS	/api/eraseSS	11	Apagar um serviço suplementar.
Ativar SS	/api/activateSS	12	Ativar um serviço suplementar.
Desativar SS	/api/deactivateSS	13	Desativar um serviço suplementar.
Interrogar SS	/api/interrogateSS	14	Interrogar o status de um serviço suplementar.
Registrar Senha	/api/registerPassword	17	Registrar uma senha de SS.
Obter Senha	/api/getPassword	18	Recuperar/verificar uma senha de SS.
Indicação de Verificação de SS	/api/forwardCheckSS-Indication	38	Verificação não confirmada em direção a um VLR.

Serviços de Localização (LCS) & GPRS

Operação	Endpoint	Opcode	Descrição
Enviar Informações de Roteamento para LCS	/api/sendRoutingInfoForLCS	85	GMLC consulta o HLR para roteamento LCS.
Fornecer Localização do Assinante	/api/provideSubscriberLocation	83	Solicitar a localização de um assinante do nó de atendimento.
Relatório de Localização do Assinante	/api/subscriberLocationReport	86	Relatar a localização de um assinante ao GMLC.
Enviar Informações de Roteamento para GPRS	/api/sendRoutingInfoForGprs	24	Consultar o HLR para roteamento GPRS (seleção de GGSN).
Atualizar Localização GPRS	/api/updateGprsLocation	23	Registrar o SGSN de atendimento de um assinante com o HLR.

Escopo LCS: as operações de Serviços de Localização são somente de saída (solicitante) — o Cliente MAP as aciona em direção a um HLR, nó de atendimento ou GMLC. O nó não atua como um servidor LCS (não responderá a um ProvideSubscriberLocation recebido ou processará um SubscriberLocationReport recebido). Os codificadores transportam os elementos de informação obrigatórios, além das opções principais mencionadas acima; o conjunto mais amplo de parâmetros LCS (QoS, prioridade, formas GAD, código, número de referência) ainda não está exposto.

CAP / CAMEL & Injeção Bruta

Operação	Endpoint	Descrição
CAP InitialDP	/api/cap/initialDP	Acionar um diálogo CAMEL em direção a um gsmSCF.
CAP Connect / Continue / ReleaseCall / ApplyCharging	/api/cap/connect, /api/cap/continue, /api/cap/releaseCall, /api/cap/applyCharging	Operações de controle de chamada CAMEL. Veja o Guia do Gateway CAMEL.
Raw SCCP	/api/raw/sccp	Injetar uma carga SCCP construída manualmente (teste/diagnósticos).
Raw M3UA	/api/raw/m3ua	Injetar uma carga M3UA construída manualmente (teste/diagnósticos).

---

Exemplos Comuns de Operações

Enviar Informações de Roteamento para SM (SRI-for-SM)

Consulta o HLR para o nó de atendimento usado para entregar um SMS. Para como o lado do HLR processa isso, veja SRI-for-SM no Guia do HLR.

Endpoint: POST /api/sri-for-sm

Solicitação:

{
  "msisdn": "447712345678",
  "serviceCenter": "447999123456"
}

Resposta:

{
  "result": {
    "imsi": "234509876543210",
    "locationInfoWithLMSI": {
      "networkNode-Number": "447999555111"
    }
  }
}

cURL:

curl -X POST http://localhost/api/sri-for-sm \
  -H "Content-Type: application/json" \
  -d '{"msisdn": "447712345678", "serviceCenter": "447999123456"}'

Enviar Informações de Roteamento (SRI)

Endpoint: POST /api/sri

Solicitação:

{
  "msisdn": "447712345678",
  "gmsc": "447999123456"
}

Fornecer Número de Roaming (PRN)

Endpoint: POST /api/prn

Solicitação:

{
  "msisdn": "447712345678",
  "gmsc": "447999123456",
  "msc_number": "447999555111",
  "imsi": "234509876543210"
}

Enviar Informações de Autenticação

Endpoint: POST /api/send-auth-info

Solicitação:

{
  "imsi": "234509876543210",
  "vectors": 5
}

Resposta:

{
  "result": {
    "authenticationSetList": [
      {
        "rand": "0123456789ABCDEF0123456789ABCDEF",
        "xres": "ABCDEF0123456789",
        "ck": "0123456789ABCDEF0123456789ABCDEF",
        "ik": "FEDCBA9876543210FEDCBA9876543210",
        "autn": "0123456789ABCDEF0123456789ABCDEF"
      }
    ]
  }
}

Atualizar Localização

Registra o VLR de atendimento de um assinante com o HLR, que responde com a sequência de Inserção de Dados do Assinante. Veja Atualizações de Localização no Guia do HLR.

Endpoint: POST /api/updateLocation

Solicitação:

{
  "imsi": "234509876543210",
  "vlr": "447999555111"
}

Interrogação a Qualquer Momento (ATI)

Endpoint: POST /api/anyTimeInterrogation

Solicitação:

{
  "hlr_gt": "447999123456",
  "msisdn": "447712345678"
}

Categorias de Operação

---

Enviando Solicitações via API

Usando Swagger UI

A Swagger UI fornece uma interface interativa para cada endpoint.

1. Navegue até http://your-server/swagger.
2. Selecione um endpoint (por exemplo, /api/sri-for-sm) e clique em Experimente.
3. Preencha o corpo da solicitação e clique em Executar.
4. A resposta SS7 decodificada é exibida abaixo.

O documento OpenAPI bruto está disponível em http://your-server/swagger.json.

Códigos de Resposta da API

Código	Significado
200	Sucesso — o resultado decodificado está no corpo da resposta.
400	Solicitação inválida — parâmetros inválidos ou ausentes.
504	Tempo limite do gateway — sem resposta SS7 dentro do tempo limite da solicitação (padrão 10 segundos).

Algumas operações são não confirmadas (fire-and-forget) e retornam imediatamente após o envio da mensagem.

---

Métricas do Cliente MAP

Todas as métricas são exportadas no endpoint Prometheus (/metrics).

Métrica: map_requests_total
Tipo: Contador
Descrição: Total de solicitações MAP enviadas.
Rótulos: operation — por exemplo, sri, sri_for_sm, prn, authentication_info, update_location.

Métrica: map_request_errors_total
Tipo: Contador
Descrição: Total de solicitações MAP que resultaram em erro ou tempo limite.
Rótulos: operation.

Métrica: map_request_duration_milliseconds
Tipo: Histograma
Descrição: Distribuição dos tempos de ida e volta das solicitações MAP.
Rótulos: operation.

Métrica: map_pending_requests
Tipo: Gauge
Descrição: Solicitações MAP atualmente aguardando uma resposta.

Exemplos de Consultas Prometheus

# Solicitações SRI-for-SM na última hora
increase(map_requests_total{operation="sri_for_sm"}[1h])

# Tempo médio de resposta SRI
rate(map_request_duration_milliseconds_sum{operation="sri"}[5m])
  / rate(map_request_duration_milliseconds_count{operation="sri"}[5m])

# Taxa de erro por operação
sum(rate(map_request_errors_total[5m])) by (operation)

# Solicitações pendentes atuais
map_pending_requests

---

Solução de Problemas do Cliente MAP

Solicitações Expiram (504)

Sintomas: A API retorna 504; sem resposta do HLR/MSC.

Possíveis causas:

• A associação M3UA ao STP/SGP não está ATIVA.
• O STP não tem rota para o Título Global de destino.
• Endereçamento SCCP incorreto (GT da Parte Chamadora/Chamado, SSN) ou Contexto de Roteamento.

Resolução:

1. Confirme o status da associação M3UA no painel ou através das visualizações de status do Guia STP.
2. Verifique a conectividade da rede (SCTP) com o STP.
3. Confirme que o Título Global de destino é roteável e que o subsistema de destino (por exemplo, HLR SSN 6) está em serviço.
4. Revise os logs em busca de mensagens de retorno SCCP (veja abaixo).

Mensagens de Retorno / Erro SCCP

Sintomas: Logs mostram mensagens de retorno do Serviço Unitdata SCCP (UDTS).

Causas comuns de retorno:

• Sem Tradução para o Endereço — o Título Global não está na tabela de roteamento do STP.
• Falha de Subsistema — o subsistema de destino (por exemplo, HLR SSN 6) está indisponível.
• Falha / Congestionamento de Rede — problema de rede transitório.

Resolução:

• Confirme a configuração de roteamento/tradução do STP para o GT de destino.
• Verifique se o subsistema de destino está operacional.
• Tente novamente após a limpeza do congestionamento.

---

Documentação Relacionada

• ← Voltar para a Documentação Principal
• Referência de Configuração — todos os parâmetros de configuração
• Guia de Recursos Comuns — Interface Web, API, monitoramento
• Guia STP — roteamento e Tradução de Título Global
• Guia HLR — processamento de operações do lado do HLR
• Guia do Centro de SMS — entrega de SMS
• Guia do Gateway CAMEL — operações CAP/CAMEL

---

OmniSS7 por Omnitouch Network Services