Servicio de Reconexión v2 - services-v2-reconexion

Información del Servicio

Endpoint: /api/services/v2/reconexion
Método: POST
Versión: 2.0
Categoría: Gestión de Servicios

Documentación del Servicio

Descripción general

El servicio services-v2-reconexion es un endpoint para solicitar la reconexión de un servicio móvil suspendido por robo, pérdida o voluntariamente. Este servicio permite reconectar servicios LTE y fija para casos de suspensión voluntaria, por pérdida o robo y suspensiones por pago.

Categoría de negocio: Gestión de Servicios Móviles.

Casos de uso principales:

Reconexión de servicios suspendidos por pago
Reconexión de servicios LTE suspendidos voluntariamente
Reconexión de servicios fijos suspendidos voluntariamente
Creación de PQR cuando no es posible crear orden de reconexión

Especificación técnica

Endpoint completo: /api/services/v2/reconexion
Método HTTP: POST
Capas involucradas:
- Controlador: ServicesController.Reconexion_v2
- Lógica de negocio: ServiceBusiness.Reconexion_v2
- Acceso a datos: ServiceUtil2, OrdersUtil, PQRUtil2

Flujo de procesamiento:

Auditoría de entrada y conversión de datos
Obtención del origen y configuración de tipologías
Validación de API encendida/apagada
Consulta del servicio por número telefónico
Validación de titularidad del servicio
Consulta del tipo de reconexión según motivo de suspensión
Creación de PQR o orden según el caso
Respuesta con CUN, número de orden o número de PQR

Dependencias principales:

ServiceUtil2.GetByPhone
OrdersUtil.ReconnectionByPayment
OrdersUtil.ReconnectionByVoluntaryLTE
OrdersUtil.ReconnectionByVoluntary
PQRUtil2.Create

Consideraciones de seguridad:

Validación de titularidad del servicio
Auditoría completa de la transacción
Validación de origen y sistema
Control de acceso por configuración

Parámetros de entrada (Request)

Headers

Campo	Tipo	Obligatorio	Descripción
WSRequestHeader	object	Sí	Cabecera de la petición con información del sistema

Body

Campo	Tipo	Obligatorio	Descripción
Audit	object	No	Auditoría de la aplicación
Document_Number	string	Sí	Número de identificación del cliente
Document_Type	string	Sí	Tipo de identificación del cliente
Phone	string	Sí	Número de conexión

Estructura de objetos anidados:

Estructura de WSRequestHeader

Campo	Tipo	Obligatorio	Descripción
System	object	No	Información asociada al sistema
Property	array	No	Propiedades asociadas al consumo del servicio web

Estructura de WSRequestHeader.System

Campo	Tipo	Obligatorio	Descripción
Name	string	Sí	Nombre del sistema que origina la petición
CorrelationID	string	Sí	Identificador de correlación de la petición
ProcessingServer	string	No	Servidor de procesamiento

Estructura de WSRequestHeader.Property

Campo	Tipo	Obligatorio	Descripción
Name	string	No	Nombre de la propiedad
Value	string	No	Valor de la propiedad

Estructura de Audit

Campo	Tipo	Obligatorio	Descripción
Canal	string	No	Canal sobre el cual se hizo la petición
Id_Device	string	No	Identificador del dispositivo móvil
SO	string	No	Sistema operativo del dispositivo
IP_Address	string	No	Dirección IP desde donde se realiza la petición
WhatsApp_Phone_Number	string	No	Número de WhatsApp desde donde se realiza la petición

Respuesta esperada (Response)

Headers

Campo	Tipo	Obligatorio	Descripción
WSResponseHeader	object	Sí	Cabecera de la respuesta con información del servicio

Body

Campo	Tipo	Obligatorio	Descripción
CUN	string	No	CUN asociado a la orden
Num_PQR	string	No	Número de la PQR. La PQR se crea si y solo si no es posible crear la orden de reconexión y siempre que exista el servicio activo
Order_Number	string	No	Número de la orden

