Validación de existencia de cliente en MECNA - customers-v1-mecna.md

Información del Servicio

Endpoint: /api/customers/v1/mecna
Método: POST
Versión: v1
Categoría: Gestión de clientes

Documentación del Servicio

Descripción general

El servicio customers-v1-mecna es un endpoint para validar la existencia de un cliente en la base de datos MECNA. Este servicio permite verificar si un cliente se encuentra en listas negras o tiene restricciones que impiden continuar con procesos de venta.

Categoría: Gestión de clientes.

Casos de uso principales:

Validación de identidad en procesos de venta LTE
Verificación de restricciones en listas negras MECNA
Control de elegibilidad para contratación de servicios
Validación previa a creación de órdenes de venta

Especificación técnica

Endpoint completo: /api/customers/v1/mecna
Método HTTP: POST
Capas involucradas:
- Controlador: CustomersController
- Lógica de negocio: CustomerBusiness.Mecna_v1
- Acceso a datos: MDMDataService2Client.MECNA_Query

Flujo de procesamiento:

Validación de parámetros de entrada (tipo y número de documento)
Obtención de origen y configuración de tipologías
Verificación de estado del API (encendido/apagado)
Consulta a servicio MDM para validación MECNA
Actualización de fase en órdenes de venta LTE (si aplica)
Generación de respuesta con códigos de estado

Dependencias principales:

MDM_Data_Services_V2.MDM_Data_Services_V2SoapClient
ConfigurationUtil para tipologías y configuración
CustomerUtil para validación MECNA
OrderUtil para actualización de fases

Consideraciones de seguridad:

Autenticación requerida mediante [Authorize]
Validación de origen de la petición
Auditoría completa de entrada y salida
Control de acceso por sistema y canal

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
Pre_Order	string	No	Número de la pre-orden de fija

Estructura de objetos anidados:

Estructura de WSRequestHeader

Campo	Tipo	Obligatorio	Descripción
System	object	Sí	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
CorrelationID	string	Sí	Identificador de la petición
ProcessingServer	string	Sí	Servidor de procesamiento del sistema

Estructura de WSRequestHeader.Property

Campo	Tipo	Obligatorio	Descripción
Name	string	Sí	Nombre de la propiedad
Value	string	Sí	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 sistema y servicio

Body

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

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 la petición
ProcessingServer	string	No	Servidor de procesamiento del sistema

Estructura de WSResponseHeader.Service

Campo	Tipo	Obligatorio	Descripción
Status	string	No	Estado de la ejecución del servicio web
ResponseDate	DateTime	No	Fecha de la respuesta
ProcessingServer	string	No	Servidor de procesamiento de la solicitud
StatusDetail	array	No	Detalle del procesamiento de la solicitud

Estructura de WSResponseHeader.Property

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

Estructura de WSResponseHeader.Service.StatusDetail

Campo	Tipo	Obligatorio	Descripción
ErrorCode	string	No	Código del error
ErrorDetailCode	string	No	Detalle del error
ErrorMessage	string	No	Mensaje del error
ErrorMessageUser	string	No	Mensaje del error para el usuario

Manejo de errores

Código	Descripción	Ejemplo
ERROR_04	La solicitud no fue exitosa. Fueron enviados objetos no acordes a la petición	Document_Type o Document_Number nulos
ERROR_08	No fue posible validar tu identidad, comunicate con un asesor	Cliente no encontrado en MECNA o error en consulta
OK_01	Validación exitosa	Cliente validado correctamente en MECNA

Análisis de Componentes

Modelos y componentes

Modelos base utilizados:

BaseRequestMecna: Contenedor principal de la petición
MecnaRequest: Body específico con parámetros de validación
BaseResponseMecna: Contenedor principal de la respuesta

Utilidades y servicios comunes:

CustomerUtil.Mecna: Validación principal contra servicio MDM
MDMDataService2Client.MECNA_Query: Cliente para consulta a MDM
ConfigurationUtil: Gestión de tipologías y configuración

Patrones de diseño implementados:

Singleton pattern en CustomerBusiness y CustomerUtil
Lazy loading para instancias de servicios
Factory pattern para creación de respuestas

Componentes reutilizados:

BotBaseRequestHeader/BotBaseResponseHeader: Headers estándar
Audit: Modelo de auditoría común
ResultModel: Modelo de resultados estándar

