Gestión de Contactos de Clientes - customers-v1-setcontact

Información del Servicio

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

Documentación del Servicio

Descripción general

El servicio customers-v1-setcontact es un endpoint para crear el contacto de un cliente (si no existe) o actualizar el teléfono y/o móvil y/o email cuando el contacto existente no lo tiene. Este servicio permite gestionar la información de contacto asociada a los clientes del sistema ETB.

Categoría de negocio: Gestión de Clientes.

Casos de uso principales:

Creación de nuevos contactos para clientes existentes
Actualización de información de contacto (teléfono, móvil, email)
Validación de datos de contacto antes de su almacenamiento
Gestión de múltiples contactos por cliente

Especificación técnica

Endpoint completo: /api/customers/v1/setcontact
Método HTTP: POST
Capas involucradas:
- Controlador: CustomersController.SetContact_v1
- Lógica de negocio: CustomerBusiness.SetContact_v1
- Acceso a datos: CustomerUtil.Create_Contact, CustomerUtil.Update_Contact

Flujo de procesamiento:

Validación de la petición y conversión de datos
Obtención del origen y tipologías de configuración
Consulta del cliente en el sistema CRM
Validación y creación/actualización del contacto
Auditoría de la transacción

Dependencias principales:

Sistema CRM para consulta de clientes
Base de datos MongoDB para auditoría
Configuraciones de tipologías de error
Utilidades de validación de clientes

Consideraciones de seguridad:

Autenticación mediante headers de sistema
Validación de datos de entrada
Auditoría completa de transacciones
Manejo seguro de información personal

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
Contact_Address	string	No	Dirección del contacto
Contact_Document_Number	string	Sí	Número de identificación del contacto
Contact_Document_Type	string	Sí	Tipo de identificación del contacto
Contact_Email	string	No	Correo electrónico del contacto
Contact_Mobile_Phone	string	No	Teléfono celular del contacto
Contact_Name	string	No	Nombre del contacto
Contact_Phone	string	No	Teléfono fijo del contacto
Contact_Second_Surname	string	No	Segundo apellido del contacto
Contact_Surname	string	No	Primer apellido del contacto
Customer_Document_Number	string	Sí	Número de identificación del cliente
Customer_Document_Type	string	Sí	Tipo de identificación del cliente

Estructura de objetos anidados:

Estructura de WSRequestHeader

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

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

Body

La respuesta no incluye un body específico, solo la cabecera con el estado de la operación.

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

Manejo de errores

Código	Descripción	Ejemplo
ERROR_04	Objetos no acordes a la petición	"La solicitud {0} no fue exitosa. Fueron enviados objetos no acordes a la petición"
ERROR_07	Cliente o servicio no encontrado	"La solicitud {0} no fue exitosa. Cliente o servicio no encontrado"
ERROR_08	Error al actualizar contacto	"La solicitud {0} no fue exitosa. Error al actualizar el contacto"

Análisis de Componentes

Modelos y componentes

Modelos base utilizados:

BaseRequestSetCustomerContact - Modelo de petición específico
SetCustomerContactRequest - Body de la petición
BaseResponseSetCustomerContact - Modelo de respuesta
BotBaseRequestHeader - Cabecera estándar de petición
BotBaseResponseHeader - Cabecera estándar de respuesta

Utilidades y servicios comunes:

CustomerUtil - Operaciones de gestión de clientes
ConfigurationUtil - Gestión de configuraciones y tipologías
AuditUtil - Auditoría de transacciones
Util.FillBaseRequest - Llenado de información base

Patrones de diseño implementados:

Singleton Pattern: CustomerBusiness.GetInstance
Template Method: Flujo de procesamiento estándar
Strategy Pattern: Diferentes estrategias de validación

Componentes reutilizados:

Modelos de CRM (CustomerModel, ContactModel)
Utilidades de configuración y auditoría
Estructuras base de request/response

Referencias cruzadas:

Endpoint relacionado: /api/customers/v1/get (consulta de clientes)
Endpoint relacionado: /api/customers/v1/settyc (términos y condiciones)

Ejemplos de Request/Response

Solicitud (request)

json

{
  "WSRequestHeader": {
    "System": {
      "name": "MAX",
      "correlationID": "LUZ-0.2793172019603388",
      "processingServer": null
    },
    "Property": [
      {
        "name": null,
        "value": null
      },
      {
        "name": null,
        "value": null
      }
    ]
  },
  "WSRequestBody": {
    "Contact_Address": "",
    "Customer_Document_Type": "CC",
    "Customer_Document_Number": "1075260000",
    "Contact_Document_Type": "CC",
    "Contact_Document_Number": "1075260000",
    "Contact_Email": "prueba@hotmail.com",
    "Contact_Mobile_Phone": "3106706000",
    "Contact_Name": "Mauricio",
    "Contact_Phone": "6017200005",
    "Contact_Surname": "Cabrera",
    "Contact_Second_Surname": "",
    "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-07-31",
      "Hour": "18:53:34",
      "WhatsApp_Phone_Number": "",
      "Facebook_User": "{au_facebook_user}",
      "Twitter_User": "{au_twitter_user}"
    }
  }
}

Respuesta exitosa

json

{
  "WSResponseHeader": {
    "System": {
      "name": "MAX",
      "correlationID": "LUZ-0.2793172019603388",
      "processingServer": null
    },
    "Service": {
      "status": "OK",
      "responseDate": "2025-07-31T18:53:35.215534Z",
      "processingServer": null,
      "statusDetail": [
        {
          "errorCode": "OK_01",
          "errorDetailCode": "El contacto no existia y fue creado",
          "errorMessage": "La solicitud LUZ-0.2793172019603388 fue exitosa. Fue adicionado el nuevo contacto al cliente",
          "errorMessageUser": null
        }
      ]
    },
    "Property": [
      {
        "name": null,
        "value": null
      }
    ]
  }
}

