Customers v1 EnrollValidationCode - Generación de Códigos LISIM

Información del Servicio

Endpoint: /api/customers/v1/enrollvalidationcode
Método: POST
Versión: v1
Categoría: Customer Management

Documentación del Servicio

Descripción general

El servicio customers-v1-enrollvalidationcode es un componente fundamental del sistema BotServices que permite generar códigos de validación LISIM (Línea de Servicio de Identificación y Medición) para clientes. Este servicio forma parte del proceso de autenticación y validación de identidad de los clientes de ETB.

Propósito Principal

Generar códigos de validación únicos para verificar la identidad del cliente
Enviar códigos de validación por SMS y correo electrónico
Validar la información de contacto del cliente (teléfono y email)
Proporcionar un token de sesión para procesos posteriores de validación

Categoría de negocio: Gestión de Clientes - Autenticación y Validación

Casos de Uso Principales

Validación de identidad del cliente durante procesos de autogestión
Verificación de información de contacto (teléfono y email)
Proceso de registro y actualización de datos del cliente
Autenticación en portales de autogestión
Validación previa a la realización de trámites comerciales

Especificación Técnica

Capas involucradas:

Controlador: CustomersController.EnrollValidationCode_v1()
Lógica de negocio: CustomerBusiness.EnrollValidationCode_v1()
Utilidades: CustomerUtil.GenerateValidationCode()
Acceso a datos: Operaciones en base de datos MongoDB y servicios externos
Servicios externos:
- ResponsysServiceClient (validación de correo)
- ProcesosCodigoLISIMClient (generación de códigos)

Flujo de procesamiento:

Recepción de la solicitud HTTP POST
Validación de autenticación y autorización
Conversión y validación de datos de entrada
Auditoría de entrada
Obtención del origen de la petición
Consulta del cliente en base de datos
Validación de parámetros de configuración
Generación de códigos de validación LISIM
Actualización de información del cliente
Auditoría de salida y BAM
Respuesta con códigos generados

Dependencias principales:

CustomerBusiness - Lógica de negocio principal
CustomerUtil - Utilidades para gestión de clientes
AuditUtil - Gestión de auditoría
ConfigurationUtil - Gestión de configuraciones
ResponsysServiceClient - Validación de correos
ProcesosCodigoLISIMClient - Generación de códigos LISIM
CRUD_MDM_CLIENTE - Acceso a datos del cliente

Consideraciones de Seguridad

Autenticación mediante token JWT
Validación de origen de la petición
Auditoría completa de entrada y salida
Control de intentos de validación
Validación de formato de teléfono y correo
Encriptación de datos sensibles

Parámetros de Entrada (Request)

Headers

Campo	Tipo	Obligatorio	Descripción
Authorization	string	Sí	Token JWT de autenticación
Content-Type	string	Sí	application/json
X-Requested-With	string	No	XMLHttpRequest

Body - WSRequestHeader

Campo	Tipo	Obligatorio	Descripción
System	object	Sí	Información del sistema que origina la petición
System.Name	string	Sí	Nombre del sistema (ej: "KIOSKOS", "AUTOGESTION")
System.CorrelationID	string	Sí	Identificador único de correlación
System.ProcessingServer	string	Sí	Servidor de procesamiento
Property	array	No	Propiedades adicionales de la petición

Body - WSRequestBody

Campo	Tipo	Obligatorio	Descripción
Audit	object	Sí	Información de auditoría de la aplicación
Audit.Canal	string	Sí	Canal desde donde se origina la petición
Audit.Id_Device	string	No	Identificador del dispositivo
Audit.SO	string	No	Sistema operativo del dispositivo
Audit.IP_Address	string	No	Dirección IP del cliente
Audit.IP_Latitude	string	No	Latitud de la ubicación IP
Audit.IP_Longitude	string	No	Longitud de la ubicación IP
Audit.WhatsApp_Phone_Number	string	No	Número de WhatsApp del cliente
Audit.Facebook_User	string	No	Usuario de Facebook del cliente
Audit.Twitter_User	string	No	Usuario de Twitter del cliente
Document_Number	string	Sí	Número de identificación del cliente
Document_Type	string	Sí	Tipo de identificación (CC, CE, NIT, etc.)
Email	string	Sí	Correo electrónico del cliente
Phone	string	Sí	Número de teléfono del cliente

Respuesta Esperada (Response)

Headers

Campo	Tipo	Obligatorio	Descripción
Content-Type	string	Sí	application/json
Cache-Control	string	No	no-cache

