Actualización de Contacto PQR - notifications-v1-updatecontactpqr

Información del Servicio

Endpoint: /api/notifications/v1/updatecontactpqr
Método: POST
Versión: 1.0.0
Categoría: Notificaciones

Documentación del Servicio

Descripción general

El servicio notifications-v1-updatecontactpqr es un endpoint para actualizar los datos de contacto de una PQR mediante un proceso de validación por códigos de verificación. Este servicio funciona en dos momentos: primero genera códigos de validación y luego valida y actualiza los datos de contacto.

Categoría de negocio: Gestión de PQR y notificaciones.

Casos de uso principales:

Actualización de correo electrónico de contacto en PQR
Actualización de teléfono de contacto en PQR
Validación de identidad mediante códigos de verificación
Generación de códigos de validación por correo electrónico y SMS

Especificación técnica

Endpoint completo: /api/notifications/v1/updatecontactpqr
Método HTTP: POST
Capas involucradas:
- Controlador: NotificationsController
- Lógica de negocio: NotificationsBusiness
- Acceso a datos: PQRUtil, CustomerUtil

Flujo de procesamiento:

Validación de datos de entrada y auditoría
Consulta de la PQR por número de identificación
Consulta del cliente asociado a la PQR
Consulta del contacto específico
Generación de códigos de validación (primer momento)
Validación de códigos y actualización de datos (segundo momento)

Dependencias principales:

PQRUtil para gestión de PQR
CustomerUtil para gestión de clientes
ResponsysServiceClient para validación de correos
ConfigurationUtil para configuración del sistema

Consideraciones de seguridad:

Autenticación mediante token Bearer
Validación de origen de la petición
Auditoría completa de transacciones
Validación de formatos de datos de entrada

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	object	Sí	Datos de contacto de la PQR a actualizar
Num_PQR	string	Sí	Número o identificador de la PQR
Validation_Code_Email	object	No*	Información del código de validación por correo electrónico
Validation_Code_SMS	object	No*	Información del código de validación por SMS
Token	string	No*	Token de validación para actualización

*Obligatorio cuando ya se solicitó un código previo

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

Estructura de Contact

Campo	Tipo	Obligatorio	Descripción
Document_Number	string	Sí	Número de identificación del contacto
Document_Type	string	Sí	Tipo de identificación del contacto
Email_Contact	string	No*	Correo electrónico de contacto
Name_Contact	string	No	Nombre de contacto
Phone_Contact	string	No*	Teléfono de contacto

*Al menos uno de los dos campos debe ser enviado

Estructura de Validation_Code_Email

Campo	Tipo	Obligatorio	Descripción
Code_System	string	Sí	Código de validación generado por el sistema
Code_User	string	Sí	Código de validación escrito por el usuario

Estructura de Validation_Code_SMS

Campo	Tipo	Obligatorio	Descripción
Code_System	string	Sí	Código de validación generado por el sistema
Code_User	string	Sí	Código de validación escrito por el usuario

Respuesta esperada (Response)

Headers

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

Body

Campo	Tipo	Obligatorio	Descripción
Validation_Code_Email	object	No	Código de validación enviado por correo electrónico
Validation_Code_SMS	object	No	Código de validación enviado por SMS
Token	string	No	Token para validación en la actualizació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

Estructura de Validation_Code_Email

Campo	Tipo	Obligatorio	Descripción
Code_System	string	No	Código del sistema generado

Estructura de Validation_Code_SMS

Campo	Tipo	Obligatorio	Descripción
Code_System	string	No	Código del sistema generado

Manejo de errores

Código	Descripción	Ejemplo
ERROR_04	Error en la conversión de datos de entrada	"El request es nulo"
ERROR_06	PQR no encontrada o sin contacto	"La PQR especificada no existe"
ERROR_07	Cliente no encontrado	"El cliente asociado a la PQR no existe"
ERROR_08	Contacto no encontrado	"El contacto especificado no existe"
ERROR_09	Error en validación de correo electrónico	"El correo electrónico no es válido"
ERROR_10	Error en validación de teléfono	"El número de teléfono no es válido"
ERROR_11	Error en generación de códigos	"Error al generar códigos de validación"
ERROR_12	Error en actualización de datos	"Error al actualizar los datos de contacto"
ERROR_13	Error en validación de códigos	"Los códigos de validación son incorrectos"

Análisis de Componentes

Modelos y componentes

Modelos base utilizados:

UpdateContactPQRRequest_v1: Modelo de petición principal
UpdateContactPQRResponse_v1: Modelo de respuesta principal
UpdateContactPQRInfoRequest_v1: Información del contacto
UpdateContactPQRValidationRequest_v1: Códigos de validación
UpdateContactPQRValidationResponse_v1: Respuesta de códigos

Utilidades y servicios comunes:

PQRUtil: Gestión de PQR y códigos de validación
CustomerUtil: Gestión de clientes y contactos
ResponsysServiceClient: Validación de correos electrónicos
ConfigurationUtil: Configuración del sistema