Referencias cruzadas:

SaleOrderController: Endpoint proxy para órdenes de venta
OrderUtil: Actualización de fases en órdenes LTE
AuditUtil: Auditoría de entrada y salida

Ejemplos de Request/Response

Solicitud (request)

json

{
  "WSRequestHeader": {
    "System": {
      "name": "MAX",
      "correlationID": "LUZ-0.7658422016757066",
      "processingServer": null
    },
    "Property": [
      {
        "name": null,
        "value": null
      }
    ]
  },
  "WSRequestBody": {
    "Document_Type": "CC",
    "Document_Number": "80955088",
    "Audit": {
      "Canal": "whatsapp",
      "IP_Address": "169.60.82.89",
      "IP_Latitud": "4.8094",
      "IP_Longitude": "-74.0980",
      "IP_City": "COTA",
      "IP_Country": "COLOMBIA",
      "Date": "2025-08-04",
      "Hour": "13:25:30",
      "WhatsApp_Phone_Number": "",
      "Facebook_User": "",
      "Twitter_User": ""
    }
  }
}

Respuesta exitosa

json

{
  "WSResponseHeader": {
    "System": {
      "name": "MAX",
      "correlationID": "LUZ-0.7658422016757066",
      "processingServer": null
    },
    "Service": {
      "status": "OK",
      "responseDate": "2025-08-04T13:25:31.6046111Z",
      "processingServer": null,
      "statusDetail": [
        {
          "errorCode": "OK_01",
          "errorDetailCode": "El cliente fue validado exitosamente",
          "errorMessage": "La solicitud LUZ-0.7658422016757066 fue exitosa",
          "errorMessageUser": null
        }
      ]
    },
    "Property": [
      {
        "name": null,
        "value": null
      }
    ]
  }
}

Respuesta de error

json

{
  "WSResponseHeader": {
    "System": {
      "Name": "MIETB",
      "CorrelationID": "123456789",
      "ProcessingServer": "BOTAPP-SERVER"
    },
    "Service": {
      "Status": "FAIL",
      "ResponseDate": "2024-12-19T10:30:00",
      "ProcessingServer": "BOTAPP-SERVER",
      "StatusDetail": [
        {
          "ErrorCode": "ERROR_08",
          "ErrorDetailCode": "Cliente no encontrado en MECNA",
          "ErrorMessage": "No fue posible validar la identidad del cliente",
          "ErrorMessageUser": "No fue posible validar tu identidad, comunicate con un asesor"
        }
      ]
    },
    "Property": [
      {
        "Name": "ERROR_TIENDA",
        "Value": "No fue posible validar tu identidad, comunicate con un asesor"
      }
    ]
  }
}

Diagramas Técnicos

3.1 Flujo de datos

mermaid

graph TD
  A[Recepción de la solicitud] --> B[CustomersController.Mecna_v1]
  B --> C[CustomerBusiness.Mecna_v1]
  C --> D[Validación de parámetros]
  D --> E[Obtención de origen]
  E --> F[Verificación API encendido]
  F --> G[CustomerUtil.Mecna]
  G --> H[MDMDataService2Client.MECNA_Query]
  H --> I[Servicio MDM_Data_Services_V2]
  I --> J[Respuesta MDM]
  J --> K[Actualización fase orden]
  K --> L[Generación respuesta]
  L --> M[Respuesta al cliente]

3.2 Arquitectura de clases

mermaid

classDiagram
  class CustomersController {
    +Mecna_v1(BaseRequestMecna)
  }
  class CustomerBusiness {
    +Mecna_v1(BaseRequest, string)
  }
  class CustomerUtil {
    +Mecna(ref RequestModel, string, string)
  }
  class MDMDataService2Client {
    +MECNA_Query(ref RequestModel, string, string)
  }
  class BaseRequestMecna {
    +WSRequestHeader
    +WSRequestBody
  }
  class BaseResponseMecna {
    +WSResponseHeader
  }
  CustomersController --> CustomerBusiness
  CustomerBusiness --> CustomerUtil
  CustomerUtil --> MDMDataService2Client
  CustomerBusiness --> BaseResponseMecna

3.3 Secuencia de ejecución

mermaid

