Actualización de PQR - pqr-v1-update

Información del Servicio

Endpoint: /api/pqr/v1/update
Método: POST
Versión: 1.0.0
Categoría: Gestión de PQRs

Documentación del Servicio

Descripción general

El servicio pqr-v1-update es un endpoint para actualizar PQRs según su estado y condiciones específicas. Este servicio permite actualizar información de PQRs existentes con diferentes comportamientos según el estado actual de la PQR.

Categoría de negocio: Gestión de PQRs y atención al cliente.

Casos de uso principales:

Actualización de PQRs cerradas (solo solución y fecha de solución)
Cierre de PQRs en estado "Enviado a Segundo Nivel" con agenda activa
Actualización de datos de contacto para PQRs de falla técnica
Modificación de estados y descripciones de PQRs

Especificación técnica

Endpoint completo: /api/pqr/v1/update
Método HTTP: POST
Capas involucradas:
- Controlador: PQRController
- Lógica de negocio: PQRBusiness
- Acceso a datos: PQRUtil, ConfigurationUtil

Flujo de procesamiento:

Validación de autenticación y autorización
Conversión y validación de datos de entrada
Obtención del origen de la petición
Verificación del estado de la API
Consulta y validación de la PQR
Procesamiento según el estado de la PQR
Actualización de datos según las reglas de negocio
Generación de respuesta con estado de ejecución

Dependencias principales:

PQRUtil para consultas de PQRs
ConfigurationUtil para configuraciones del sistema
AuditUtil para auditoría de transacciones
Utilidades de validación y conversión de datos

Consideraciones de seguridad:

Autenticación requerida mediante [Authorize]
Validación de origen de la petición
Auditoría completa de transacciones
Validación de permisos y estados

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
Agenda_Decision	string	No	Decisión de Agendamiento
Audit	object	No	Auditoria de la aplicación
Contact	object	No	Contacto de la PQR
PQR_Number	string	Sí	Numero de Identificación de la PQR
Result	string	No	Descripcion de La PQR a modificar
State	string	No	Estado de la PQR

Estructura de objetos anidados:

Estructura de WSRequestHeader

Campo	Tipo	Obligatorio	Descripción
System	object	No	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	No	Tipo de identificación del contacto existente o del nuevo contacto asociado a la PQR
Document_Type	string	No	Tipo de identificación del contacto existente o del nuevo contacto asociado a la PQR
Email	string	No	Correo electrónico de contacto. Este correo electrónico será validado
Phone	string	No	Número de conexión de contacto. Este número de teléfono debe tener 10 dígitos e iniciar por 3

Respuesta esperada (Response)

Headers

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

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	Error en la conversión de datos de entrada	"El request es nulo"
ERROR_07	PQR inactiva o no válida	"La PQR no está activa"
TIPOLOGIA_ENDPOINT_OFF	API deshabilitada	"El servicio no está disponible"

Análisis de Componentes

Modelos y componentes

Modelos base utilizados:

BaseRequestUpdatePQR: Modelo de petición principal
UpdatePQRRequest: Cuerpo de la petición con campos específicos
BaseResponseUpdatePQR: Modelo de respuesta
UpdatePQRContactRequest: Modelo para actualización de contactos

Utilidades y servicios comunes:

PQRUtil: Utilidades para gestión de PQRs
ConfigurationUtil: Utilidades de configuración del sistema
AuditUtil: Utilidades de auditoría

Patrones de diseño implementados:

Singleton pattern en PQRBusiness
Factory pattern para creación de respuestas
Strategy pattern para diferentes tipos de actualización

Componentes reutilizados:

BotBaseRequestHeader: Cabecera base para peticiones
BotBaseResponseHeader: Cabecera base para respuestas
Audit: Modelo de auditoría estándar

Referencias cruzadas:

PQRController: Controlador principal
PQRBusiness: Lógica de negocio
PQRUtil: Acceso a datos

Ejemplos de Request/Response

Solicitud (request)

json

{
  "WSRequestHeader": {
    "System": {
      "Name": "SISTEMA_CLIENTE",
      "CorrelationID": "CORR-001-2024",
      "ProcessingServer": "SRV-001"
    },
    "Property": [
      {
        "Name": "NUM_ORDEN",
        "Value": "ORD-123456"
      }
    ]
  },
  "WSRequestBody": {
    "PQR_Number": "PQR-2024-001",
    "State": "CERRADA",
    "Result": "Problema resuelto satisfactoriamente",
    "Audit": {
      "Canal": "WEB",
      "IP_Address": "192.168.1.100",
      "Id_Device": "DEVICE-001"
    },
    "Contact": {
      "Document_Number": "12345678",
      "Document_Type": "CC",
      "Email": "cliente@ejemplo.com",
      "Phone": "3001234567"
    }
  }
}