Patrones de diseño implementados:

Singleton pattern para servicios de negocio
Factory pattern para creación de respuestas
Strategy pattern para validaciones

Componentes reutilizados:

BotBaseRequestHeader/BotBaseResponseHeader: Cabeceras estándar
Audit: Auditoría de transacciones
BaseRequest/BaseResponse: Clases base de petición/respuesta

Referencias cruzadas:

PQRController: Gestión de PQR
CustomerController: Gestión de clientes
NotificationsController: Gestión de notificaciones

Ejemplos de Request/Response

Solicitud (request) - Primer momento (Generación de códigos)

json

{
  "WSRequestHeader": {
    "System": {
      "name": "MAX",
      "correlationID": "LUZ-0.9473387148006269",
      "processingServer": null
    },
    "Property": [
      {
        "value": null,
        "name": null
      }
    ]
  },
  "WSRequestBody": {
    "Audit": {
      "IP_Address": "10.10.0.1",
      "SO": "Android 9",
      "Id_Device": "d952095584ec1d26",
      "Canal": null,
      "IP_Longitude": "-74.0980",
      "WhatsApp_Phone_Number": "{au_whatsapp_number}",
      "Facebook_User": "{au_facebook_user}",
      "Twitter_User": "{au_twitter_user}",
      "IP_Latitude": "4.8094"
    },
    "Contact": {
      "Document_Number": "992041",
      "Document_Type": "NIT",
      "Email_Contact": "Prueba@gmail.com",
      "Phone_Contact": "3124883086",
      "Name_Contact": "SinlisimNIT Pruebaj"
    },
    "Num_PQR": null,
    "Validation_Code_Email": {
      "Code_System": "",
      "Code_User": ""
    },
    "Validation_Code_SMS": {
      "Code_System": "",
      "Code_User": ""
    },
    "Token": ""
  }
}

Respuesta exitosa - Primer momento

json

{
  "WSResponseHeader": {
    "System": {
      "name": "MAX",
      "correlationID": "LUZ-0.8787339309809213",
      "processingServer": null
    },
    "Service": {
      "status": "OK",
      "responseDate": "2025-07-31T01:07:23.588756Z",
      "processingServer": null,
      "statusDetail": [
        {
          "errorCode": "OK_01",
          "errorDetailCode": "La solicitud fue exitosa",
          "errorMessage": "La solicitud LUZ-0.8787339309809213 fue exitosa.",
          "errorMessageUser": null
        }
      ]
    },
    "Property": [
      {
        "name": null,
        "value": null
      }
    ]
  },
  "WSResponseBody": null
}

Solicitud (request) - Segundo momento (Validación y actualización)

json

{
  "WSRequestHeader": {
    "System": {
      "Name": "SISTEMA_CLIENTE",
      "CorrelationID": "123456789",
      "ProcessingServer": "SERVER01"
    }
  },
  "WSRequestBody": {
    "Contact": {
      "Document_Number": "12345678",
      "Document_Type": "CC",
      "Email_Contact": "usuario@ejemplo.com",
      "Phone_Contact": "3001234567",
      "Name_Contact": "Juan Pérez"
    },
    "Num_PQR": "PQR2024001",
    "Validation_Code_Email": {
      "Code_System": "ABC123",
      "Code_User": "ABC123"
    },
    "Validation_Code_SMS": {
      "Code_System": "XYZ789",
      "Code_User": "XYZ789"
    },
    "Token": "TOKEN_VALIDACION_123456"
  }
}

Respuesta de error

json

{
  "WSResponseHeader": {
    "System": {
      "Name": "SISTEMA_CLIENTE",
      "CorrelationID": "123456789",
      "ProcessingServer": "SERVER01"
    },
    "Service": {
      "Status": "ERROR",
      "ResponseDate": "2024-12-19T10:30:00",
      "ProcessingServer": "SERVER01",
      "StatusDetail": [
        {
          "ErrorCode": "ERROR_10",
          "ErrorMessage": "El número de teléfono no es válido",
          "ErrorDetail": "El número de teléfono no es válido"
        }
      ]
    }
  }
}

Diagramas Técnicos

3.1 Flujo de datos

mermaid

graph TD
  A[Recepción de la solicitud] --> B[NotificationsController]
  B --> C[NotificationsBusiness]
  C --> D[Validación de datos]
  D --> E[Consulta PQR]
  E --> F[Consulta Cliente]
  F --> G[Consulta Contacto]
  G --> H{¿Token presente?}
  H -->|No| I[Generar códigos de validación]
  H -->|Sí| J[Validar códigos]
  I --> K[Enviar códigos por email/SMS]
  J --> L[Actualizar datos de contacto]
  K --> M[Respuesta con códigos]
  L --> N[Respuesta de actualización]

3.2 Arquitectura de clases

mermaid

