Valida la identidad de clientes ETB - customers-v1-identityvalidation

Información del Servicio

Endpoint: /api/customers/v1/identityvalidation
Método: POST
Versión: v1
Categoría: Gestión de Clientes / Seguridad

Documentación del Servicio

Descripción general

El servicio customers-v1-identityvalidation permite validar la identidad de un cliente ETB a partir de sus datos personales y contexto de negocio (proceso, producto, canal, etc.). Este servicio es fundamental para procesos de venta, activación de servicios y prevención de fraude, ya que verifica que los datos proporcionados coincidan con la información registrada en los sistemas de ETB.

Categoría de negocio: Gestión de Clientes / Seguridad

Casos de uso principales:

Validación de identidad en ventas presenciales y digitales
Prevención de fraude y suplantación de identidad
Automatización de flujos comerciales que requieren verificación de identidad
Validación previa a la activación de servicios móviles y fijos

Especificación técnica

Endpoint completo: /api/customers/v1/identityvalidation
Método HTTP: POST
Capas involucradas:
- Controlador: CustomersController (método IdentityValidation_v1)
- Lógica de negocio: CustomerBusiness.IdentityValidation_v1
- Acceso a datos: CustomerUtil, ConfigurationUtil, AuditUtil, OrderUtil, LSIMModel

Flujo de procesamiento:

El controlador recibe el request y construye un objeto BaseRequest
Se valida y completa la información base del request
Se delega la lógica a CustomerBusiness.IdentityValidation_v1
Se audita la entrada y se convierte el request a modelo de negocio
Se valida la presencia y formato de los campos obligatorios
Se obtiene el origen y tipologías de configuración
Se verifica si el endpoint está habilitado para el canal
Se consulta el cliente y se validan los datos contra la base
Se ejecuta la validación de identidad vía LSIM (sistema externo)
Se actualiza la fase de la orden si aplica
Se construye la respuesta con el estado y detalles
Se audita la salida y se registra la validación

Dependencias principales:

Modelos: BaseRequestIdentityValidation, IdentityValidationRequest, BaseResponseIdentityValidation, BotBaseRequestHeader, BotBaseResponseHeader, Audit
Utilidades: CustomerUtil, ConfigurationUtil, AuditUtil, OrderUtil, LSIMModel
Servicios externos: LSIM (sistema de validación de identidad)

Consideraciones de seguridad:

Requiere autenticación JWT y validación de canal/sistema
Valida origen, canal y correlación de la petición
Audita todas las operaciones de entrada y salida
Integra con sistema LSIM para validación biométrica

Parámetros de entrada (Request)

Headers

Campo	Tipo	Obligatorio	Descripción
System.name	string	Sí	Nombre del sistema que realiza la petición
System.correlationID	string	Sí	Identificador único de la transacción
System.processingServer	string	Sí	Servidor de procesamiento
Property	array	No*	Propiedades adicionales del request (condicional según integración)

Body

Campo	Tipo	Obligatorio	Descripción
Audit	object	Sí	Información de auditoría de la petición
Document_Number	string	Sí	Número de identificación del cliente
Document_Type	string	Sí	Tipo de identificación (CC, CE, NIT, etc.)
Expedition_Date	string	Sí	Fecha de expedición del documento (dd/MM/yyyy)
Pre_Order	string	No	Número de pre-orden asociado
Process	string	Sí	Proceso asociado (ej: VTA, ACTIVA_SIM)
Product	string	No	Producto asociado (ej: FIJA, MOVIL)
Stratum	string	No	Estrato asociado a la solicitud
Sub_Process	string	No	Subproceso asociado (ej: PREPAGO, POSPAGO)
Surname	string	Sí	Primer apellido del cliente

Estructura de objetos anidados:

Objeto anidado: Audit

Campo	Tipo	Obligatorio	Descripción
Canal	string	Sí	Canal sobre el cual se hace la petición
Id_Device	string	No	Identificador del dispositivo
SO	string	No	Sistema operativo del dispositivo
IP_Address	string	No	Dirección IP de origen
IP_Latitude	string	No	Latitud de la ubicación
IP_Longitude	string	No	Longitud de la ubicación
WhatsApp_Phone_Number	string	No	Número de WhatsApp
Facebook_User	string	No	Usuario de Facebook
Twitter_User	string	No	Usuario de Twitter

Respuesta esperada (Response)

Headers

Campo	Tipo	Obligatorio	Descripción
Content-Type	string	Sí	application/json
Cache-Control	string	No	Control de caché

Body

Campo	Tipo	Obligatorio	Descripción
WSResponseHeader	object	Sí	Cabecera de la respuesta

Estructura de objetos anidados:

Objeto anidado: WSResponseHeader

Campo	Tipo	Obligatorio	Descripción
System	object	Sí	Información del sistema
Service	object	Sí	Información del servicio
Property	array	No	Propiedades adicionales

