Gerenciador de Portabilidade Omnitouch
Gerenciamento de portabilidade de números para operadoras — integração com a câmara de compensação, roteamento ENUM e eventos do ciclo de vida OSS/BSS, com uma interface web para equipes de operações.
A Omnitouch implementou a portabilidade de números em nossas redes, com integrações ao vivo contra PortingXS e suporte para NPAC nos mercados da América do Norte.
Visão Geral
O Gerenciador de Portabilidade Omnitouch lida com todo o ciclo de vida das operações de portabilidade de números: enviando e rastreando solicitações com a câmara de compensação, mantendo um banco de dados de roteamento ENUM para números portados e entregando eventos de ciclo de vida para o OSS/BSS do operador. Ele se integra com o PortingXS em sua rede de 43 países e com o NPAC para implantações nos EUA.
A plataforma é projetada para ser impulsionada por um OSS/BSS em grande escala, com uma interface web para o trabalho diário de operações — revisando o status da portabilidade, lidando com casos extremos, consultando roteamento e validando a entrega de SMS em números portados.
Algumas coisas que vale a pena notar antes de você ler mais:
- O roteamento usa All-Call-Query contra um banco de dados ENUM com parâmetros
npdi/rnpor RFC 4694 e 3GPP TS 23.228 — não tabelas de intervalo estáticas, que quebram silenciosamente em portas subsequentes - Desajustes de tipo de conta (a razão de rejeição mais comum) são reprocessados automaticamente sem intervenção manual
- A plataforma possui o fluxo de trabalho de portabilidade e roteamento; a elegibilidade da conta e o ciclo de vida do serviço permanecem em seu OSS/BSS, com ganchos de API para conectá-los
- Para operadores que utilizam o OmniCRM, a integração OSS/BSS já está pré-construída
O Gerenciador de Portabilidade Omnitouch atua como o ponto de integração central entre sistemas de gerenciamento de clientes, câmaras de compensação de portabilidade externas, infraestrutura de roteamento DNS/ENUM e plataformas de cobrança.
Arquitetura de Integração
O Gerenciador de Portabilidade Omnitouch é projetado em torno de um limite limpo: ele possui o fluxo de trabalho de portabilidade e roteamento, e seu OSS/BSS possui o cliente. Isso é intencional.
Os operadores já possuem um BSS que sabe se uma conta de cliente está em boa situação, quais serviços eles possuem e o que acontece quando um serviço é encerrado. Construir essa lógica em uma plataforma de portabilidade significaria duplicá-la ou combatê-la. Em vez disso, o Gerenciador de Portabilidade Omnitouch expõe os ganchos corretos — verificações de elegibilidade chamam seu BSS para uma resposta, e eventos de ciclo de vida (portabilidade concluída, portabilidade autorizada) notificam seu BSS para tomar uma ação. A plataforma de portabilidade faz seu trabalho; seu BSS faz seu trabalho.
Na prática, isso significa:
- O ciclo de vida da solicitação de portabilidade e as interações com a câmara de compensação são totalmente gerenciados aqui
- O roteamento é atualizado automaticamente na conclusão
- A elegibilidade da conta, a ativação do serviço e o fechamento da conta permanecem em seu OSS/BSS — acionados por eventos desta plataforma, não substituídos por ela
Para operadores que utilizam o OmniCRM, essa integração já está pré-construída. Para operadores com um BSS existente, a API fornece os ganchos de evento necessários para conectá-lo.
A interface web está disponível para as equipes de portabilidade lidarem com operações diárias — revisando solicitações, agindo sobre portas pendentes, consultando roteamento e diagnosticando problemas de entrega de SMS. Em grande escala, a expectativa é que as submissões de portabilidade e as respostas do ciclo de vida sejam automatizadas por meio da API.
Arquitetura do Sistema
Componentes Principais
- Gerenciador de Portabilidade — Orquestra fluxos de trabalho de portabilidade e gerencia interações com a câmara de compensação de portabilidade de números
- Servidor DNS/ENUM — Gerencia o roteamento de chamadas e a resolução de números
- API & Interface Web — Fornece acesso programático e do usuário às funções de portabilidade
Pontos de Integração
- OmniCRM — Gerenciamento de relacionamento com o cliente e provisionamento de serviços
- Plataforma de Cobrança — Gerenciamento de faturamento e receita (CGrateS)
- PortingXS — Câmara de compensação de portabilidade de números internacional
- NPAC — Câmara de compensação de portabilidade de números dos EUA
- Infraestrutura DNS/ENUM — Roteamento de chamadas e resolução de números
Gerenciador de Portabilidade
Fluxo de Trabalho de Port-In
- Iniciação da Solicitação — Solicitação de port-in é criada via a interface web ou API
- Submissão à Câmara de Compensação — O Gerenciador de Portabilidade envia a solicitação para a câmara de compensação apropriada (PortingXS para mercados internacionais, NPAC para os EUA)
- Monitoramento de Status — O sistema rastreia mudanças de estado via o fluxo de eventos da câmara de compensação
- Provisionamento ENUM — Após a conclusão bem-sucedida da portabilidade, o banco de dados de roteamento é atualizado automaticamente
- Ativação do Serviço — O serviço OmniCRM é ativado e a cobrança começa
- Integração de Cobrança — A plataforma de cobrança é notificada para começar a cobrança
Detecção Automática do Operador Doador
Quando uma solicitação de port-in é enviada sem um donornetworkoperator, o Gerenciador de Portabilidade Omnitouch determina automaticamente a operadora doadora a partir do intervalo de números. Este é o padrão recomendado para a maioria das submissões — o código do operador só precisa ser especificado explicitamente quando o resultado da detecção automática precisa ser substituído.
Reenvio Automático de Tipo de Conta
Uma razão comum de rejeição de operadoras doadoras é Tipo de Conta Incorreto (código de rejeição 35) — a flag Pré-pago/Pós-pago na solicitação não corresponde aos registros do doador. Em vez de exigir intervenção manual, o Gerenciador de Portabilidade reenvia automaticamente a solicitação com o tipo de conta alternado (Pré-pago → Pós-pago ou vice-versa) quando essa rejeição é recebida.
O reenvio cria um novo registro de portabilidade. Na interface web, o ID da portabilidade original é exibido em verde no novo registro, de modo que o histórico seja rastreável. Via API, GET /np_api/PortIn/{msgidentifier} resolve de forma transparente para o registro ativo se um reenvio ocorreu.
Fluxo de Trabalho de Port-Out
- Recepção da Solicitação — Solicitação de port-out é recebida da operadora ganhadora via a câmara de compensação
- Validação do Serviço — O sistema valida se o serviço existe e é elegível
- Notificação ao CRM — O OmniCRM é atualizado com o status do port-out
- Desprovisionamento ENUM — O banco de dados de roteamento é atualizado para direcionar chamadas para a operadora ganhadora
- Encerramento do Serviço — No horário programado da portabilidade: serviço desativado no OmniCRM, fatura final gerada, todos os serviços associados encerrados
Integrações com Câmaras de Compensação
PortingXS
PortingXS (PXS) é uma câmara de compensação de portabilidade de números internacional amplamente adotada, operando em 43 países em quatro regiões:
| Região | Países |
|---|---|
| Américas & Caribe | Antígua e Barbuda, Bahamas, Barbados, Ilhas Cayman, Curaçao, Dominica, Granada, Guiana, Jamaica, Panamá, Santa Lúcia, São Cristóvão e Nevis, Sint Maarten, São Vicente e Granadinas, Trinidad e Tobago, Ilhas Turcas e Caicos |
| Europa | Bélgica, Bósnia e Herzegovina, Gibraltar, Guernsey, Irlanda, Ilha de Man, Jersey, Kosovo, Montenegro, Eslovênia, Países Baixos, Ucrânia |
| África | Argélia, Benin, Gana, Quênia, Namíbia, Nigéria, Ruanda, Senegal, Seicheles, Togo |
| Oriente Médio & Ásia | Armênia, Bangladesh, Brunei, Iraque, Sri Lanka |
O Gerenciador de Portabilidade se integra via uma API REST/SOAP e gerencia todo o ciclo de vida da portabilidade através de uma máquina de estados.
Capacidades principais:
- Gerenciamento de Port-In/Out com fluxo de trabalho completo da máquina de estados
- Atualizações de status em tempo real via histórico de eventos
- Rastreamento de mensagens SOA/ENUM XML
- Banco de dados de roteamento centralizado para ENUM (IMS) e MAP/INAP/CAP (All Call Query)
- Sobrescrita manual de roteamento
Endpoints da API:
| Método | Endpoint | Descrição |
|---|---|---|
| POST | /PortIn/create | Enviar nova solicitação de port-in |
| GET | /PortIn/list | Listar todas as solicitações de port-in |
| GET | /PortIn/{msgidentifier} | Obter histórico de eventos |
| POST | /PortIn/{msgidentifier} | Enviar instrução para prosseguir |
| DELETE | /PortIn/{msgidentifier} | Abortar solicitação de portabilidade |
| GET | /PortOut/list | Listar solicitações de port-out |
| POST | /PortOut/{msgidentifier} | Autorizar port-out |
| DELETE | /PortOut/{msgidentifier} | Rejeitar port-out |
| GET | /route/{phone_number} | Consultar roteamento atual |
| POST | /route/{msisdn}/{operator}/{type} | Atualizar roteamento manualmente |
Os códigos de operador, formato de número e tipos de conta são configurados por implantação.
NPAC
Para operações nos EUA, o Gerenciador de Portabilidade Omnitouch se integra com o Centro de Administração de Portabilidade de Números (NPAC):
- Criação e gerenciamento de Ordem de Serviço (SO) do NPAC
- Interações com Provedor de Serviço Local (LSP)
- Gerenciamento de Versão de Assinatura (SV)
- Sincronização de status em tempo real
- Conformidade com regulamentos e prazos de portabilidade dos EUA
Servidor DNS / ENUM
O servidor DNS fornece serviços DNS abrangentes para redes de telecomunicações, suportando serviços de pacotes padrão, cenários de roaming, IMS e roteamento de chamadas de portabilidade de números.
Zonas de Rede 3GPP
Zona EPC (epc.mncXXX.mccYYY.3gppnetwork.org) — Usada para sinalização Diameter local e cenários de roaming. Permite que redes visitadas descubram recursos locais do PGW. Contém registros SRV e NAPTR para descoberta de pares Diameter.
Zona IMS (ims.mncXXX.mccYYY.3gppnetwork.org) — Suporta operações do Subsistema de Mídia IP. Roteia sinalização SIP e localiza recursos CSCF para assinantes IMS. Suporta VoLTE e RCS.
Zona Pública 3GPP (mncXXX.mccYYY.pub.3gppnetwork.org) — Fornece acesso externo a serviços voltados para assinantes: descoberta de servidor XCAP, localização de BSF para GBA e descoberta de ePDG para VoWiFi.
ENUM para Portabilidade de Números
O servidor DNS implementa serviços ENUM RFC 3761 usando a zona e164enum.net.
All-Call-Query (ACQ): Cada chamada consulta o banco de dados ENUM para determinar o roteamento atual.
Fluxo de Consulta ENUM:
- O sistema chamador extrai o número discado (por exemplo, +1-555-0100)
- O número é convertido para o formato ENUM (
0.0.1.0.5.5.5.1.e164.arpa) - Consulta NAPTR DNS emitida para o servidor ENUM
- O servidor retorna informações de roteamento: identificador da operadora, número de roteamento (RN), provedor de serviço, tags de roteamento personalizadas
OmniCall — a plataforma IMS e MSC da Omnitouch — lida com o fluxo ACQ ENUM automaticamente. Nenhum trabalho de integração adicional é necessário; o OmniCall consulta o servidor ENUM em cada chamada e roteia com base na resposta NAPTR. Para operadores que utilizam o OmniCall junto com o Gerenciador de Portabilidade Omnitouch, o roteamento de números portados está correto desde o momento em que uma portabilidade é concluída, sem intervenção manual ou manutenção separada de tabelas de roteamento necessária.
Abordagem de Roteamento para Números Portados
A abordagem definida na RFC 4694 e adotada pelo 3GPP em TS 23.228 §4.18 para IMS é All-Call-Query contra um banco de dados ENUM. Cada chamada consulta ENUM para o roteamento atual do número discado específico, e a resposta carrega diretamente o número de roteamento da operadora que está servindo. É assim que a portabilidade de números deve funcionar em uma rede IMS — decisões de roteamento baseadas em dados em tempo real por número específico, não tabelas de intervalo que requerem manutenção manual e se tornam obsoletas à medida que os números são portados e portados novamente.
O Gerenciador de Portabilidade Omnitouch implementa isso completamente. Quando uma portabilidade é concluída, registros NAPTR são enviados automaticamente para o servidor ENUM para cada número no intervalo. A resposta carrega dois parâmetros:
rn— o número de roteamento da operadora que está servindo atualmente. O switch de origem roteia para isso, não para a operadora original do número discado.npdi— sinaliza que a consulta NP foi concluída. Nós a montante não devem reconsultar, o que previne loops.
Quando uma portabilidade é concluída, o Gerenciador de Portabilidade Omnitouch automaticamente envia um registro NAPTR para o servidor ENUM para cada número no intervalo portado:
0.0.1.0.5.5.5.1.e164.arpa. NAPTR 10 10 "u" "E2U+pstn:tel"
"!(^.*$)!sip:\1;npdi;rn=<routing_number>@<carrier_ims_domain>!"
Para números não portados, npdi é definido sem rn — confirmando que a consulta foi executada e que o número não se moveu. De qualquer forma, o núcleo IMS de origem (S-CSCF/BGCF) recebe uma resposta definitiva do DNS e roteia sem qualquer nova consulta ao banco de dados.
O roteamento permanece correto através de múltiplas portabilidades sem qualquer intervenção manual. O servidor ENUM é sempre a única fonte de verdade.
Integração com a Plataforma de Cobrança
Port-In
Quando um número é portado com sucesso:
- O gateway envia uma notificação de ativação para a plataforma de cobrança
- A plataforma de cobrança cria uma conta de assinante e perfis de classificação
- As cobranças recorrentes e a classificação de uso começam imediatamente
- A primeira fatura pode ser proporcional com base na data de conclusão da portabilidade
Port-Out
Quando um número é portado para fora:
- O gateway envia uma notificação de desativação para a plataforma de cobrança
- A cobrança em tempo real para
- Fatura final gerada: cobranças recorrentes proporcionais, uso pendente, taxas de rescisão antecipada (se aplicável), créditos/reembolsos
- Conta do assinante encerrada com código de motivo de portabilidade
Fluxos de Trabalho Operacionais
Operações Diárias
- Revisão de Status Matinal — Verificar atividades de portabilidade durante a noite e atualizações da câmara de compensação
- Processamento de Itens de Ação — Lidar com aprovações pendentes e confirmações de clientes
- Resolução de Erros — Investigar e resolver portabilidades falhadas ou rejeitadas
- Comunicação com Clientes — Coordenar com clientes sobre datas de portabilidade futuras
Monitoramento
O Gerenciador de Portabilidade Omnitouch fornece monitoramento automatizado para:
- Conectividade da API da câmara de compensação
- Falhas de provisionamento ENUM
- Erros de sincronização do CRM
- Falhas de integração da plataforma de cobrança
- Taxas anormais de rejeição de portabilidade
Conformidade e Auditoria
- Todas as atividades de portabilidade registradas com trilhas de auditoria completas
- Conformidade com prazos regulatórios de portabilidade
- Registros de comunicação interoperadora retidos
- Reconciliação financeira com taxas da câmara de compensação
Problemas Comuns
Portabilidade presa em estado pendente — Verifique a conectividade da API da câmara de compensação, verifique as informações do cliente, revise o log de eventos para a razão da rejeição.
Roteamento não atualizado após a portabilidade — Confirme que o estado da portabilidade é Number_Ported. Use a Consulta de Roteamento para verificar o estado atual. Use o Push Routing para corrigir manualmente se necessário.
Falhas de validação de SMS — Expanda a linha de resultado para coletar o ID da mensagem e o ID da transação. Forneça esses dados ao provedor de CPaaS ao escalar.
Guia do Usuário
Começando
O acesso é controlado por uma chave de API. Na primeira carga, você será solicitado a inserir uma Chave de API. Insira sua chave de API atribuída e clique em Salvar Alterações. As credenciais são armazenadas no localStorage do navegador e persistem entre sessões. Para atualizar sua chave a qualquer momento, clique em Alterar Chave de API no canto superior direito da barra de navegação.
Seu nível de conta determina quais recursos estão disponíveis:
| Nível | Acesso |
|---|---|
| Admin | Acesso total a todos os recursos |
| Usuário PXS | Gerenciamento de Port IN/OUT e roteamento |
| Somente Leitura | Consultas de roteamento e validação de SMS apenas |
Navegação
Solicitação de Portabilidade — Enviar uma nova solicitação de port-in
Port IN — Visualizar e gerenciar todas as solicitações de port-in
Port OUT — Revisar e responder a solicitações de port-out de outras operadoras
Consulta de Roteamento — Consultar o roteamento atual para qualquer número
Push Routing — Provisionar manualmente um registro de roteamento
Validar Roteamento de SMS — Enviar mensagens SMS de teste através de vários provedores de CPaaS
Alterar Chave de API — Atualizar suas credenciais (botão, canto superior direito)
Nova Solicitação de Portabilidade
Clique em Solicitação de Portabilidade na navegação para abrir o formulário de submissão.
| Campo | Descrição |
|---|---|
| Operadora Doadora | Código da operadora doadora. Selecione Auto para detecção automática a partir do intervalo de números. |
| Ignorar Período de Espera | Defina como Verdadeiro somente quando o cliente tiver renunciado explicitamente ao período de espera. Padrão: Falso. |
| Tipo de Conta | Pré-pago ou Pós-pago |
| Tipo de Números | Móvel ou Fixo |
| Primeiro Número | Início do intervalo de números (formato local, sem código do país) |
| Último Número | Fim do intervalo — igual ao Primeiro Número para uma única portabilidade |
| Total de Números | Calculado automaticamente |
| Email (Contato) | Email de contato para esta solicitação |
| Número de Autorização | Número de autorização do cliente — preenchido automaticamente a partir do Primeiro Número se deixado em branco |
Clique em Enviar para criar a solicitação. Uma mensagem de sucesso exibirá o identificador da mensagem atribuído.
Painel de Port IN
| Coluna | Descrição |
|---|---|
| ID | ID interno do banco de dados |
| Port ID | Identificador da mensagem da câmara de compensação |
| Estado | Estado atual da portabilidade |
| Solicitado | Timestamp da submissão |
| Atualizado | Timestamp da última atualização |
| Operadora | Código da operadora doadora |
| Alvo | Número de contato/autorização |
| Tipo | Móvel ou Fixo |
| Tipo de Serviço | Botão de Histórico de Eventos |
| Ações | Botões de ação dependentes do estado |
Onde uma portabilidade foi reenviada (por exemplo, após um desajuste de tipo de conta), o ID da portabilidade original é exibido em verde. Onde uma portabilidade foi rejeitada, a razão da rejeição é exibida em vermelho.
Estados de Port-In:
| Estado | Significado |
|---|---|
Waiting_for_Authorisation_Response | Solicitação enviada, aguardando resposta do doador |
Waiting_for_Instruction | Doador autorizou — confirme para prosseguir |
Waiting_for_Instruction_Response | Instrução enviada, aguardando reconhecimento |
Waiting_for_Ported_Response | Execução da portabilidade em andamento |
Number_Ported / Number_Ported_Complete | Portabilidade concluída, roteamento atualizado |
Aborted | Cancelado |
Rejected | Doador rejeitou a solicitação |
TimeOut | Solicitação expirou |
Ações:
Waiting_for_Authorisation_Response— Botão Abortar (vermelho) cancela a solicitaçãoWaiting_for_Instruction— Botão Instrução (verde) confirma que a portabilidade deve prosseguir
Histórico de Eventos:
Clique em Histórico de Eventos em qualquer linha para abrir o modal de log de eventos.
- Eventos — lista em acordeão de cada transição de estado com tipo de evento e detalhe do log
- Corpos XML — links de download para todas as mensagens XML SOA/ENUM, divididas em outbound (
Output_XML) e inbound (Input_XML) - Dados Detalhados — despejo completo em JSON do registro de portabilidade
Painel de Port OUT
| Coluna | Descrição |
|---|---|
| ID | ID interno do banco de dados |
| Port ID | Identificador da mensagem da câmara de compensação |
| Estado | Estado atual da portabilidade |
| Solicitado | Timestamp da submissão |
| Atualizado | Timestamp da última atualização |
| Operadora | Código da operadora receptora (ganhadora) |
| Alvos | Intervalos de números sendo portados para fora |
| Tipo de Serviço | Botão de Log de Eventos |
| Ações | Botões de Autorizar ou Rejeitar |
Ações (Waiting_for_Authorisation_Response):
- Autorizar (verde) — Aprova o port-out e notifica a operadora ganhadora
- Rejeitar (vermelho) — Nega a solicitação. Use apenas por razões legítimas: desajuste de conta, saldo pendente, solicitação fraudulenta ou número não ativo.
Clique em Log de Eventos em qualquer linha para visualizar a troca de mensagens completa.
Consulta de Roteamento
Insira o número local (código do país adicionado automaticamente) e clique em Verificar Roteamento.
A resposta é o resultado bruto do CGrateS ProcessEvent:
| Campo | Descrição |
|---|---|
Event.E164Address | O número consultado |
Event.NAPTRAddress | String de roteamento NAPTR — domínio IMS ou número de roteamento |
Event.NAPTROrder | Valor da ordem NAPTR |
Event.NAPTRPreference | Valor de preferência NAPTR |
MatchedProfiles | Perfil de atributo CGrateS correspondente para este número |
Push Routing
| Campo | Descrição |
|---|---|
| Número de Telefone (Sem código do país) | Número local — código do país adicionado automaticamente |
| Operadora | Código da operadora para a qual este número deve ser roteado |
| Tipo | Móvel ou Fixo |
Use para correções de emergência, provisionamento inicial ou quando o roteamento automático pós-portabilidade falha.
Validar Roteamento de SMS
O caso de uso principal para esta ferramenta é validar que mensagens SMS A2P (aplicação para pessoa) de provedores externos de CPaaS roteiam corretamente para números portados. Quando um número é portado, a nova operadora deve ser provisionada corretamente nas tabelas de roteamento de cada provedor — isso nem sempre acontece automaticamente, e sem uma ferramenta como esta não há uma maneira fácil de detectar a lacuna.
Ao enviar uma mensagem de teste de cada provedor para um número portado, você pode confirmar quais provedores atualizaram seu roteamento e quais não atualizaram. Provedores que retornam um erro ou falham na entrega podem ser escalados diretamente usando as informações de depuração no resultado.
Valida que o provedor aceitou a submissão da mensagem — não confirma a entrega ao dispositivo. Use um dispositivo de teste ou verifique o log do SMSc para confirmar a entrega.
- Insira o número de telefone alvo (tipicamente um número recentemente portado em teste)
- Selecione um ou mais provedores A2P para testar
- Clique em Verificar Roteamento
O número alvo receberá um SMS de cada provedor selecionado com o corpo Teste de {ProviderName}. Os resultados mostram verde (aceito) ou vermelho (erro). Clique em qualquer linha de resultado para expandir as informações de depuração — necessárias ao escalar problemas de roteamento para provedores de CPaaS.
Provedores Disponíveis:
| Provedor | Notas |
|---|---|
| Nativo | Entrega SMPP da plataforma nativa |
| CarrierA | Direto da operadora |
| CarrierB | Direto da operadora |
| Sinch | Provedor de CPaaS |
| Twilio | A Omnitouch tem contato de escalonamento direto |
| Vonage | A Omnitouch tem contato de escalonamento direto |
| Telnyx | Cliente da Omnitouch — contato direto da equipe |
| Pilvo | A Omnitouch tem contato de escalonamento direto |
Swagger / API Explorer
O Gerenciador de Portabilidade Omnitouch expõe uma interface Swagger ao vivo em /np_api/doc.
O esquema OpenAPI está disponível em /np_api/swagger.json para importação no Postman ou outras ferramentas de API.
Referência da API
URL Base
/np_api/
Documentação interativa disponível em /np_api/doc.
Autenticação
Consulte o Guia do Administrador para configuração de autenticação e gerenciamento de credenciais.
| Nível | Capacidades |
|---|---|
admin | Acesso total a todos os endpoints |
pxs | Gerenciamento de Port IN/OUT e roteamento |
read_only | Validação e endpoints de informações de números apenas |
Endpoints de Port-In
Criar Solicitação de Port-In
POST /np_api/PortIn/create — Auth: admin, pxs
| Campo | Tipo | Requerido | Descrição |
|---|---|---|---|
donornetworkoperator | string | Não | Código da operadora doadora — deixe em branco para detecção automática |
email | string | Sim | Email de contato |
overridecooloff | boolean | Não | Ignorar o período de espera regulatório (padrão: falso) |
contacttelephonenumber | string | Sim | Número de autorização do cliente |
Type_of_Numbers | string | Sim | "mobile" ou "fixed" |
telephonenumberseriestart | string | Sim | Primeiro número no intervalo |
telephonenumberserieend | string | Sim | Último número no intervalo |
AccountType | string | Sim | "Prepaid" ou "Postpaid" |
PortingState | integer | Não | Sobrescrição do estado inicial (padrão: 0) |
curl -X POST https://your-host/np_api/PortIn/create \
-u "your_username:your_api_key" \
-H "Content-Type: application/json" \
-d '{
"donornetworkoperator": "DONOR",
"email": "ops@example.com",
"overridecooloff": false,
"contacttelephonenumber": "5550100",
"Type_of_Numbers": "mobile",
"telephonenumberseriestart": "5550100",
"telephonenumberserieend": "5550199",
"AccountType": "Prepaid"
}'
Resposta:
{
"result": "success",
"msgidentifier": "XX202501-CARR-00001",
"message": "Solicitação de port-in criada com sucesso"
}
Listar Solicitações de Port-In
GET /np_api/PortIn/list — Auth: admin, pxs
Retorna até 30 registros ordenados pelo mais recente.
Obter Solicitação de Port-In
GET /np_api/PortIn/{msgidentifier} — Auth: admin, pxs
Retorna o registro completo, incluindo histórico de eventos e intervalos de números. Se substituído por um reenvio, retorna de forma transparente o registro mais recente.
Formato da resposta:
{
"port_in_id": 42,
"msgidentifier": "XX202501-CARR-00001",
"PortingState": 2,
"PortingStateString": "Waiting_for_Instruction",
"donornetworkoperator": "DONOR",
"email": "ops@example.com",
"contacttelephonenumber": "5550100",
"Type_of_Numbers": "mobile",
"AccountType": "Prepaid",
"overridecooloff": false,
"submission_timestamp": "2025-01-15T10:30:00",
"update_timestamp": "2025-01-15T14:22:00",
"failure_reason": null,
"original_porting_request": null,
"phone_number_ranges": [
{ "telephonenumberseriestart": "5550100", "telephonenumberserieend": "5550199" }
],
"events": [
{
"porting_in_event_id": 1,
"msgtype": "PortingRequest",
"direction": 0,
"eventlog": "Submetido à câmara de compensação",
"submission_timestamp": "2025-01-15T10:30:00Z"
}
]
}
Valores do estado de portabilidade:
| Valor | Estado |
|---|---|
| 0 | NoPort |
| 1 | Waiting_for_Authorisation_Response |
| 2 | Waiting_for_Instruction |
| 3 | Waiting_for_Instruction_Response |
| 10 | Waiting_for_Ported_Response |
| 11 | Waiting_for_Change_Response |
| 20 | Number_Ported |
| 30 | Number_Ported_Complete |
| 97 | TimeOut |
| 98 | Aborted |
| 99 | Rejected |
Códigos de razão de rejeição (failure_reason):
| Código | Razão |
|---|---|
| 0 | Desconhecido |
| 31 | Conta Suspensa |
| 32 | Problema de Conta |
| 33 | Problema de Fatura |
| 34 | Depósito Excedido |
| 35 | Tipo de Conta Incorreto |
| 36 | Reportado como Roubado ou Perdido |
| 37 | Especial |
| 38 | Sem Período de Espera (Repatriação) |
| 39 | Problema de Fatura Pré-paga |
| 99 | Rejeição Geral |
Enviar Instrução (Confirmar Port)
POST /np_api/PortIn/{msgidentifier} — Auth: admin, pxs
Confirma que a portabilidade deve prosseguir. Válido apenas quando PortingState é Waiting_for_Instruction (2).
Abortar Port-In
DELETE /np_api/PortIn/{msgidentifier} — Auth: admin, pxs
Cancela um port-in. Válido nos estados: Waiting_for_Authorisation_Response, Waiting_for_Instruction, Waiting_for_Authorisation.
Listar Arquivos XML
GET /np_api/PortIn/get_xml_list/{msgidentifier} — Auth: admin, pxs
Retorna um array de nomes de arquivos XML para uma portabilidade.
Baixar Arquivo XML
GET /np_api/PortIn/get_xml/{folder}/{filename} — Auth: admin, pxs
folder é output_XML (enviado) ou input_XML (recebido).
Endpoints de Port-Out
Listar Solicitações de Port-Out
GET /np_api/PortOut/list — Auth: admin, pxs
Obter Solicitação de Port-Out
GET /np_api/PortOut/{msgidentifier} — Auth: admin, pxs
Formato da resposta:
{
"port_out_id": 99,
"msgidentifier": "XX202501-DONOR-00001",
"PortingState": 1,
"PortingStateString": "Waiting_for_Authorisation_Response",
"recipientnetworkoperator": "DONOR",
"Type_of_Numbers": "mobile",
"submission_timestamp": "2025-01-16T09:15:00",
"update_timestamp": "2025-01-16T09:15:00",
"phone_number_ranges": [
{ "telephonenumberseriestart": "5550200", "telephonenumberserieend": "5550249" }
],
"events": []
}
Autorizar Port-Out
POST /np_api/PortOut/{msgidentifier} — Auth: admin, pxs
Aprova o port-out e notifica a operadora ganhadora.
Rejeitar Port-Out
DELETE /np_api/PortOut/{msgidentifier} — Auth: admin, pxs
Rejeita o port-out. Use apenas por razões legítimas: desajuste de conta, saldo pendente, solicitação fraudulenta ou número não ativo.
Endpoints de Roteamento
Consultar Roteamento de Números
GET /np_api/route/{msisdn} — Auth: admin, pxs
Retorna o registro de roteamento CGrateS, incluindo endereço NAPTR, ordem, preferência e dados de assinatura HSS. msisdn é o número completo em E.164 sem o + inicial.
Atualizar Roteamento Manualmente
POST /np_api/route/{msisdn}/{operator}/{type} — Auth: admin, pxs
Provisiona manualmente um registro de roteamento. operator é específico da implantação. type é mobile ou fixed.
Deletar Registro de Roteamento
DELETE /np_api/route/{msisdn} — Auth: admin, pxs
Remove um registro de roteamento.
Consultar Apenas HSS
GET /np_api/route/hss_route/{msisdn} — Auth: admin, pxs
Retorna apenas dados de assinatura HSS, sem a consulta ao banco de dados de roteamento.
Endpoints de Validação
Validação de Roteamento de SMS
POST /np_api/validate/sms_validate — Auth: admin, pxs, read_only
Envia um SMS de teste via um provedor de CPaaS especificado. Prefixo do código do país adicionado automaticamente.
| Campo | Tipo | Descrição |
|---|---|---|
phone_number | string | Número alvo |
Operator | string | Native, CarrierA, CarrierB, Sinch, Twilio, Vonage, Telnyx, Pilvo, ClickSend |
apiKey | string | Chave de API do provedor (se necessário) |
Resposta:
{
"result": "Sent",
"x-message-id": "SM1234567890abcdef",
"x-transaction-id": "8a2c925809bb403f01",
"x-message-timestamp": "2025-01-15T10:30:00.000Z",
"x-provider": "Twilio",
"x-provider-response": "..."
}
Informações do Número
GET /np_api/info/{msisdn} — Auth: admin, pxs, read_only
Consulta a câmara de compensação para informações sobre o número. Retorna a resposta bruta da câmara de compensação como JSON.
Encerrar Número
DELETE /np_api/terminate/{msisdn}/{type_of_numbers} — Auth: admin, pxs
Submete uma solicitação de encerramento à câmara de compensação e remove o registro de roteamento. type_of_numbers é mobile ou fixed.
Receptor XML da Câmara de Compensação
POST /np_api/{deployment_prefix}/recv/ — Auth: pxs (credenciais da câmara de compensação)
Endpoint interno usado pela câmara de compensação para entregar mensagens XML de entrada. Não para uso direto. O prefixo de implantação é configurado por instalação.
| Tipo de Mensagem | Ação |
|---|---|
authorisation_request | Cria um novo registro de port-out |
authorisation_response | Atualiza o estado do port-in; tenta novamente com tipo de conta alternado no código 35 |
instruction_response | Avança o port-in para Waiting_for_Ported_Response |
ported | Marca a portabilidade como concluída, atualiza o banco de dados de roteamento, envia notificação de boas-vindas |
timedout | Define o estado como TimeOut |
terminated | Remove o registro de roteamento |
Respostas de Erro
{
"result": "Exceção levantada em ...",
"Reason": "detalhes do erro"
}
| Status | Significado |
|---|---|
| 200 | Sucesso |
| 401 | Autenticação falhou |
| 403 | Arquivo não encontrado (download XML) |
| 500 | Erro interno — verifique o campo Reason |