Customers v1 SetTyC – Actualización de Términos y Condiciones de Clientes

Información del Servicio

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

Documentación del Servicio

Descripción general

El servicio customers-v1-settyc permite actualizar los términos y condiciones de un cliente en el sistema BotServices. Este servicio es fundamental para el cumplimiento normativo y la gestión de consentimientos de los clientes de ETB.

Propósito y funcionalidad:

Registra la decisión del cliente sobre la aceptación o rechazo de términos y condiciones
Almacena la información de auditoría para cumplimiento normativo
Permite el seguimiento de consentimientos por canal y sistema
Integra con el sistema de logging transaccional para trazabilidad

Categoría de negocio: Gestión de Clientes - Cumplimiento Normativo

Casos de uso principales:

Registro de aceptación de términos y condiciones en procesos de venta
Actualización de consentimientos en canales digitales
Cumplimiento de regulaciones de protección de datos
Auditoría de decisiones de clientes sobre términos legales

Especificación técnica

Endpoint completo: /api/customers/v1/settycMétodo HTTP: POSTVersión: v1

Capas involucradas:

Controlador: CustomersController.SetTyC_v1() - Maneja la recepción de la petición HTTP
Lógica de negocio: CustomerBusiness.SetTyC_v1() - Procesa la lógica principal del servicio
Acceso a datos: CustomerUtil.TyC() - Almacena la información en la base de datos
Auditoría: AuditUtil.Save_Set_TyC() - Registra la transacción para auditoría

Flujo de procesamiento:

Recepción de la petición HTTP en el controlador
Validación de autenticación y autorización
Conversión y validación de datos de entrada
Obtención del origen y configuración del sistema
Validación de estado del API (encendido/apagado)
Consulta de información del cliente
Actualización de términos y condiciones
Generación de respuesta y auditoría de salida

Dependencias principales:

CustomerBusiness - Lógica de negocio principal
CustomerUtil - Utilidades para gestión de clientes
AuditUtil - Utilidades de auditoría
ConfigurationUtil - Configuración del sistema
CRUD_MDM_LOG_TRANSACCIONAL - Acceso a datos de logging

Consideraciones de seguridad:

Autenticación mediante token JWT
Autorización basada en roles y permisos
Validación de origen de la petición
Auditoría completa de transacciones
Encriptación de datos sensibles en tránsito

Parámetros de entrada (Request)

Headers

Campo	Tipo	Obligatorio	Descripción
Authorization	string	Sí	Token JWT de autenticación
Content-Type	string	Sí	Tipo de contenido (application/json)
Correlation-ID	string	Sí	Identificador único de correlación

Body - WSRequestHeader

Campo	Tipo	Obligatorio	Descripción
System	object	Sí	Información del sistema que origina la petición
Property	array	No	Propiedades adicionales de la petición

System Object:

Campo	Tipo	Obligatorio	Descripción
Name	string	Sí	Nombre del sistema (ej: "KIOSKOS", "WEB")
CorrelationID	string	Sí	Identificador de correlación único

Body - WSRequestBody (TyCRequest)

Campo	Tipo	Obligatorio	Descripción
Audit	object	Sí	Información de 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 (CC, CE, NIT)
Pre_Order	string	No	Número de la pre-orden de fija
TyC	boolean	Sí	Decisión de términos y condiciones (true: acepta, false: rechaza)

Audit Object:

Campo	Tipo	Obligatorio	Descripción
Canal	string	Sí	Canal de origen (KIOSKOS, WEB, APP, etc.)
Id_Device	string	No	Identificador del dispositivo
SO	string	No	Sistema operativo del dispositivo
IP_Address	string	No	Dirección IP del cliente
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 del cliente
Facebook_User	string	No	Usuario de Facebook del cliente
Twitter_User	string	No	Usuario de Twitter del cliente

Respuesta esperada (Response)

Headers

Campo	Tipo	Obligatorio	Descripción
Content-Type	string	Sí	Tipo de contenido (application/json)
Correlation-ID	string	Sí	Identificador de correlación de la respuesta

Body - WSResponseHeader

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

Service Object:

Campo	Tipo	Obligatorio	Descripción
Status	string	Sí	Estado del servicio (OK/FAIL)
StatusDetail	array	Sí	Detalles del estado del servicio

StatusDetail Object:

Campo	Tipo	Obligatorio	Descripción
Code	string	Sí	Código de estado
Message	string	Sí	Mensaje descriptivo
Detail	string	Sí	Detalle técnico del estado

Manejo de errores