Estructura de objetos anidados:

Estructura de WSResponseHeader

Campo	Tipo	Obligatorio	Descripción
System	object	No	Información asociada al sistema
Service	object	No	Información asociada a la ejecución del servicio
Property	array	No	Arreglo de propiedades asociado al servicio

Estructura de WSResponseHeader.System

Campo	Tipo	Obligatorio	Descripción
Name	string	No	Nombre del sistema
CorrelationID	string	No	Identificador de correlación
ProcessingServer	string	No	Servidor de procesamiento

Estructura de WSResponseHeader.Service

Campo	Tipo	Obligatorio	Descripción
Status	string	No	Estado del servicio (OK/ERROR)
Code	string	No	Código de respuesta
Message	string	No	Mensaje de respuesta
StatusDetail	array	No	Detalles del estado

Estructura de WSResponseHeader.Property

Campo	Tipo	Obligatorio	Descripción
Name	string	No	Nombre de la propiedad
Value	string	No	Valor de la propiedad

Manejo de errores

Código	Descripción	Ejemplo
ERROR_04	El request es nulo o faltan campos obligatorios	Document_Number, Document_Type o Phone vacíos
ERROR_06	Servicio no encontrado	El número telefónico no existe en el sistema
ERROR_07	Servicio no está suspendido	El servicio está activo, no requiere reconexión
ERROR_08	Error de titularidad	El documento no corresponde al titular del servicio
ERROR_09	Error en el tipo de reconexión	No se puede procesar la reconexión según el motivo

Análisis de Componentes

Modelos y componentes

Modelos base utilizados:

ReconexionRequest_v2: Modelo de entrada con campos de auditoría y datos del cliente
ReconexionResponse_v2: Modelo de salida con CUN, número de orden y PQR
BotBaseRequestHeader: Cabecera estándar de petición
BotBaseResponseHeader: Cabecera estándar de respuesta

Utilidades y servicios comunes:

ServiceUtil2: Consulta de servicios por número telefónico
OrdersUtil: Gestión de órdenes de reconexión
PQRUtil2: Creación y gestión de PQRs
ConfigurationUtil: Configuración de tipologías y validaciones

Patrones de diseño implementados:

Factory Pattern: Creación de respuestas estándar
Strategy Pattern: Diferentes tipos de reconexión según motivo
Chain of Responsibility: Validaciones secuenciales

Componentes reutilizados:

BaseRequest/BaseResponse: Estructuras base para todas las peticiones
Audit: Sistema de auditoría estándar
Tipologías: Configuración centralizada de errores y mensajes

Referencias cruzadas:

Servicios de consulta de servicios (Get_v2, Get_v3)
Servicios de órdenes (RegisterDevice_v1, RegisterDevice_v2)
Servicios de PQR (Create, Update)

Ejemplos de Request/Response

Solicitud (request)

json

{
  "WSRequestHeader": {
    "System": {
      "name": "MiETB",
      "correlationID": "MIETB-31072025-131528403",
      "processingServer": null
    },
    "Property": []
  },
  "WSRequestBody": {
    "Audit": {
      "Canal": "WEB",
      "Id_Device": null,
      "SO": "Windows",
      "IP_Address": null,
      "WhatsApp_Phone_Number": null
    },
    "Document_Number": "1026578508",
    "Document_Type": "CC",
    "Phone": "SR-50452171"
  }
}

Respuesta exitosa

json