sequenceDiagram
  participant Cliente
  participant CustomersController
  participant CustomerBusiness
  participant CustomerUtil
  participant MDMDataService2Client
  participant MDM_Data_Services_V2
  Cliente->>CustomersController: POST /api/customers/v1/mecna
  CustomersController->>CustomerBusiness: Mecna_v1(BaseRequest, request_name)
  CustomerBusiness->>CustomerBusiness: Validación parámetros
  CustomerBusiness->>CustomerBusiness: Obtención origen
  CustomerBusiness->>CustomerBusiness: Verificación API
  CustomerBusiness->>CustomerUtil: Mecna(ref Origin, Document_Type, Document_Number)
  CustomerUtil->>MDMDataService2Client: MECNA_Query(ref Origin, Document_Type, Document_Number)
  MDMDataService2Client->>MDM_Data_Services_V2: MECNA_Query(WSRequestHeader, Consulta_MECNA_Request)
  MDM_Data_Services_V2-->>MDMDataService2Client: Consulta_MECNA_Response
  MDMDataService2Client-->>CustomerUtil: bool (resultado)
  CustomerUtil-->>CustomerBusiness: bool (resultado)
  CustomerBusiness->>CustomerBusiness: Actualización fase orden
  CustomerBusiness-->>CustomersController: BaseResponseMecna
  CustomersController-->>Cliente: JSON Response

Evaluación TM Forum

Categorización TM Forum

Categoría TM Forum sugerida: Customer Management

TMF_ID correspondiente: TMF620

Justificación de la selección: El servicio MECNA se alinea con la categoría Customer Management de TM Forum (TMF620) ya que realiza validación de identidad y elegibilidad de clientes, que son funciones fundamentales de gestión de clientes. La validación contra listas negras es un proceso estándar en la industria de telecomunicaciones para verificar la elegibilidad de clientes antes de proceder con transacciones comerciales. Sin embargo, no existe una correspondencia exacta en TM Forum para validaciones específicas de listas negras, por lo que se categoriza bajo la gestión general de clientes.

Políticas y Consideraciones

Políticas de seguridad

Mecanismos de autenticación y autorización:

Autenticación requerida mediante atributo [Authorize]
Validación de token Bearer en headers
Control de acceso por sistema y canal de origen

Validaciones de seguridad implementadas:

Validación de parámetros obligatorios (Document_Type, Document_Number)
Verificación de origen de la petición
Auditoría completa de entrada y salida
Control de estado del API (encendido/apagado)

Límites de tasa (rate limits):

No se implementan rate limits específicos
Control indirecto mediante autenticación y autorización

SLAs aplicables:

Tiempo de respuesta esperado: < 5 segundos
Disponibilidad: 99.9%
Tolerancia a fallos: Reintentos automáticos en MDM

Recomendaciones y mejores prácticas

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

Implementar rate limiting para prevenir abuso del servicio
Agregar validación de formato de documentos de identidad
Implementar cache para consultas frecuentes a MECNA
Mejorar manejo de excepciones específicas de MDM

Optimizaciones posibles:

Implementar consultas asíncronas para mejor rendimiento
Agregar circuit breaker pattern para resiliencia
Implementar métricas de performance y monitoreo
Optimizar consultas a base de datos de configuración

Consideraciones de mantenimiento importantes:

Monitorear disponibilidad del servicio MDM
Revisar regularmente las tipologías de error en MongoDB
Mantener actualizada la documentación de códigos de error
Validar periódicamente la configuración de origen y sistemas

Sugerencias de seguridad aplicables:

Implementar logging de auditoría más detallado
Agregar validación de IP de origen
Implementar rate limiting por cliente/IP
Considerar encriptación de datos sensibles en logs

Validación de existencia de cliente en MECNA - customers-v1-mecna.md ​

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 ​

Estructura de WSResponseHeader.Service.StatusDetail ​

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 ​

Evaluación TM Forum ​

Categorización TM Forum ​

Políticas y Consideraciones ​

Políticas de seguridad ​

Recomendaciones y mejores prácticas ​

Validación de existencia de cliente en MECNA - customers-v1-mecna.md

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

Estructura de WSResponseHeader.Service.StatusDetail

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

Evaluación TM Forum

Categorización TM Forum

Políticas y Consideraciones

Políticas de seguridad

Recomendaciones y mejores prácticas