Objeto anidado: System

Campo	Tipo	Obligatorio	Descripción
name	string	Sí	Nombre del sistema
correlationID	string	Sí	Identificador de correlación
processingServer	string	No	Servidor de procesamiento

Objeto anidado: Service

Campo	Tipo	Obligatorio	Descripción
status	string	Sí	Estado de la ejecución (OK, Error, etc.)
responseDate	datetime	Sí	Fecha de la respuesta
processingServer	string	No	Servidor de procesamiento
statusDetail	array	Sí	Detalles de estado y errores

Objeto anidado: statusDetail

Campo	Tipo	Obligatorio	Descripción
errorCode	string	Sí	Código del error o estado
errorDetailCode	string	No	Detalle funcional del error
errorMessage	string	No	Mensaje técnico del error
errorMessageUser	string	No	Mensaje funcional para el usuario

Manejo de errores

Código	Descripción	Ejemplo
OK_01	El cliente fue validado exitosamente	"La solicitud {0} fue exitosa"
OK_02	Validación deshabilitada, se permite continuar	"La solicitud {0} fue exitosa"
ERROR_04	Faltan campos obligatorios o formato incorrecto	"Uno de los campos obligatorios no fue enviado o la fecha tiene un formato incorrecto"
ERROR_06	Canal no habilitado o error de configuración	"El canal enviado no está habilitado para la consulta"
ERROR_08	Validación de cliente no exitosa	"Datos incorrectos, por favor verificar"

Análisis de Componentes

Modelos y componentes

Modelos base utilizados:

BaseRequestIdentityValidation (request completo)
IdentityValidationRequest (body de la petición)
BaseResponseIdentityValidation (respuesta principal)
BotBaseRequestHeader y BotBaseResponseHeader (cabeceras)
Audit (auditoría de la petición)

Utilidades y servicios comunes:

CustomerUtil (gestión y consulta de clientes)
ConfigurationUtil (gestión de tipologías y configuración)
AuditUtil (auditoría de requests y respuestas)
OrderUtil (actualización de fases de orden)
LSIMModel (validación de identidad)

Patrones de diseño implementados:

Singleton para utilidades (GetInstance)
Separación de capas (Controller, Business, Util, Model)
Manejo centralizado de auditoría y errores

Componentes reutilizados:

Modelos de cabecera y auditoría se usan en otros endpoints de clientes
Utilidades de configuración y auditoría son transversales

Referencias cruzadas:

Relacionado con /api/customers/v1/mecna (listas negras)
Utiliza lógica y modelos comunes de validación de clientes

Ejemplos de Request/Response

Solicitud (request)

json

{
  "WSRequestHeader": {
    "System": {
      "name": "MAX",
      "correlationID": "LUZ-0.6875654170768943",
      "processingServer": null
    },
    "Property": []
  },
  "WSRequestBody": {
    "Document_Type": "CC",
    "Document_Number": "12808270",
    "Expedition_Date": "11/05/2002",
    "Surname": "SANTIAGO DIAZ",
    "Process": "MAX_DEFAULT",
    "Product": "",
    "Audit": {
      "Canal": "WEB",
      "Date": "2025-07-24",
      "Hour": "23:12:41"
    }
  }
}

Respuesta exitosa

json

{
  "WSResponseHeader": {
    "System": {
      "name": "MAX",
      "correlationID": "LUZ-0.6875654170768943",
      "processingServer": null
    },
    "Service": {
      "status": "OK",
      "responseDate": "2025-07-24T23:12:42.5236065Z",
      "processingServer": null,
      "statusDetail": [
        {
          "errorCode": "OK_01",
          "errorDetailCode": "El cliente fue validado exitosamente",
          "errorMessage": "La solicitud LUZ-0.6875654170768943 fue exitosa",
          "errorMessageUser": null
        }
      ]
    },
    "Property": []
  }
}

Respuesta de error

json

{
  "WSResponseHeader": {
    "System": {
      "name": "Kioskos",
      "correlationID": "KIOSKOS-11072022158",
      "processingServer": "Server01"
    },
    "Service": {
      "status": "Error",
      "responseDate": "2024-06-11T10:00:00Z",
      "processingServer": "Server01",
      "statusDetail": [
        {
          "errorCode": "ERROR_04",
          "errorDetailCode": null,
          "errorMessage": "Uno de los campos obligatorios no fue enviado o la fecha tiene un formato incorrecto",
          "errorMessageUser": "La solicitud no fue exitosa. En este momento no podemos atender tu solicitud, por favor acércate a una tienda"
        }
      ]
    },
    "Property": []
  }
}

Diagramas Técnicos

3.1 Flujo de datos

mermaid