classDiagram
  class NotificationsController {
    +UpdateContactPQR_v1()
  }
  class NotificationsBusiness {
    +UpdateContactPQR_v1()
  }
  class PQRUtil {
    +GenerateValidationCode_UpdateContact()
    +ValidationCode_UpdateContact()
    +Update_Contact_ETA()
  }
  class CustomerUtil {
    +Get()
    +Get_Contact()
    +Update_Contact()
  }
  class ResponsysServiceClient {
    +ValidaCorreo()
  }
  NotificationsController --> NotificationsBusiness
  NotificationsBusiness --> PQRUtil
  NotificationsBusiness --> CustomerUtil
  NotificationsBusiness --> ResponsysServiceClient

3.3 Secuencia de ejecución

mermaid

sequenceDiagram
  participant Cliente
  participant NotificationsController
  participant NotificationsBusiness
  participant PQRUtil
  participant CustomerUtil
  participant ResponsysServiceClient
  
  Cliente->>NotificationsController: Solicitud POST
  NotificationsController->>NotificationsBusiness: UpdateContactPQR_v1()
  NotificationsBusiness->>NotificationsBusiness: Validar datos de entrada
  NotificationsBusiness->>PQRUtil: Consultar PQR
  NotificationsBusiness->>CustomerUtil: Consultar Cliente
  NotificationsBusiness->>CustomerUtil: Consultar Contacto
  
  alt Primer momento (sin token)
    NotificationsBusiness->>PQRUtil: Generar códigos de validación
    NotificationsBusiness->>ResponsysServiceClient: Validar correo
    NotificationsBusiness-->>Cliente: Respuesta con códigos
  else Segundo momento (con token)
    NotificationsBusiness->>PQRUtil: Validar códigos
    NotificationsBusiness->>CustomerUtil: Actualizar contacto
    NotificationsBusiness->>PQRUtil: Actualizar PQR
    NotificationsBusiness-->>Cliente: Respuesta de actualización
  end

Políticas y Consideraciones

Políticas de seguridad

Mecanismos de autenticación y autorización:

Autenticación mediante token Bearer en header Authorization
Validación de origen de la petición mediante configuración
Auditoría completa de todas las transacciones

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)
Validación de existencia de PQR y cliente
Validación de códigos de verificación

Límites de tasa (rate limits):

Configuración por origen de petición
Control de frecuencia de generación de códigos
Validación de intentos de actualización

SLAs aplicables:

Tiempo de respuesta máximo: 30 segundos
Disponibilidad: 99.9%
Tolerancia a fallos: Configuración por endpoint

Recomendaciones y mejores prácticas

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

Implementar cache para consultas frecuentes de PQR y cliente
Agregar validación de formato de correo más robusta
Implementar rate limiting más granular
Mejorar manejo de errores con códigos más específicos

Optimizaciones posibles:

Paralelizar consultas de PQR, cliente y contacto
Implementar batch processing para múltiples actualizaciones
Optimizar consultas a base de datos con índices apropiados
Implementar circuit breaker para servicios externos

Consideraciones de mantenimiento importantes:

Monitoreo de performance de generación de códigos
Auditoría de intentos fallidos de validación
Backup y recuperación de datos de códigos de validación
Actualización de configuraciones de seguridad

Sugerencias de seguridad aplicables:

Implementar encriptación de códigos de validación
Agregar validación de IP para prevenir ataques
Implementar timeout para códigos de validación
Agregar logging de seguridad para auditoría

Actualización de Contacto PQR - notifications-v1-updatecontactpqr ​

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 ​

Estructura de Contact ​

Estructura de Validation_Code_Email ​

Estructura de Validation_Code_SMS ​

Respuesta esperada (Response) ​

Headers ​

Body ​

Estructura de WSResponseHeader ​

Estructura de WSResponseHeader.System ​

Estructura de WSResponseHeader.Service ​

Estructura de WSResponseHeader.Property ​

Estructura de Validation_Code_Email ​

Estructura de Validation_Code_SMS ​

Manejo de errores ​

Análisis de Componentes ​

Modelos y componentes ​

Ejemplos de Request/Response ​

Solicitud (request) - Primer momento (Generación de códigos) ​

Respuesta exitosa - Primer momento ​

Solicitud (request) - Segundo momento (Validación y actualización) ​

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 ​

Actualización de Contacto PQR - notifications-v1-updatecontactpqr

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

Estructura de Contact

Estructura de Validation_Code_Email

Estructura de Validation_Code_SMS

Respuesta esperada (Response)

Headers

Body

Estructura de WSResponseHeader

Estructura de WSResponseHeader.System

Estructura de WSResponseHeader.Service

Estructura de WSResponseHeader.Property

Estructura de Validation_Code_Email

Estructura de Validation_Code_SMS

Manejo de errores

Análisis de Componentes

Modelos y componentes

Ejemplos de Request/Response

Solicitud (request) - Primer momento (Generación de códigos)

Respuesta exitosa - Primer momento

Solicitud (request) - Segundo momento (Validación y actualización)

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