Gestor de Portabilidad de Omnitouch
Gestión de portabilidad numérica para operadores — integración con el clearinghouse, enrutamiento ENUM y eventos del ciclo de vida OSS/BSS, con una interfaz web para equipos de operaciones.
Omnitouch ha implementado la portabilidad numérica en nuestras redes, con integraciones en vivo contra PortingXS y soporte para NPAC en mercados de América del Norte.
Descripción General
El Gestor de Portabilidad de Omnitouch maneja el ciclo completo de las operaciones de portabilidad numérica: enviando y rastreando solicitudes con el clearinghouse, manteniendo una base de datos de enrutamiento ENUM para números portados y entregando eventos del ciclo de vida al OSS/BSS del operador. Se integra con PortingXS a través de su red de 43 países y con NPAC para implementaciones en EE. UU.
La plataforma está diseñada para ser impulsada por un OSS/BSS a gran escala, con una interfaz web para el trabajo diario de operaciones — revisando el estado de los puertos, manejando casos especiales, consultando enrutamientos y validando la entrega de SMS en números portados.
Algunas cosas que vale la pena señalar antes de que continúes leyendo:
- El enrutamiento utiliza All-Call-Query contra una base de datos ENUM con parámetros
npdi/rnpor RFC 4694 y 3GPP TS 23.228 — no tablas de rango estáticas, que fallan silenciosamente en puertos posteriores - Los desajustes de tipo de cuenta (la razón de rechazo más común) se reintentan automáticamente sin intervención manual
- La plataforma posee el flujo de trabajo de portabilidad y el enrutamiento; la elegibilidad de la cuenta y el ciclo de vida del servicio permanecen en tu OSS/BSS, con ganchos de API para conectarlos
- Para los operadores que ejecutan OmniCRM, la integración OSS/BSS está preconstruida
El Gestor de Portabilidad de Omnitouch actúa como el punto de integración central entre los sistemas de gestión de clientes, los clearinghouses de portabilidad externos, la infraestructura de enrutamiento DNS/ENUM y las plataformas de facturación.
Arquitectura de Integración
El Gestor de Portabilidad de Omnitouch está construido con un límite claro: posee el flujo de trabajo de portabilidad y el enrutamiento, y tu OSS/BSS posee al cliente. Esto es intencional.
Los operadores ya tienen un BSS que sabe si una cuenta de cliente está en buen estado, qué servicios tienen y qué sucede cuando un servicio se termina. Construir esa lógica en una plataforma de portabilidad significaría duplicarla o luchar contra ella. En su lugar, el Gestor de Portabilidad de Omnitouch expone los ganchos correctos: las verificaciones de elegibilidad llaman a tu BSS para obtener una respuesta, y los eventos del ciclo de vida (puerto completo, puerto autorizado) notifican a tu BSS para que tome acción. La plataforma de portabilidad hace su trabajo; tu BSS hace su trabajo.
En la práctica, esto significa:
- El ciclo de vida de la solicitud de puerto y las interacciones con el clearinghouse se gestionan completamente aquí
- El enrutamiento se actualiza automáticamente al completarse
- La elegibilidad de la cuenta, la activación del servicio y el cierre de la cuenta permanecen en tu OSS/BSS — desencadenados por eventos de esta plataforma, no reemplazados por ella
Para los operadores que ejecutan OmniCRM, esta integración está preconstruida. Para los operadores con un BSS existente, la API proporciona los ganchos de eventos necesarios para conectarlo.
La interfaz web está disponible para que los equipos de portabilidad manejen las operaciones diarias — revisando solicitudes, actuando sobre puertos pendientes, consultando enrutamientos y diagnosticando problemas de entrega de SMS. A gran escala, se espera que las presentaciones de puertos y las respuestas del ciclo de vida se automaticen a través de la API.
Arquitectura del Sistema
Componentes Principales
- Gestor de Portabilidad — Orquesta flujos de trabajo de portabilidad y gestiona interacciones con el clearinghouse de portabilidad numérica
- Servidor DNS/ENUM — Gestiona el enrutamiento de llamadas y la resolución de números
- API e Interfaz Web — Proporciona acceso programático y de usuario a funciones de portabilidad
Puntos de Integración
- OmniCRM — Gestión de relaciones con clientes y provisión de servicios
- Plataforma de Facturación — Gestión de facturación y ingresos (CGrateS)
- PortingXS — Clearinghouse internacional de portabilidad numérica
- NPAC — Clearinghouse de portabilidad numérica de EE. UU.
- Infraestructura DNS/ENUM — Enrutamiento de llamadas y resolución de números
Gestor de Portabilidad
Flujo de Trabajo de Port-In
- Iniciación de Solicitud — Se crea una solicitud de port-in a través de la interfaz web o API
- Presentación al Clearinghouse — El Gestor de Portabilidad presenta la solicitud al clearinghouse apropiado (PortingXS para mercados internacionales, NPAC para EE. UU.)
- Monitoreo de Estado — El sistema rastrea cambios de estado a través del flujo de eventos del clearinghouse
- Provisionamiento ENUM — Al completarse el puerto con éxito, la base de datos de enrutamiento se actualiza automáticamente
- Activación del Servicio — El servicio de OmniCRM se activa y comienza la facturación
- Integración de Cargos — Se notifica a la plataforma de facturación para comenzar a cobrar
Detección Automática del Operador Donante
Cuando se presenta una solicitud de port-in sin un donornetworkoperator, el Gestor de Portabilidad de Omnitouch determina automáticamente el operador donante a partir del rango de números. Esta es la opción predeterminada recomendada para la mayoría de las presentaciones — el código del operador solo necesita especificarse explícitamente cuando se necesita anular el resultado de la detección automática.
Reenvío Automático del Tipo de Cuenta
Una razón común de rechazo por parte de los operadores donantes es Tipo de Cuenta Incorrecto (código de rechazo 35) — el indicador de Prepagado/Postpagado en la solicitud no coincide con los registros del donante. En lugar de requerir intervención manual, el Gestor de Portabilidad reintenta automáticamente la solicitud con el tipo de cuenta alternado (Prepagado → Postpagado o viceversa) cuando se recibe este rechazo.
El reenvío crea un nuevo registro de puerto. En la interfaz web, el ID de puerto original se muestra en verde en el nuevo registro para que la historia sea rastreable. A través de la API, GET /np_api/PortIn/{msgidentifier} se resuelve de manera transparente al registro activo si ha ocurrido un reenvío.
Flujo de Trabajo de Port-Out
- Recepción de Solicitud — Se recibe una solicitud de port-out del operador receptor a través del clearinghouse
- Validación del Servicio — El sistema valida que el servicio exista y sea elegible
- Notificación a CRM — OmniCRM se actualiza con el estado de port-out
- Deprovisionamiento ENUM — La base de datos de enrutamiento se actualiza para enrutar llamadas al operador receptor
- Terminación del Servicio — En el momento programado del puerto: servicio desactivado en OmniCRM, factura final generada, todos los servicios asociados cerrados
Integraciones con Clearinghouse
PortingXS
PortingXS (PXS) es un clearinghouse internacional de portabilidad numérica ampliamente adoptado que opera en 43 países en cuatro regiones:
| Región | Países |
|---|---|
| Américas y Caribe | Antigua y Barbuda, Bahamas, Barbados, Islas Caimán, Curazao, Dominica, Granada, Guyana, Jamaica, Panamá, Santa Lucía, San Cristóbal y Nieves, San Martín, San Vicente y las Granadinas, Trinidad y Tobago, Islas Turcas y Caicos |
| Europa | Bélgica, Bosnia y Herzegovina, Gibraltar, Guernsey, Irlanda, Isla de Man, Jersey, Kosovo, Montenegro, Eslovenia, Países Bajos, Ucrania |
| África | Argelia, Benín, Ghana, Kenia, Namibia, Nigeria, Ruanda, Senegal, Seychelles, Togo |
| Medio Oriente y Asia | Armenia, Bangladés, Brunéi, Irak, Sri Lanka |
El Gestor de Portabilidad se integra a través de una API REST/SOAP y gestiona el ciclo completo de portabilidad a través de una máquina de estados.
Capacidades principales:
- Gestión de Port-In/Out con flujo de trabajo completo de máquina de estados
- Actualizaciones de estado en tiempo real a través del historial de eventos
- Seguimiento de mensajes XML SOA/ENUM
- Base de datos de enrutamiento centralizada para ENUM (IMS) y MAP/INAP/CAP (All Call Query)
- Anulación manual de enrutamiento
Puntos finales de la API:
| Método | Punto final | Descripción |
|---|---|---|
| POST | /PortIn/create | Enviar nueva solicitud de port-in |
| GET | /PortIn/list | Listar todas las solicitudes de port-in |
| GET | /PortIn/{msgidentifier} | Obtener historial de eventos |
| POST | /PortIn/{msgidentifier} | Enviar instrucción para proceder |
| DELETE | /PortIn/{msgidentifier} | Abortar solicitud de puerto |
| GET | /PortOut/list | Listar solicitudes de port-out |
| POST | /PortOut/{msgidentifier} | Autorizar port-out |
| DELETE | /PortOut/{msgidentifier} | Rechazar port-out |
| GET | /route/{phone_number} | Consultar enrutamiento actual |
| POST | /route/{msisdn}/{operator}/{type} | Actualizar enrutamiento manualmente |
Los códigos de operador, el formato de número y los tipos de cuenta se configuran por implementación.
NPAC
Para operaciones en EE. UU., el Gestor de Portabilidad de Omnitouch se integra con el Centro de Administración de Portabilidad de Números (NPAC):
- Creación y gestión de Órdenes de Servicio (SO) de NPAC
- Interacciones con Proveedores de Servicios Locales (LSP)
- Gestión de Versiones de Suscripción (SV)
- Sincronización de estado en tiempo real
- Cumplimiento de regulaciones y plazos de portabilidad en EE. UU.
Servidor DNS / ENUM
El servidor DNS proporciona servicios DNS completos para redes de telecomunicaciones, apoyando servicios de paquetes estándar, escenarios de roaming, IMS y enrutamiento de llamadas de portabilidad numérica.
Zonas de Red 3GPP
Zona EPC (epc.mncXXX.mccYYY.3gppnetwork.org) — Utilizada para señalización Diameter local y escenarios de roaming. Permite a las redes visitadas descubrir recursos PGW locales. Contiene registros SRV y NAPTR para el descubrimiento de pares Diameter.
Zona IMS (ims.mncXXX.mccYYY.3gppnetwork.org) — Soporta operaciones del Subsistema Multimedia IP. Ruta la señalización SIP y localiza recursos CSCF para suscriptores IMS. Soporta VoLTE y RCS.
Zona Pública 3GPP (mncXXX.mccYYY.pub.3gppnetwork.org) — Proporciona acceso externo a servicios orientados al suscriptor: descubrimiento del servidor XCAP, ubicación de BSF para GBA y descubrimiento de ePDG para VoWiFi.
ENUM para Portabilidad Numérica
El servidor DNS implementa los servicios ENUM de RFC 3761 utilizando la zona e164enum.net.
All-Call-Query (ACQ): Cada llamada consulta la base de datos ENUM para determinar el enrutamiento actual.
Flujo de Consulta ENUM:
- El sistema de llamadas extrae el número marcado (por ejemplo, +1-555-0100)
- El número se convierte al formato ENUM (
0.0.1.0.5.5.5.1.e164.arpa) - Se emite una consulta DNS NAPTR al servidor ENUM
- El servidor devuelve información de enrutamiento: identificador del operador, número de enrutamiento (RN), proveedor de servicios, etiquetas de enrutamiento personalizadas
OmniCall — la plataforma IMS y MSC de Omnitouch — maneja el flujo ACQ ENUM de forma nativa. No se requiere trabajo de integración adicional; OmniCall consulta el servidor ENUM en cada llamada y enruta según la respuesta NAPTR. Para los operadores que ejecutan OmniCall junto con el Gestor de Portabilidad de Omnitouch, el enrutamiento de números portados es correcto desde el momento en que se completa un puerto, sin intervención manual o mantenimiento de tablas de enrutamiento separadas.
Enfoque de Enrutamiento para Números Portados
El enfoque definido en RFC 4694 y adoptado por 3GPP en TS 23.228 §4.18 para IMS es All-Call-Query contra una base de datos ENUM. Cada llamada consulta ENUM para el enrutamiento actual del número marcado específico, y la respuesta lleva directamente el número de enrutamiento del operador que sirve. Así es como se supone que debe funcionar la portabilidad numérica en una red IMS: decisiones de enrutamiento basadas en datos en tiempo real por número, no tablas de rango que requieren mantenimiento manual y se desactualizan a medida que los números se portan y vuelven a portarse.
El Gestor de Portabilidad de Omnitouch implementa esto completamente. Cuando se completa un puerto, los registros NAPTR se envían automáticamente al servidor ENUM para cada número en el rango. La respuesta lleva dos parámetros:
rn— el número de enrutamiento del operador que sirve actualmente. El switch de origen enruta a esto, no al operador original del número marcado.npdi— señala que la búsqueda NP se ha realizado. Los nodos descendentes no deben volver a consultar, lo que previene bucles.
Cuando se completa un puerto, el Gestor de Portabilidad de Omnitouch envía automáticamente un registro NAPTR al servidor ENUM para cada número en el rango 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 no portados, npdi se establece sin rn — confirmando que la búsqueda se realizó y el número no se ha movido. De cualquier manera, el núcleo IMS de origen (S-CSCF/BGCF) obtiene una respuesta definitiva del DNS y enruta sin ninguna otra consulta a la base de datos.
El enrutamiento permanece correcto a través de múltiples puertos sin intervención manual. El servidor ENUM es siempre la única fuente de verdad.
Integración de la Plataforma de Facturación
Port-In
Cuando un número se porta con éxito:
- El gateway envía una notificación de activación a la plataforma de facturación
- La plataforma de facturación crea una cuenta de suscriptor y perfiles de calificación
- Los cargos recurrentes y la calificación de uso comienzan inmediatamente
- La primera factura puede ser prorrateada según la fecha de finalización del puerto
Port-Out
Cuando un número se porta fuera:
- El gateway envía una notificación de desactivación a la plataforma de facturación
- La facturación en tiempo real se detiene en el momento programado del puerto
- Se genera la factura final: cargos recurrentes prorrateados, uso pendiente, tarifas de terminación anticipada (si corresponde), créditos/reembolsos
- La cuenta del suscriptor se cierra con el código de razón de portabilidad
Flujos de Trabajo Operativos
Operaciones Diarias
- Revisión de Estado Matutina — Verificar actividades de portabilidad nocturnas y actualizaciones del clearinghouse
- Procesamiento de Elementos de Acción — Manejar aprobaciones pendientes y confirmaciones de clientes
- Resolución de Errores — Investigar y resolver puertos fallidos o rechazados
- Comunicación con Clientes — Coordinar con los clientes sobre las fechas de puerto próximas
Monitoreo
El Gestor de Portabilidad de Omnitouch proporciona monitoreo automatizado para:
- Conectividad de la API del clearinghouse
- Fallos en el aprovisionamiento ENUM
- Errores de sincronización de CRM
- Fallos en la integración de la plataforma de facturación
- Tasas anormales de rechazo de portabilidad
Cumplimiento y Auditoría
- Todas las actividades de portabilidad se registran con trazas de auditoría completas
- Cumplimiento de los plazos de portabilidad regulatorios
- Registros de comunicación interoperadora retenidos
- Conciliación financiera con tarifas del clearinghouse
Problemas Comunes
Puerto atascado en estado pendiente — Verificar conectividad de la API del clearinghouse, verificar información del cliente, revisar el registro de eventos para la razón del rechazo.
Enrutamiento no actualizado después del puerto — Confirmar que el estado del puerto es Number_Ported. Usar Consulta de Enrutamiento para verificar el estado actual. Usar Push Routing para corregir manualmente si es necesario.
Fallos en la validación de SMS — Expandir la fila de resultados para recopilar el ID del mensaje y el ID de transacción. Proporcionar estos a la CPaaS cuando se escale.
Guía del Usuario
Comenzando
El acceso está controlado por una clave API. En la primera carga, se te pedirá que ingreses una Clave API. Ingresa tu clave API asignada y haz clic en Guardar Cambios. Las credenciales se almacenan en el localStorage del navegador y persisten entre sesiones. Para actualizar tu clave en cualquier momento, haz clic en Cambiar Clave API en la parte superior derecha de la barra de navegación.
Tu nivel de cuenta determina qué funciones están disponibles:
| Nivel | Acceso |
|---|---|
| Admin | Acceso completo a todas las funciones |
| Usuario PXS | Gestión de Port IN/OUT y enrutamiento |
| Solo Lectura | Consultas de enrutamiento y validación de SMS solamente |
Navegación
Solicitud de Portabilidad — Enviar una nueva solicitud de port-in
Port IN — Ver y gestionar todas las solicitudes de port-in
Port OUT — Revisar y responder a solicitudes de port-out de otros operadores
Consulta de Enrutamiento — Buscar el enrutamiento actual para cualquier número
Push Routing — Aprovisionar manualmente un registro de enrutamiento
Validar Enrutamiento de SMS — Enviar mensajes SMS de prueba a través de múltiples proveedores de CPaaS
Cambiar Clave API — Actualizar tus credenciales (botón, parte superior derecha)
Nueva Solicitud de Portabilidad
Haz clic en Solicitud de Portabilidad en la navegación para abrir el formulario de presentación.
| Campo | Descripción |
|---|---|
| Operador de Red Donante | Código del operador donante. Selecciona Automático para detección automática del rango de números. |
| Anular Período de Enfriamiento | Establecer en Verdadero solo cuando el cliente haya renunciado explícitamente al período de enfriamiento. Predeterminado: Falso. |
| Tipo de Cuenta | Prepagado o Postpagado |
| Tipo de Números | Móvil o Fijo |
| Primer Número | Inicio del rango de números (formato local, sin código de país) |
| Último Número | Fin del rango — igual que el Primer Número para un puerto único |
| Total de Números | Calculado automáticamente |
| Correo Electrónico (Contacto) | Correo electrónico de contacto para esta solicitud |
| Número de Autorización | Número de autorización del cliente — se completa automáticamente desde el Primer Número si se deja en blanco |
Haz clic en Enviar para crear la solicitud. Un mensaje de éxito mostrará el identificador de mensaje asignado.
Panel de Port IN
| Columna | Descripción |
|---|---|
| ID | ID interno de la base de datos |
| ID de Puerto | Identificador de mensaje del clearinghouse |
| Estado | Estado actual de la portabilidad |
| Solicitado | Marca de tiempo de presentación |
| Actualizado | Marca de tiempo de la última actualización |
| Operador | Código del operador de red donante |
| Objetivo | Número de contacto/autorización |
| Tipo | Móvil o Fijo |
| Tipo de Servicio | Botón de Historial de Eventos |
| Acciones | Botones de acción dependientes del estado |
Donde un puerto ha sido reenviado (por ejemplo, después de un desajuste de tipo de cuenta), el ID de puerto original se muestra en verde. Donde un puerto ha sido rechazado, la razón del rechazo se muestra en rojo.
Estados de Port-In:
| Estado | Significado |
|---|---|
Waiting_for_Authorisation_Response | Solicitud presentada, esperando respuesta del donante |
Waiting_for_Instruction | Donante autorizado — confirmar para proceder |
Waiting_for_Instruction_Response | Instrucción enviada, esperando reconocimiento |
Waiting_for_Ported_Response | Ejecución del puerto en progreso |
Number_Ported / Number_Ported_Complete | Puerto completo, enrutamiento actualizado |
Aborted | Cancelado |
Rejected | El donante rechazó la solicitud |
TimeOut | Solicitud agotada |
Acciones:
Waiting_for_Authorisation_Response— Botón Abortar (rojo) cancela la solicitudWaiting_for_Instruction— Botón Instrucción (verde) confirma que el puerto debe proceder
Historial de Eventos:
Haz clic en Historial de Eventos en cualquier fila para abrir el modal de registro de eventos.
- Eventos — lista acordeón de cada transición de estado con tipo de evento y detalle del registro
- Cuerpos XML — enlaces de descarga para todos los mensajes XML SOA/ENUM, divididos en salientes (
Output_XML) y entrantes (Input_XML) - Datos Detallados — volcado completo en JSON del registro de puerto
Panel de Port OUT
| Columna | Descripción |
|---|---|
| ID | ID interno de la base de datos |
| ID de Puerto | Identificador de mensaje del clearinghouse |
| Estado | Estado actual de la portabilidad |
| Solicitado | Marca de tiempo de presentación |
| Actualizado | Marca de tiempo de la última actualización |
| Operador | Código del operador receptor (ganador) |
| Objetivos | Rangos de números que se están portando |
| Tipo de Servicio | Botón de Registro de Eventos |
| Acciones | Botones de Autorizar o Rechazar |
Acciones (Waiting_for_Authorisation_Response):
- Autorizar (verde) — Aprueba el port-out y notifica al operador receptor
- Rechazar (rojo) — Niega la solicitud. Úsalo solo por razones legítimas: desajuste de cuenta, saldo pendiente, solicitud fraudulenta o número no activo.
Haz clic en Registro de Eventos en cualquier fila para ver el intercambio completo de mensajes.
Consulta de Enrutamiento
Ingresa el número local (el código de país se agrega automáticamente) y haz clic en Verificar Enrutamiento.
La respuesta es el resultado crudo del Proceso de Evento de CGrateS:
| Campo | Descripción |
|---|---|
Event.E164Address | El número consultado |
Event.NAPTRAddress | Cadena de enrutamiento NAPTR — dominio IMS o número de enrutamiento |
Event.NAPTROrder | Valor de orden NAPTR |
Event.NAPTRPreference | Valor de preferencia NAPTR |
MatchedProfiles | Perfil de atributo de CGrateS coincidente para este número |
Push Routing
| Campo | Descripción |
|---|---|
| Número de Teléfono (Sin código de país) | Número local — el código de país se agrega automáticamente |
| Operador | Código del operador al que se debe enrutar este número |
| Tipo | Móvil o Fijo |
Utiliza para correcciones de emergencia, aprovisionamiento inicial o cuando el enrutamiento automático posterior al puerto falla.
Validar Enrutamiento de SMS
El caso de uso principal para esta herramienta es validar que los mensajes SMS A2P (aplicación a persona) de proveedores externos de CPaaS se enruten correctamente a números portados. Cuando un número se porta, el nuevo operador debe estar correctamente aprovisionado en las tablas de enrutamiento de cada proveedor — esto no siempre sucede automáticamente, y sin una herramienta como esta no hay una forma fácil de detectar la brecha.
Al enviar un mensaje de prueba desde cada proveedor a un número portado, puedes confirmar qué proveedores han actualizado su enrutamiento y cuáles no. Los proveedores que devuelven un error o no logran entregar pueden ser escalados directamente utilizando la información de depuración en el resultado.
Valida que el proveedor aceptó la presentación del mensaje — no confirma la entrega al dispositivo. Utiliza un dispositivo de prueba o verifica el registro SMSc para confirmar la entrega.
- Ingresa el número de teléfono objetivo (típicamente un número recientemente portado bajo prueba)
- Selecciona uno o más proveedores A2P para probar
- Haz clic en Verificar Enrutamiento
El número objetivo recibirá un SMS de cada proveedor seleccionado con el cuerpo Prueba de {ProviderName}. Los resultados muestran verde (aceptado) o rojo (error). Haz clic en cualquier fila de resultado para expandir la información de depuración — requerida al escalar problemas de enrutamiento a proveedores de CPaaS.
Proveedores Disponibles:
| Proveedor | Notas |
|---|---|
| Nativo | Entrega nativa de la plataforma SMPP |
| CarrierA | Directo del operador |
| CarrierB | Directo del operador |
| Sinch | Proveedor de CPaaS |
| Twilio | Omnitouch tiene contacto de escalación directa |
| Vonage | Omnitouch tiene contacto de escalación directa |
| Telnyx | Cliente de Omnitouch — contacto directo del equipo |
| Pilvo | Omnitouch tiene contacto de escalación directa |
Swagger / Explorador de API
El Gestor de Portabilidad de Omnitouch expone una interfaz Swagger en vivo en /np_api/doc.
El esquema OpenAPI está disponible en /np_api/swagger.json para importación en Postman u otras herramientas de API.
Referencia de API
URL Base
/np_api/
Documentación interactiva disponible en /np_api/doc.
Autenticación
Consulta la Guía del Administrador para la configuración de autenticación y gestión de credenciales.
| Nivel | Capacidades |
|---|---|
admin | Acceso completo a todos los puntos finales |
pxs | Gestión de Port IN/OUT y enrutamiento |
read_only | Validación y puntos finales de información de números solamente |
Puntos finales de Port-In
Crear Solicitud de Port-In
POST /np_api/PortIn/create — Auth: admin, pxs
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
donornetworkoperator | string | No | Código del operador donante — dejar en blanco para detección automática |
email | string | Sí | Correo electrónico de contacto |
overridecooloff | boolean | No | Saltar el período de enfriamiento regulatorio (predeterminado: falso) |
contacttelephonenumber | string | Sí | Número de autorización del cliente |
Type_of_Numbers | string | Sí | "mobile" o "fixed" |
telephonenumberseriestart | string | Sí | Primer número en el rango |
telephonenumberserieend | string | Sí | Último número en el rango |
AccountType | string | Sí | "Prepaid" o "Postpaid" |
PortingState | integer | No | Anulación del estado inicial (predeterminado: 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"
}'
Respuesta:
{
"result": "success",
"msgidentifier": "XX202501-CARR-00001",
"message": "Solicitud de port-in creada con éxito"
}
Listar Solicitudes de Port-In
GET /np_api/PortIn/list — Auth: admin, pxs
Devuelve hasta 30 registros ordenados por los más recientes.
Obtener Solicitud de Port-In
GET /np_api/PortIn/{msgidentifier} — Auth: admin, pxs
Devuelve el registro completo incluyendo el historial de eventos y rangos de números. Si es reemplazado por un reenvío, devuelve de manera transparente el registro más nuevo.
Forma de respuesta:
{
"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": "Presentado al clearinghouse",
"submission_timestamp": "2025-01-15T10:30:00Z"
}
]
}
Valores de estado de portabilidad:
| 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ón de rechazo (failure_reason):
| Código | Razón |
|---|---|
| 0 | Desconocido |
| 31 | Cuenta Suspendida |
| 32 | Problema de Cuenta |
| 33 | Problema de Factura |
| 34 | Depósito Excedido |
| 35 | Tipo de Cuenta Incorrecto |
| 36 | Reportado Robado o Perdido |
| 37 | Especial |
| 38 | Sin Enfriamiento (Repatriación) |
| 39 | Problema de Factura Prepagada |
| 99 | Rechazo General |
Enviar Instrucción (Confirmar Puerto)
POST /np_api/PortIn/{msgidentifier} — Auth: admin, pxs
Confirma que el puerto debe proceder. Solo válido cuando PortingState es Waiting_for_Instruction (2).
Abortar Port-In
DELETE /np_api/PortIn/{msgidentifier} — Auth: admin, pxs
Cancela un port-in. Válido en estados: Waiting_for_Authorisation_Response, Waiting_for_Instruction, Waiting_for_Authorisation.
Listar Archivos XML
GET /np_api/PortIn/get_xml_list/{msgidentifier} — Auth: admin, pxs
Devuelve un array de nombres de archivos XML para un puerto.
Descargar Archivo XML
GET /np_api/PortIn/get_xml/{folder}/{filename} — Auth: admin, pxs
folder es output_XML (enviado) o input_XML (recibido).
Puntos finales de Port-Out
Listar Solicitudes de Port-Out
GET /np_api/PortOut/list — Auth: admin, pxs
Obtener Solicitud de Port-Out
GET /np_api/PortOut/{msgidentifier} — Auth: admin, pxs
Forma de respuesta:
{
"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
Aprueba el port-out y notifica al operador receptor.
Rechazar Port-Out
DELETE /np_api/PortOut/{msgidentifier} — Auth: admin, pxs
Rechaza el port-out. Úsalo solo por razones legítimas: desajuste de cuenta, saldo pendiente, solicitud fraudulenta o número no activo.
Puntos finales de Enrutamiento
Consultar Enrutamiento de Números
GET /np_api/route/{msisdn} — Auth: admin, pxs
Devuelve el registro de enrutamiento de CGrateS incluyendo dirección NAPTR, orden, preferencia y datos de suscripción HSS. msisdn es el número completo en E.164 sin el + inicial.
Actualizar Enrutamiento Push
POST /np_api/route/{msisdn}/{operator}/{type} — Auth: admin, pxs
Aprovisiona manualmente un registro de enrutamiento. operator es específico de la implementación. type es mobile o fixed.
Eliminar Registro de Enrutamiento
DELETE /np_api/route/{msisdn} — Auth: admin, pxs
Elimina un registro de enrutamiento.
Consultar Solo HSS
GET /np_api/route/hss_route/{msisdn} — Auth: admin, pxs
Devuelve solo datos de suscripción HSS, sin la búsqueda en la base de datos de enrutamiento.
Puntos finales de Validación
Validación de Enrutamiento de SMS
POST /np_api/validate/sms_validate — Auth: admin, pxs, read_only
Envía un SMS de prueba a través de un proveedor de CPaaS específico. El prefijo del código de país se agrega automáticamente.
| Campo | Tipo | Descripción |
|---|---|---|
phone_number | string | Número objetivo |
Operator | string | Native, CarrierA, CarrierB, Sinch, Twilio, Vonage, Telnyx, Pilvo, ClickSend |
apiKey | string | Clave API del proveedor (si es necesario) |
Respuesta:
{
"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": "..."
}
Información del Número
GET /np_api/info/{msisdn} — Auth: admin, pxs, read_only
Consulta al clearinghouse para obtener información sobre el número. Devuelve la respuesta cruda del clearinghouse como JSON.
Terminar Número
DELETE /np_api/terminate/{msisdn}/{type_of_numbers} — Auth: admin, pxs
Envía una solicitud de terminación al clearinghouse y elimina el registro de enrutamiento. type_of_numbers es mobile o fixed.
Receptor XML del Clearinghouse
POST /np_api/{deployment_prefix}/recv/ — Auth: pxs (credenciales del clearinghouse)
Punto final interno utilizado por el clearinghouse para entregar mensajes XML entrantes. No para uso directo. El prefijo de implementación se configura por instalación.
| Tipo de Mensaje | Acción |
|---|---|
authorisation_request | Crea un nuevo registro de port-out |
authorisation_response | Actualiza el estado de port-in; reintenta con el tipo de cuenta alternado en el código 35 |
instruction_response | Avanza el port-in a Waiting_for_Ported_Response |
ported | Marca el puerto como completo, actualiza la base de datos de enrutamiento, envía notificación de bienvenida |
timedout | Establece el estado en TimeOut |
terminated | Elimina el registro de enrutamiento |
Respuestas de Error
{
"result": "Excepción generada en ...",
"Reason": "detalles del error"
}
| Estado | Significado |
|---|---|
| 200 | Éxito |
| 401 | Autenticación fallida |
| 403 | Archivo no encontrado (descarga de XML) |
| 500 | Error interno — verifica el campo Reason |