Respuesta exitosa

json

{
  "WSResponseHeader": {
    "System": {
      "name": "MAX",
      "correlationID": "LUZ-0.17537218292273005",
      "processingServer": null
    },
    "Service": {
      "status": "OK",
      "responseDate": "2025-07-31T02:39:01.3817374Z",
      "processingServer": null,
      "statusDetail": [
        {
          "errorCode": "OK_01",
          "errorDetailCode": "La solicitud LUZ-0.5970594921401777 fue exitosa",
          "errorMessage": "La solicitud fue exitosa",
          "errorMessageUser": null
        }
      ]
    },
    "Property": [
      {
        "name": null,
        "value": null
      },
      {
        "name": null,
        "value": null
      }
    ]
  }
}

Respuesta de error

json

{
  "WSResponseHeader": {
    "System": {
      "Name": "SISTEMA_CLIENTE",
      "CorrelationID": "CORR-001-2024",
      "ProcessingServer": "SRV-001"
    },
    "Service": {
      "Status": "FAIL",
      "ResponseDate": "2024-12-19T10:30:00",
      "ProcessingServer": "SRV-001",
      "StatusDetail": [
        {
          "ErrorCode": "ERROR_07",
          "ErrorMessage": "La PQR no está activa",
          "ErrorMessageUser": "La PQR no está activa"
        }
      ]
    },
    "Property": [
      {
        "Name": "NUM_ORDEN",
        "Value": "ORD-123456"
      }
    ]
  }
}

Diagramas Técnicos

3.1 Flujo de datos

mermaid

graph TD
  A[Recepción de la solicitud] --> B[PQRController]
  B --> C[PQRBusiness.Update_v1]
  C --> D[Validación de datos]
  D --> E[Consulta de PQR]
  E --> F[Validación de estado]
  F --> G[Procesamiento según estado]
  G --> H[Actualización de datos]
  H --> I[Generación de respuesta]
  I --> J[Auditoría de salida]

3.2 Arquitectura de clases

mermaid

classDiagram
  class PQRController {
    +Update_v1(BaseRequestUpdatePQR)
  }
  class PQRBusiness {
    +Update_v1(BaseRequest, string)
  }
  class PQRUtil {
    +Get_By_Id(string)
    +Is_Active(PQRModel)
  }
  class ConfigurationUtil {
    +Get_Origin(BaseRequest, Audit, string)
    +Is_Api_Turned_On(RequestModel, string)
  }
  PQRController --> PQRBusiness
  PQRBusiness --> PQRUtil
  PQRBusiness --> ConfigurationUtil

3.3 Secuencia de ejecución

mermaid

sequenceDiagram
  participant Cliente
  participant PQRController
  participant PQRBusiness
  participant PQRUtil
  participant ConfigurationUtil
  participant AuditUtil
  
  Cliente->>PQRController: POST /api/pqr/v1/update
  PQRController->>PQRBusiness: Update_v1(request)
  PQRBusiness->>AuditUtil: Save_Request()
  PQRBusiness->>ConfigurationUtil: Get_Origin()
  PQRBusiness->>ConfigurationUtil: Is_Api_Turned_On()
  PQRBusiness->>PQRUtil: Get_By_Id()
  PQRBusiness->>PQRUtil: Is_Active()
  PQRBusiness->>AuditUtil: Save_Response()
  PQRBusiness-->>PQRController: BaseResponseUpdatePQR
  PQRController-->>Cliente: Respuesta

Políticas y Consideraciones

Políticas de seguridad

Mecanismos de autenticación y autorización:

Autenticación requerida mediante [Authorize]
Validación de origen de la petición
Auditoría completa de transacciones

Validaciones de seguridad implementadas:

Validación de datos de entrada
Verificación de estados de PQR
Control de acceso por configuración

Límites de tasa (rate limits):

Controlado por configuración del sistema
Validación de origen de peticiones

SLAs aplicables:

Tiempo de respuesta: < 5 segundos
Disponibilidad: 99.9%

Recomendaciones y mejores prácticas

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

Implementar validaciones más robustas en el controlador
Agregar logging detallado para debugging
Mejorar el manejo de excepciones específicas

Optimizaciones posibles:

Implementar cache para configuraciones frecuentes
Optimizar consultas a base de datos
Agregar métricas de rendimiento

Consideraciones de mantenimiento importantes:

Mantener actualizadas las configuraciones de tipologías
Revisar regularmente los logs de auditoría
Monitorear el rendimiento del servicio

Sugerencias de seguridad aplicables:

Implementar rate limiting más granular
Agregar validación de tokens JWT
Implementar encriptación de datos sensibles

Actualización de PQR - pqr-v1-update ​

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 ​

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 ​

Actualización de PQR - pqr-v1-update

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

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