{
  "WSResponseHeader": {
    "System": {
      "Name": "KIOSKOS",
      "CorrelationID": "KIOSKOS-20241219-123456",
      "ProcessingServer": "SRV-API-01"
    },
    "Service": {
      "status": "OK",
      "responseDate": "2025-07-31T09:26:10.3568059Z",
      "processingServer": null,
      "statusDetail": [
        {
          "errorCode": "OK_01",
          "errorDetailCode": "La solicitud MIETB-31072025-7205176 fue exitosa. El servicio fue reconectado exitosamente",
          "errorMessage": "El servicio fue reconectado exitosamente",
          "errorMessageUser": null
        }
      ]
    },
    "Property": []
  },
  "WSResponseBody": {
    "CUN": "CUN123456789",
    "Order_Number": "ORD987654321",
    "Num_PQR": null
  }
}

Respuesta de error

json

{
    "WSResponseHeader": {
        "System": {
            "Name": "KIOSKOS",
            "CorrelationID": "KIOSKOS-20241219-123456",
            "ProcessingServer": "SRV-API-01"
        },
        "Service": {
            "Status": "ERROR",
            "Code": "ERROR_06",
            "Message": "Servicio no encontrado",
            "StatusDetail": [
                {
                    "Code": "ERROR_06",
                    "Message": "El número telefónico no existe en el sistema",
                    "Detail": "No se encontró servicio asociado al número 3057000428"
                }
            ]
        },
        "Property": []
    },
    "WSResponseBody": null
}

Diagramas Técnicos

3.1 Flujo de datos

mermaid

graph TD
    A[Recepción de la solicitud] --> B[ServicesController.Reconexion_v2]
    B --> C[ServiceBusiness.Reconexion_v2]
    C --> D[Auditoría de entrada]
    D --> E[Conversión de datos]
    E --> F[Obtención del origen]
    F --> G[Validación API encendida]
    G --> H[Consulta del servicio]
    H --> I[Validación de titularidad]
    I --> J[Consulta tipo reconexión]
    J --> K{Creación de orden/PQR}
    K --> L[Respuesta exitosa]
    K --> M[Respuesta de error]

3.2 Arquitectura de clases

mermaid

classDiagram
    class ServicesController {
        +Reconexion_v2(BaseRequestReconexion_v2)
    }
    class ServiceBusiness {
        +Reconexion_v2(BaseRequest, string)
    }
    class ReconexionRequest_v2 {
        +Audit Audit
        +string Document_Number
        +string Document_Type
        +string Phone
    }
    class ReconexionResponse_v2 {
        +string CUN
        +string Num_PQR
        +string Order_Number
    }
    class ServiceUtil2 {
        +GetByPhone(Origin, string, string)
    }
    class OrdersUtil {
        +ReconnectionByPayment(Origin, Service, string)
        +ReconnectionByVoluntaryLTE(Origin, Service)
        +ReconnectionByVoluntary(Origin, Service, string, string, string)
    }
    ServicesController --> ServiceBusiness
    ServiceBusiness --> ReconexionRequest_v2
    ServiceBusiness --> ReconexionResponse_v2
    ServiceBusiness --> ServiceUtil2
    ServiceBusiness --> OrdersUtil

3.3 Secuencia de ejecución

mermaid

sequenceDiagram
    participant Cliente
    participant ServicesController
    participant ServiceBusiness
    participant ServiceUtil2
    participant OrdersUtil
    participant PQRUtil2
    
    Cliente->>ServicesController: POST /api/services/v2/reconexion
    ServicesController->>ServiceBusiness: Reconexion_v2(BaseRequest)
    ServiceBusiness->>ServiceBusiness: Auditoría de entrada
    ServiceBusiness->>ServiceBusiness: Conversión de datos
    ServiceBusiness->>ServiceBusiness: Validación de origen
    ServiceBusiness->>ServiceBusiness: Validación API encendida
    ServiceBusiness->>ServiceUtil2: GetByPhone(Origin, Phone)
    ServiceUtil2-->>ServiceBusiness: Service
    ServiceBusiness->>ServiceBusiness: Validación de titularidad
    ServiceBusiness->>ServiceBusiness: Consulta tipo reconexión
    ServiceBusiness->>OrdersUtil: ReconnectionByPayment/Voluntary
    OrdersUtil-->>ServiceBusiness: Resultado
    ServiceBusiness->>PQRUtil2: Create(Origin, Customer, Service, PQR)
    PQRUtil2-->>ServiceBusiness: PQR creada
    ServiceBusiness-->>ServicesController: BaseResponseReconexion_v2
    ServicesController-->>Cliente: Respuesta JSON