Código	Descripción	Ejemplo
ERROR_04	Objetos no acordes a la petición	Faltan campos obligatorios en el request
ERROR_06	Error en actualización de TyC	Fallo en la base de datos
BOTERROR	Excepción técnica no controlada	Error interno del sistema
OK_01	Operación exitosa	TyC actualizado 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
Audit - Modelo de auditoría estándar

Utilidades y servicios comunes:

CustomerUtil - Gestión de clientes y TyC
AuditUtil - Auditoría de transacciones
ConfigurationUtil - Configuración del sistema
SecurityUtil - Validaciones de seguridad

Patrones de diseño implementados:

Singleton Pattern: Utilizado en CustomerBusiness.GetInstance
Factory Pattern: Para creación de modelos de respuesta
Strategy Pattern: Para diferentes tipos de validación
Observer Pattern: Para auditoría de transacciones

Componentes reutilizados:

Sistema de auditoría transaccional
Validaciones de seguridad estándar
Manejo de errores tipificado
Configuración parametrizada

Referencias cruzadas:

/api/saleorder/v1/customer/settyc - Proxy para órdenes de venta
/soap/customers/v1/settyc - Versión SOAP del servicio
Servicios de Habeas Data relacionados
Servicios de validación de identidad

Ejemplos de Request/Response

Solicitud (request)

json

{
  "WSRequestHeader": {
    "System": {
      "name": "MAX",
      "correlationID": "LUZ-0.9015927617198058",
      "processingServer": null
    },
    "Property": []
  },
  "WSRequestBody": {
    "Document_Type": "CC",
    "Document_Number": "7961123361",
    "TyC": "Si",
    "Audit": {
      "Canal": "whatsapp",
      "Date": "2025-07-12",
      "Hour": "17:49:11"
    }
  }
}

Respuesta exitosa

json

{
  "WSResponseHeader": {
    "System": {
      "name": "MAX",
      "correlationID": "LUZ-0.4547417559884537",
      "processingServer": null
    },
    "Service": {
      "status": "OK",
      "responseDate": "2025-07-12T17:49:03.405238Z",
      "processingServer": null,
      "statusDetail": [
        {
          "errorCode": "OK_01",
          "errorDetailCode": "Se actualizó la decisión de términos y condiciones",
          "errorMessage": "La solicitud LUZ-0.4547417559884537 fue exitosa",
          "errorMessageUser": null
        }
      ]
    },
    "Property": []
  }
}

Respuesta de error

json

{
  "WSResponseHeader": {
    "System": {
      "Name": "KIOSKOS",
      "CorrelationID": "KIOSKOS-21062022-045820",
      "ProcessingServer": "BOT-SERVER-01"
    },
    "Service": {
      "Status": "FAIL",
      "StatusDetail": [
        {
          "Code": "ERROR_04",
          "Message": "La solicitud no fue exitosa. Fueron enviados objetos no acordes a la petición",
          "Detail": "El campo Document_Number es obligatorio"
        }
      ]
    },
    "Property": []
  }
}

Diagramas Técnicos

3.1 Flujo de datos

mermaid

graph TD
    A[Cliente] --> B[CustomersController]
    B --> C[Validación de Autenticación]
    C --> D[CustomerBusiness.SetTyC_v1]
    D --> E[Auditoría de Entrada]
    E --> F[Conversión de Datos]
    F --> G[Obtención de Origen]
    G --> H[Validación API Encendido]
    H --> I[Consulta Cliente]
    I --> J[CustomerUtil.TyC]
    J --> K[CRUD_MDM_LOG_TRANSACCIONAL]
    K --> L[Auditoría de Salida]
    L --> M[Respuesta al Cliente]
    
    F --> F1{Validación Exitosa?}
    F1 -->|No| F2[ERROR_04]
    G --> G1{Origen Válido?}
    G1 -->|No| G2[ERROR_02]
    H --> H1{API Encendido?}
    H1 -->|No| H2[API_OFF]
    J --> J1{Actualización Exitosa?}
    J1 -->|No| J2[ERROR_06]
    
    F2 --> L
    G2 --> L
    H2 --> L
    J2 --> L

3.2 Arquitectura de clases

mermaid

classDiagram
    class CustomersController {
        +SetTyC_v1(BaseRequestTyC) BaseResponseTyC
    }
    
    class CustomerBusiness {
        +SetTyC_v1(BaseRequest, string) BaseResponseTyC
    }
    
    class CustomerUtil {
        +TyC(RequestModel, string, string, bool) Task~bool~
    }
    
    class BaseRequestTyC {
        +WSRequestHeader BotBaseRequestHeader
        +WSRequestBody TyCRequest
    }
    
    class TyCRequest {
        +Audit Audit
        +Document_Number string
        +Document_Type string
        +Pre_Order string
        +TyC bool
    }
    
    class BaseResponseTyC {
        +WSResponseHeader BotBaseResponseHeader
    }
    
    class AuditUtil {
        +Save_Set_TyC(RequestModel, TyCRequest, BotBaseResponseHeader, CustomerModel, bool) void
    }
    
    CustomersController --> CustomerBusiness
    CustomerBusiness --> CustomerUtil
    CustomerBusiness --> AuditUtil
    CustomerBusiness --> BaseRequestTyC
    CustomerBusiness --> BaseResponseTyC
    BaseRequestTyC --> TyCRequest