graph TD
  A[Recepción de la solicitud] --> B[CustomersController]
  B --> C[CustomerBusiness]
  C --> D[CustomerUtil]
  C --> E[ConfigurationUtil]
  C --> F[AuditUtil]
  C --> G[OrderUtil]
  C --> H[LSIMModel]
  H --> I[Validación de identidad]
  C --> J[Construcción de respuesta]
  J --> K[Retorno al cliente]

3.2 Arquitectura de clases

mermaid

classDiagram
  class CustomersController {
    +IdentityValidation_v1(BaseRequestIdentityValidation)
  }
  class CustomerBusiness {
    +IdentityValidation_v1(BaseRequest, string)
  }
  class BaseRequestIdentityValidation {
    +BotBaseRequestHeader WSRequestHeader
    +IdentityValidationRequest WSRequestBody
  }
  class IdentityValidationRequest {
    +Audit Audit
    +string Document_Number
    +string Document_Type
    +string Expedition_Date
    +string Pre_Order
    +string Process
    +string Product
    +string Stratum
    +string Sub_Process
    +string Surname
  }
  class BaseResponseIdentityValidation {
    +BotBaseResponseHeader WSResponseHeader
  }
  CustomersController --> CustomerBusiness
  CustomersController --> BaseRequestIdentityValidation
  BaseRequestIdentityValidation --> IdentityValidationRequest
  CustomerBusiness --> BaseResponseIdentityValidation

3.3 Secuencia de ejecución

mermaid

sequenceDiagram
  participant Cliente
  participant API as CustomersController
  participant Negocio as CustomerBusiness
  participant Util as CustomerUtil
  participant Config as ConfigurationUtil
  participant Audit as AuditUtil
  participant Orden as OrderUtil
  participant LSIM as LSIMModel
  Cliente->>API: POST /api/customers/v1/identityvalidation
  API->>Negocio: IdentityValidation_v1(request)
  Negocio->>Audit: Save_Request (entrada)
  Negocio->>Config: Get_Origin, Get_By_Code
  Negocio->>Util: Get (cliente)
  Negocio->>LSIM: Validar identidad
  Negocio->>Orden: Update_Phase_VentaLTE (si aplica)
  Negocio->>Audit: Save_Request (salida)
  Negocio->>Audit: Save_Identity_Validation
  Negocio-->>API: BaseResponseIdentityValidation
  API-->>Cliente: Respuesta

Políticas y Consideraciones

Políticas de seguridad

Mecanismos de autenticación y autorización:

Requiere autenticación JWT y validación de canal/sistema
Valida origen, canal y correlación de la petición
Integra con sistema LSIM para validación biométrica

Validaciones de seguridad implementadas:

Validación de campos obligatorios y formato de datos
Verificación de habilitación del canal para el endpoint
Auditoría completa de entrada y salida
Validación contra base de datos de clientes

Límites de tasa (rate limits):

No se especifican límites explícitos en el código
Se recomienda implementar rate limiting por canal/sistema

SLAs aplicables:

Tiempo de respuesta esperado: < 5 segundos
Disponibilidad: 99.9%

Recomendaciones y mejores prácticas

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

Implementar rate limiting por canal y sistema
Agregar validación de formato de fecha más robusta
Implementar cache para consultas frecuentes de configuración
Mejorar el manejo de errores específicos de LSIM

Optimizaciones posibles:

Implementar cache de tipologías de configuración
Optimizar consultas a base de datos de clientes
Implementar circuit breaker para integración con LSIM
Agregar métricas de performance y monitoreo

Consideraciones de mantenimiento importantes:

Mantener actualizada la configuración de canales habilitados
Monitorear la integración con LSIM para detectar fallas
Revisar periódicamente los logs de auditoría
Validar que las tipologías de error estén actualizadas

Sugerencias de seguridad aplicables:

Implementar encriptación de datos sensibles en tránsito
Agregar validación de IP para prevenir ataques
Implementar logging de seguridad para detectar intentos de fraude
Revisar periódicamente los permisos de acceso al endpoint

Valida la identidad de clientes ETB - customers-v1-identityvalidation ​

Documentación del Servicio ​

Descripción general ​

Especificación técnica ​

Parámetros de entrada (Request) ​

Headers ​

Body ​

Objeto anidado: Audit ​

Respuesta esperada (Response) ​

Headers ​

Body ​

Objeto anidado: WSResponseHeader ​

Objeto anidado: System ​

Objeto anidado: Service ​

Objeto anidado: 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 ​

Políticas y Consideraciones ​

Políticas de seguridad ​

Recomendaciones y mejores prácticas ​

Valida la identidad de clientes ETB - customers-v1-identityvalidation

Documentación del Servicio

Descripción general

Especificación técnica

Parámetros de entrada (Request)

Headers

Body

Objeto anidado: Audit

Respuesta esperada (Response)

Headers

Body

Objeto anidado: WSResponseHeader

Objeto anidado: System

Objeto anidado: Service

Objeto anidado: 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

Políticas y Consideraciones

Políticas de seguridad

Recomendaciones y mejores prácticas