Body - WSResponseHeader

Campo	Tipo	Obligatorio	Descripción
System	object	Sí	Información del sistema de respuesta
System.Name	string	Sí	Nombre del sistema que procesó la petición
System.CorrelationID	string	Sí	Identificador de correlación de respuesta
Service	object	Sí	Información del servicio
Service.Status	string	Sí	Estado del servicio (OK/FAIL)
Service.StatusDetail	array	Sí	Detalles del estado del servicio
Property	array	No	Propiedades adicionales de la respuesta

Body - WSResponseBody

Campo	Tipo	Obligatorio	Descripción
Code_Email	string	Sí	Código de validación generado para email
Code_Phone	string	Sí	Código de validación generado para SMS
Token	string	Sí	Token único asociado a la validación

Manejo de Errores

Código	Descripción	Ejemplo
ERROR_04	Fueron enviados objetos no acordes a la petición	Request nulo o campos obligatorios faltantes
ERROR_08	El correo electrónico no es válido	Formato de email incorrecto
ERROR_09	El número de teléfono no es válido	Teléfono no empieza con 3 o formato inválido
ERROR_10	Error al generar códigos de validación	Fallo en servicio LISIM
ERROR_12	Error técnico en la generación de códigos	Excepción no controlada
OK_01	Operación exitosa	Códigos generados correctamente

Análisis de Componentes

Modelos y Componentes

Modelos base utilizados:

BaseRequest - Clase base para todas las peticiones
BaseResponse - Clase base para todas las respuestas
BotBaseRequestHeader - Cabecera estándar de petición
BotBaseResponseHeader - Cabecera estándar de respuesta
ResultModel - Modelo para manejo de resultados y errores

Modelos específicos del servicio:

BaseRequestEnrollValidationCode_v1 - Petición específica del servicio
BaseResponseEnrollValidationCode_v1 - Respuesta específica del servicio
EnrollValidationCodeRequest_v1 - Body de la petición
EnrollValidationCodeResponse_v1 - Body de la respuesta

Utilidades y servicios comunes:

CustomerUtil - Utilidades para gestión de clientes
AuditUtil - Gestión de auditoría y logs
ConfigurationUtil - Gestión de configuraciones y tipologías
SecurityUtil - Validaciones de seguridad
UtilDate - Utilidades de fecha y hora

Patrones de diseño implementados:

Singleton Pattern: Utilizado en todas las clases de utilidad
Factory Pattern: Para creación de modelos de respuesta
Strategy Pattern: Para diferentes tipos de validación
Observer Pattern: Para auditoría y logging

Componentes reutilizados:

Sistema de auditoría (AuditUtil)
Gestión de configuraciones (ConfigurationUtil)
Validaciones de seguridad (SecurityUtil)
Modelos base de request/response
Cliente LISIM (ProcesosCodigoLISIMClient)

Referencias Cruzadas

/api/customers/v1/validatecodelsim - Validación de códigos generados
/api/customers/v1/get - Consulta de información del cliente
/api/customers/v1/update - Actualización de datos del cliente

Ejemplos de Request/Response

Solicitud (Request)

json

{
  "WSRequestHeader": {
    "System": {
      "Name": "KIOSKOS",
      "CorrelationID": "KIOSKOS-21062022-045820",
      "ProcessingServer": "BOT-SERVER-01"
    },
    "Property": [
      {
        "Name": "Version",
        "Value": "1.0"
      }
    ]
  },
  "WSRequestBody": {
    "Audit": {
      "Canal": "KIOSKOS",
      "Id_Device": "KIOSK-001",
      "SO": "Windows 10",
      "IP_Address": "192.168.1.100",
      "IP_Latitude": "4.7110",
      "IP_Longitude": "-74.0721",
      "WhatsApp_Phone_Number": "",
      "Facebook_User": "",
      "Twitter_User": ""
    },
    "Document_Number": "98302931",
    "Document_Type": "CC",
    "Email": "cliente@ejemplo.com",
    "Phone": "3001234567"
  }
}

Respuesta Exitosa

json