Políticas y Consideraciones

Políticas de seguridad

Mecanismos de autenticación y autorización:

Validación de origen del sistema
Verificación de titularidad del servicio
Auditoría completa de transacciones

Validaciones de seguridad implementadas:

Validación de campos obligatorios
Verificación de existencia del servicio
Control de acceso por configuración de API

Límites de tasa (rate limits):

Control por sistema origen
Validación de correlación ID único
Auditoría de frecuencia de uso

SLAs aplicables:

Tiempo de respuesta: < 5 segundos
Disponibilidad: 99.9%
Tolerancia a fallos: Circuit breaker implementado

Recomendaciones y mejores prácticas

Puntos de mejora específicos en el código:

Implementar cache para consultas de servicios frecuentes
Agregar métricas de rendimiento más detalladas
Mejorar el manejo de errores con códigos más específicos
Implementar retry automático para fallos transitorios

Optimizaciones posibles:

Paralelizar consultas de servicios y validaciones
Implementar batch processing para múltiples reconexiones
Optimizar consultas a base de datos con índices específicos
Reducir llamadas a servicios externos innecesarias

Consideraciones de mantenimiento importantes:

Mantener actualizada la configuración de tipologías
Revisar periódicamente los logs de auditoría
Monitorear el rendimiento de las consultas de servicios
Validar la integridad de datos en migraciones

Sugerencias de seguridad aplicables:

Implementar rate limiting más granular
Agregar validación de IP en auditoría
Implementar encriptación end-to-end para datos sensibles
Mejorar el logging de eventos de seguridad

Servicio de Reconexión v2 - services-v2-reconexion ​

Documentación del Servicio ​

Descripción general ​

Especificación técnica ​

Parámetros de entrada (Request) ​

Headers ​

Body ​

Estructura de WSRequestHeader ​

Estructura de WSRequestHeader.System ​

Estructura de WSRequestHeader.Property ​

Estructura de Audit ​

Respuesta esperada (Response) ​

Headers ​

Body ​

Estructura de WSResponseHeader ​

Estructura de WSResponseHeader.System ​

Estructura de WSResponseHeader.Service ​

Estructura de WSResponseHeader.Property ​

Manejo de errores ​

Análisis de Componentes ​

Modelos y componentes ​

Ejemplos de Request/Response ​

Solicitud (request) ​

Respuesta exitosa ​

Respuesta de error ​

Diagramas Técnicos ​

3.1 Flujo de datos ​

3.2 Arquitectura de clases ​

3.3 Secuencia de ejecución ​

Políticas y Consideraciones ​

Políticas de seguridad ​

Recomendaciones y mejores prácticas ​

Servicio de Reconexión v2 - services-v2-reconexion

Documentación del Servicio

Descripción general

Especificación técnica

Parámetros de entrada (Request)

Headers

Body

Estructura de WSRequestHeader

Estructura de WSRequestHeader.System

Estructura de WSRequestHeader.Property

Estructura de Audit

Respuesta esperada (Response)

Headers

Body

Estructura de WSResponseHeader

Estructura de WSResponseHeader.System

Estructura de WSResponseHeader.Service

Estructura de WSResponseHeader.Property

Manejo de errores

Análisis de Componentes

Modelos y componentes

Ejemplos de Request/Response

Solicitud (request)

Respuesta exitosa

Respuesta de error

Diagramas Técnicos

3.1 Flujo de datos

3.2 Arquitectura de clases

3.3 Secuencia de ejecución

Políticas y Consideraciones

Políticas de seguridad

Recomendaciones y mejores prácticas