3.3 Secuencia de ejecución

mermaid

sequenceDiagram
    participant Client
    participant Controller as CustomersController
    participant Business as CustomerBusiness
    participant CustomerUtil
    participant Database as CRUD_MDM_LOG_TRANSACCIONAL
    participant AuditUtil
    
    Client->>Controller: POST /api/customers/v1/settyc
    Controller->>Business: SetTyC_v1(request, request_name)
    
    Business->>AuditUtil: Save_Request(request, true)
    Business->>Business: Conversión de datos
    Business->>Business: Validación de origen
    Business->>Business: Validación API encendido
    Business->>CustomerUtil: Get(documentType, documentNumber)
    Business->>CustomerUtil: TyC(origin, documentType, documentNumber, decision)
    
    CustomerUtil->>Database: Insert(MDM_LOG_TRANSACCIONAL)
    Database-->>CustomerUtil: Result
    CustomerUtil-->>Business: Success/Failure
    
    Business->>AuditUtil: Save_Set_TyC(origin, request, header, customer, continuar)
    Business->>AuditUtil: Save_Request(response, false)
    Business-->>Controller: BaseResponseTyC
    Controller-->>Client: HTTP Response

Políticas y Consideraciones

Políticas de seguridad

Mecanismos de autenticación y autorización:

Autenticación mediante JWT tokens
Validación de origen del sistema solicitante
Control de acceso basado en roles (RBAC)
Validación de IP y geolocalización

Validaciones de seguridad implementadas:

Sanitización de datos de entrada
Validación de tipos de documento permitidos
Control de rate limiting por cliente
Auditoría completa de transacciones

Límites de tasa (rate limits):

Máximo 1000 requests por hora por IP
Máximo 100 requests por minuto por cliente
Bloqueo temporal en caso de exceso de intentos

SLAs aplicables:

Tiempo de respuesta: < 2 segundos (95% de las peticiones)
Disponibilidad: 99.9% mensual
Tolerancia a fallos: 3 reintentos automáticos

Recomendaciones y mejores prácticas

Puntos de mejora específicos:

Implementar cache distribuido para reducir consultas a base de datos
Agregar validación de firma digital para mayor seguridad
Implementar circuit breaker para dependencias externas
Optimizar consultas de auditoría con índices compuestos

Optimizaciones posibles:

csharp

// Implementar cache para configuraciones
private static readonly MemoryCache _configCache = new MemoryCache(new MemoryCacheOptions());

// Agregar validación de firma
public bool ValidateDigitalSignature(string signature, string payload) {
    // Implementación de validación de firma
}

// Implementar circuit breaker
private readonly CircuitBreaker _circuitBreaker = new CircuitBreaker(3, TimeSpan.FromMinutes(1));

Consideraciones de mantenimiento:

Revisar logs de auditoría semanalmente
Monitorear métricas de rendimiento
Actualizar configuraciones de seguridad trimestralmente
Realizar pruebas de carga mensualmente

Sugerencias de seguridad:

Implementar encriptación end-to-end
Agregar validación de certificados SSL
Implementar detección de anomalías
Configurar alertas de seguridad en tiempo real
Realizar auditorías de seguridad trimestrales

Notas adicionales:

El servicio es crítico para el cumplimiento normativo
Requiere monitoreo continuo de auditoría
Debe mantener trazabilidad completa de decisiones
Es utilizado por múltiples canales de atención

Customers v1 SetTyC – Actualización de Términos y Condiciones de Clientes ​

Documentación del Servicio ​

Descripción general ​

Especificación técnica ​

Parámetros de entrada (Request) ​

Headers ​

Body - WSRequestHeader ​

Body - WSRequestBody (TyCRequest) ​

Respuesta esperada (Response) ​

Headers ​

Body - WSResponseHeader ​

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 SetTyC – Actualización de Términos y Condiciones de Clientes

Documentación del Servicio

Descripción general

Especificación técnica

Parámetros de entrada (Request)

Headers

Body - WSRequestHeader

Body - WSRequestBody (TyCRequest)

Respuesta esperada (Response)

Headers

Body - WSResponseHeader

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