{
  "WSResponseHeader": {
    "System": {
      "Name": "BOTServices",
      "CorrelationID": "KIOSKOS-21062022-045820"
    },
    "Service": {
      "Status": "OK",
      "StatusDetail": [
        {
          "ErrorCode": "OK_01",
          "ErrorDetailCode": "OK_01",
          "ErrorDetailMessage": "La respuesta fue exitosa"
        }
      ]
    }
  },
  "WSResponseBody": {
    "Code_Email": "123456",
    "Code_Phone": "789012",
    "Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Respuesta de Error

json

{
  "WSResponseHeader": {
    "System": {
      "Name": "BOTServices",
      "CorrelationID": "KIOSKOS-21062022-045820"
    },
    "Service": {
      "Status": "FAIL",
      "StatusDetail": [
        {
          "ErrorCode": "ERROR_09",
          "ErrorDetailCode": "ERROR_09",
          "ErrorDetailMessage": "El número de teléfono no es válido"
        }
      ]
    }
  },
  "WSResponseBody": null
}

Diagramas Técnicos

3.1 Flujo de Datos

mermaid

graph TD
    A[Cliente] --> B[API Gateway]
    B --> C[CustomersController]
    C --> D[CustomerBusiness]
    D --> E[AuditUtil - Entrada]
    E --> F[Validación de datos]
    F --> G[CustomerUtil]
    G --> H[ResponsysServiceClient]
    H --> I[ProcesosCodigoLISIMClient]
    I --> J[Generación de códigos]
    J --> K[Actualización BD]
    K --> L[AuditUtil - Salida]
    L --> M[Respuesta al cliente]
    
    F -->|Error| N[Error Response]
    H -->|Error| N
    I -->|Error| N
    K -->|Error| N

3.2 Arquitectura de Clases

mermaid

classDiagram
    class CustomersController {
        +EnrollValidationCode_v1(BaseRequestEnrollValidationCode_v1)
    }
    
    class CustomerBusiness {
        +EnrollValidationCode_v1(BaseRequest, string)
    }
    
    class CustomerUtil {
        +GenerateValidationCode(RequestModel, CustomerModel, string, string, ref string, ref string, ref string)
        +Can_Validation_Code(CustomerModel)
        +UpdateValidationCodeAttempt(CustomerModel, bool)
    }
    
    class BaseRequestEnrollValidationCode_v1 {
        +WSRequestHeader: BotBaseRequestHeader
        +WSRequestBody: EnrollValidationCodeRequest_v1
    }
    
    class BaseResponseEnrollValidationCode_v1 {
        +WSResponseHeader: BotBaseResponseHeader
        +WSResponseBody: EnrollValidationCodeResponse_v1
    }
    
    class EnrollValidationCodeRequest_v1 {
        +Audit: Audit
        +Document_Number: string
        +Document_Type: string
        +Email: string
        +Phone: string
    }
    
    class EnrollValidationCodeResponse_v1 {
        +Code_Email: string
        +Code_Phone: string
        +Token: string
    }
    
    CustomersController --> CustomerBusiness
    CustomerBusiness --> CustomerUtil
    CustomerBusiness --> BaseResponseEnrollValidationCode_v1
    BaseRequestEnrollValidationCode_v1 --> EnrollValidationCodeRequest_v1
    BaseResponseEnrollValidationCode_v1 --> EnrollValidationCodeResponse_v1

3.3 Secuencia de Ejecución

mermaid

sequenceDiagram
    participant Client
    participant Controller as CustomersController
    participant Business as CustomerBusiness
    participant CustomerUtil
    participant ResponsysClient
    participant LISIMClient
    participant Database
    participant AuditUtil
    
    Client->>Controller: POST /api/customers/v1/enrollvalidationcode
    Controller->>Business: EnrollValidationCode_v1()
    Business->>AuditUtil: Save_Request() - Entrada
    Business->>Business: Validación de datos de entrada
    alt Datos válidos
        Business->>CustomerUtil: GenerateValidationCode()
        CustomerUtil->>ResponsysClient: ValidaCorreo()
        ResponsysClient-->>CustomerUtil: Resultado validación
        alt Correo válido
            CustomerUtil->>LISIMClient: GenerarCodigosValidacionLISIM()
            LISIMClient-->>CustomerUtil: Códigos generados
            CustomerUtil->>Database: Actualizar información cliente
            Database-->>CustomerUtil: Confirmación
            CustomerUtil-->>Business: Resultado exitoso
        else Correo inválido
            CustomerUtil-->>Business: ERROR_08
        end
    else Datos inválidos
        Business-->>Business: ERROR_04
    end
    Business->>AuditUtil: Save_Request() - Salida
    Business->>AuditUtil: Save_Generate_Validation_Codes()
    Business-->>Controller: BaseResponseEnrollValidationCode_v1
    Controller-->>Client: Respuesta HTTP

Políticas y Consideraciones

Políticas de Seguridad

Mecanismos de autenticación y autorización:

Autenticación mediante JWT (JSON Web Token)
Validación de origen de la petición mediante SecurityUtil
Control de acceso basado en roles y permisos
Validación de IP y geolocalización

Validaciones de seguridad implementadas:

Validación de formato de correo electrónico
Validación de formato de número de teléfono (debe empezar con 3 y tener máximo 10 dígitos)
Control de intentos de validación por cliente
Validación de tipo de documento
Sanitización de datos de entrada

Límites de tasa (rate limits):

Control de intentos por cliente mediante parámetros configurables
Límite de intentos por día configurado en base de datos
Tiempo de espera entre intentos (horas configurables)
Bloqueo temporal tras exceder límites

SLAs aplicables:

Tiempo de respuesta máximo: 30 segundos
Disponibilidad: 99.9%
Tolerancia a fallos: 3 reintentos automáticos
Tiempo de procesamiento: < 5 segundos

Recomendaciones y Mejores Prácticas

Puntos de mejora específicos:

Manejo de excepciones:

csharp

// Actual - Captura genérica
catch
{
    continuar = false;
    Result = new BotModel.Principal.ResultModel(ConfigurationUtil.GetInstance.Get_Tipology(Tipologias, "ERROR_12"));
}

// Recomendado - Captura específica
catch (Exception ex)
{
    continuar = false;
    _telemetryTracker.TrackException(ex);
    Result = new BotModel.Principal.ResultModel(ConfigurationUtil.GetInstance.Get_Tipology(Tipologias, "ERROR_12"));
}

Validación de parámetros:

csharp

// Actual - Validación básica
if (String.IsNullOrEmpty(Phone) || !Phone.StartsWith("3") || Phone.Length > 10 || !Phone.All(char.IsDigit))

// Recomendado - Validación con regex
if (!Regex.IsMatch(Phone, @"^3\d{9}$"))

Logging estructurado:

csharp

// Agregar logging estructurado para mejor trazabilidad
_logger.LogInformation("Generando códigos de validación para cliente {DocumentType}:{DocumentNumber}", 
    Customer.Document_Type, Customer.Document_Number);

Optimizaciones posibles:

Caché de configuraciones:
- Implementar caché distribuido para tipologías de error
- Reducir consultas a base de datos para configuraciones
Procesamiento asíncrono:
- Convertir operaciones de auditoría a async/await
- Implementar procesamiento en background para logs
Validación temprana:
- Validar formato de datos antes de consultas a servicios externos
- Implementar circuit breaker para servicios externos

Consideraciones de mantenimiento:

Monitoreo:
- Implementar métricas de rendimiento
- Agregar alertas para fallos de servicios externos
- Monitorear tasa de éxito/fallo
Documentación:
- Mantener documentación de cambios en el servicio
- Documentar nuevos códigos de error
- Actualizar ejemplos de uso
Testing:
- Implementar tests unitarios para CustomerUtil
- Agregar tests de integración para flujo completo
- Implementar tests de carga para validar rendimiento

Sugerencias de seguridad:

Encriptación:
- Encriptar códigos de validación en tránsito
- Implementar rotación de tokens
- Agregar firma digital a las respuestas
Validación adicional:
- Implementar validación de dispositivo
- Agregar verificación de comportamiento (fraude)
- Validar geolocalización del cliente
Auditoría mejorada:
- Logging de eventos de seguridad
- Alertas para patrones sospechosos
- Retención de logs por períodos configurables

Notas Adicionales

El servicio es parte del ecosistema de autenticación LISIM de ETB
Los códigos generados tienen un tiempo de vida limitado
El token devuelto debe ser utilizado en el servicio de validación correspondiente
El servicio está diseñado para ser escalable y tolerante a fallos

Customers v1 EnrollValidationCode - Generación de Códigos LISIM ​

Documentación del Servicio ​

Descripción general ​

Especificación Técnica ​

Parámetros de Entrada (Request) ​

Headers ​

Body - WSRequestHeader ​

Body - WSRequestBody ​

Respuesta Esperada (Response) ​

Headers ​

Body - WSResponseHeader ​

Body - WSResponseBody ​

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 ​

Customers v1 EnrollValidationCode - Generación de Códigos LISIM

Documentación del Servicio

Descripción general

Especificación Técnica

Parámetros de Entrada (Request)

Headers

Body - WSRequestHeader

Body - WSRequestBody

Respuesta Esperada (Response)

Headers

Body - WSResponseHeader

Body - WSResponseBody

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