Respuesta de error

json

{
  "WSResponseHeader": {
    "System": {
      "Name": "BOT_SYSTEM",
      "CorrelationID": "REQ-12345-67890",
      "ProcessingServer": "BOT-SERVER-01"
    },
    "Service": {
      "Status": "FAIL",
      "ResponseDate": "2024-12-19T10:30:00.000Z",
      "ProcessingServer": "BOT-SERVER-01",
      "StatusDetail": [
        {
          "ErrorCode": "ERROR_04",
          "ErrorMessage": "La solicitud REQ-12345-67890 no fue exitosa. Fueron enviados objetos no acordes a la petición",
          "ErrorMessageUser": "La solicitud REQ-12345-67890 no fue exitosa. Fueron enviados objetos no acordes a la petición",
          "ErrorDetailCode": "La solicitud REQ-12345-67890 no fue exitosa. Fueron enviados objetos no acordes a la petición"
        }
      ]
    },
    "Property": [
      {
        "Name": "Channel",
        "Value": "WEB"
      }
    ]
  }
}

Diagramas Técnicos

3.1 Flujo de datos

mermaid

graph TD
  A[Recepción de la solicitud] --> B[CustomersController.SetContact_v1]
  B --> C[CustomerBusiness.SetContact_v1]
  C --> D[Validación de datos]
  D --> E[Consulta cliente en CRM]
  E --> F{¿Existe contacto?}
  F -->|Sí| G[Actualizar contacto]
  F -->|No| H[Crear contacto]
  G --> I[Auditoría]
  H --> I
  I --> J[Respuesta]

3.2 Arquitectura de clases

mermaid

classDiagram
  class CustomersController {
    +SetContact_v1(BaseRequestSetCustomerContact)
  }
  class CustomerBusiness {
    +SetContact_v1(BaseRequest, string)
  }
  class CustomerUtil {
    +Is_Contact(Customer, string, string)
    +Create_Contact(Customer, Contact)
    +Update_Contact(Customer, Contact)
  }
  class SetCustomerContactRequest {
    +Audit Audit
    +string Contact_Address
    +string Contact_Document_Number
    +string Contact_Document_Type
    +string Contact_Email
    +string Contact_Mobile_Phone
    +string Contact_Name
    +string Contact_Phone
    +string Contact_Second_Surname
    +string Contact_Surname
    +string Customer_Document_Number
    +string Customer_Document_Type
  }
  CustomersController --> CustomerBusiness
  CustomerBusiness --> CustomerUtil
  CustomerBusiness --> SetCustomerContactRequest

3.3 Secuencia de ejecución

mermaid

sequenceDiagram
  participant Cliente
  participant CustomersController
  participant CustomerBusiness
  participant CustomerUtil
  participant CRM
  participant MongoDB
  Cliente->>CustomersController: POST /api/customers/v1/setcontact
  CustomersController->>CustomerBusiness: SetContact_v1(request)
  CustomerBusiness->>CustomerBusiness: Validar datos de entrada
  CustomerBusiness->>CRM: Consultar cliente
  CRM-->>CustomerBusiness: Datos del cliente
  CustomerBusiness->>CustomerUtil: Is_Contact(customer, docType, docNumber)
  CustomerUtil-->>CustomerBusiness: Existe contacto
  alt Contacto existe
    CustomerBusiness->>CustomerUtil: Update_Contact(customer, contact)
  else Contacto no existe
    CustomerBusiness->>CustomerUtil: Create_Contact(customer, contact)
  end
  CustomerUtil-->>CustomerBusiness: Resultado operación
  CustomerBusiness->>MongoDB: Guardar auditoría
  CustomerBusiness-->>CustomersController: Respuesta
  CustomersController-->>Cliente: Respuesta HTTP

Políticas y Consideraciones

Políticas de seguridad

Mecanismos de autenticación y autorización:

Validación de headers de sistema obligatorios
Autenticación mediante nombre de sistema y credenciales
Validación de IP de origen para auditoría

Validaciones de seguridad implementadas:

Validación de datos de entrada obligatorios
Sanitización de información personal
Control de acceso basado en roles de sistema

Límites de tasa (rate limits):

No se implementan límites específicos de tasa
Control mediante auditoría de transacciones
Monitoreo de uso por sistema origen

SLAs aplicables:

Tiempo de respuesta esperado: < 2 segundos
Disponibilidad del servicio: 99.9%
Tolerancia a fallos: Múltiples reintentos automáticos

Recomendaciones y mejores prácticas

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

Implementar validación más robusta de formatos de email y teléfonos
Agregar logging detallado para debugging
Implementar cache para consultas frecuentes de clientes
Mejorar manejo de excepciones con información más específica

Optimizaciones posibles:

Implementar transacciones atómicas para operaciones de contacto
Agregar índices optimizados en MongoDB para consultas de clientes
Implementar batch processing para múltiples contactos
Optimizar consultas a CRM con proyecciones específicas

Consideraciones de mantenimiento importantes:

Mantener sincronización entre sistemas CRM y MongoDB
Monitorear el crecimiento de la colección de auditoría
Implementar limpieza periódica de logs antiguos
Mantener actualizadas las configuraciones de tipologías

Sugerencias de seguridad aplicables:

Implementar encriptación de datos sensibles en tránsito
Agregar validación de tokens JWT para autenticación
Implementar rate limiting por IP y sistema
Agregar logging de seguridad para auditoría de accesos

Gestión de Contactos de Clientes - customers-v1-setcontact ​

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 ​

Gestión de Contactos de Clientes - customers-v1-setcontact

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