Agendamiento de PQR - pqr-v2-agenda

Información del Servicio

Endpoint: /api/pqr/v2/agenda
Método: POST
Versión: v2
Categoría: PQR - Agendamiento

Documentación del Servicio

Descripción general

El servicio pqr-v2-agenda es un endpoint para agendar una visita técnica a partir de una PQR previamente creada. Este servicio permite crear una agenda con una PQR existente, especificando la fecha, duración y franja horaria de la visita técnica.

Categoría de negocio: Gestión de PQRs y Agendamiento.

Casos de uso principales:

Agendamiento de visitas técnicas para PQRs existentes
Programación de citas de servicio técnico
Gestión de agenda de técnicos de campo

Especificación técnica

Endpoint completo: /api/pqr/v2/agenda
Método HTTP: POST
Capas involucradas:
- Controlador: PQRController.Agenda_v2()
- Lógica de negocio: PQRBusiness.Agenda_v2()
- Acceso a datos: PQRUtil, AgendaUtil

Flujo de procesamiento:

Validación de la petición y auditoría de entrada
Conversión de datos de entrada
Consulta de la PQR existente
Validación de la PQR y sus datos asociados
Creación de la agenda en ETA (Enterprise Technical Appointment)
Actualización de la PQR con información de la agenda
Auditoría de salida y respuesta

Dependencias principales:

PQRUtil para consulta de PQRs
AgendaUtil para gestión de agendas
CustomerUtil para validación de clientes
ServiceUtil para consulta de servicios

Consideraciones de seguridad:

Autenticación requerida mediante [Authorize]
Validación de usuario asociado al servicio
Auditoría completa de transacciones
Validación de titularidad del servicio

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
Date	string	Sí	Fecha de la visita técnica (formato: yyyy-MM-dd)
Duration	string	Sí	Duración de la visita técnica obtenida de la consulta a ETA
Id_PQR	string	Sí	Número de la PQR
Timeslot	string	Sí	Franja horaria de la visita técnica obtenida de la consulta a ETA

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	No	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

Body

Campo	Tipo	Obligatorio	Descripción
Causal	string	No	Causal de la PQR
Contact_Document_Number	string	No	Número de identificación del contacto
Contact_Document_Type	string	No	Tipo de identificación del contacto
Creation_Date	DateTime?	No	Fecha de creación de la PQR
CUN	string	No	CUN de la PQR
Description	string	No	Descripción de la PQR
Document_Number	string	No	Número de identificación del cliente
Document_Type	string	No	Tipo de identificación del cliente
Id	string	No	Número de la PQR
Id_ETA	string	No	Identificador en ETA
Id_OSM	string	No	Identificador en OSM
Kind	string	No	Clase de la PQR
Phone	string	No	Número de conexión asociado a la PQR
Reason	string	No	Razón de creación de la PQR
State	string	No	Estado de la PQR
Solution_Date	DateTime?	No	Fecha de solución de la PQR
Symptom	string	No	Síntoma de la PQR
Type	string	No	Tipo de la PQR

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_00	Excepción técnica	La solicitud no fue exitosa. Se ha generado una excepción técnica
ERROR_01	Usuario no encontrado	La solicitud no fue exitosa. No fue posible obtener el usuario asociado
ERROR_02	Origen no encontrado	La solicitud no fue exitosa. No fue posible obtener el origen
ERROR_03	Validación de petición fallida	La solicitud no fue exitosa. No fue posible validar la petición
ERROR_04	Objetos no acordes	La solicitud no fue exitosa. Fueron enviados objetos no acordes a la petición

Análisis de Componentes

Modelos y componentes

Modelos base utilizados:

BaseRequestAgenda_v2 - Modelo de petición
BaseResponseAgenda_v2 - Modelo de respuesta
AgendaRequest_v2 - Contenido de la petición
AgendaResponse_v2 - Contenido de la respuesta

Utilidades y servicios comunes:

PQRBusiness - Lógica de negocio principal
PQRUtil - Operaciones de PQRs
AgendaUtil - Gestión de agendas
AuditUtil - Auditoría de transacciones

Patrones de diseño implementados:

Singleton Pattern en PQRBusiness
Template Method en el flujo de procesamiento
Strategy Pattern para diferentes tipos de validación

Componentes reutilizados:

BotBaseRequestHeader/ResponseHeader para cabeceras estándar
Audit para auditoría
PQRModel para modelo de datos

Referencias cruzadas:

PQRController para endpoint
PQRBusiness para lógica de negocio
PQRUtil para operaciones de base de datos

Ejemplos de Request/Response

Solicitud (request)

json

{
  "WSRequestHeader": {
    "System": {
      "name": "MAX",
      "correlationID": "LUZ-0.03201327641925744",
      "processingServer": null
    },
    "Property": [
      {
        "name": null,
        "value": null
      }
    ]
  },
  "WSRequestBody": {
    "Id_PQR": "MDM-PQR-4159147",
    "Date": "2025-07-26",
    "Timeslot": "PM2",
    "Duration": "120",
    "Audit": {
      "Canal": "Whatsapp"
    }
  }
}

Respuesta exitosa

json

{
  "WSResponseHeader": {
    "System": {
      "name": "MAX",
      "correlationID": "LUZ-0.03201327641925744",
      "processingServer": null
    },
    "Service": {
      "status": "OK",
      "responseDate": "2025-07-25T12:36:38.9784777Z",
      "processingServer": null,
      "statusDetail": [
        {
          "errorCode": "OK_01",
          "errorDetailCode": "La solicitud LUZ-0.3502884354642898 fue exitosa",
          "errorMessage": "La solicitud fue exitosa",
          "errorMessageUser": null
        }
      ]
    },
    "Property": [
      {
        "name": null,
        "value": null
      }
    ]
  },
  "WSResponseBody": {
    "Causal": "FALLA INTERNET",
    "Contact_Document_Number": "99103441",
    "Contact_Document_Type": "1",
    "Creation_Date": "2025-07-25T12:36:21Z",
    "CUN": "4347250001277543",
    "Description": "Cliente reporta falla en el servicio",
    "Document_Number": "99203441",
    "Document_Type": "NIT",
    "Id": "MDM-PQR-4159147",
    "Id_ETA": "8846003",
    "Id_OSM": null,
    "Kind": "PETICION",
    "Phone": "6012728457",
    "Reason": "FALLA TECNICA",
    "State": "Enviado a Segundo Nivel",
    "Solution_Date": null,
    "Symptom": "SIN SERVICIO -F",
    "Type": "PRODUCTO"
  }
}

Respuesta de error

json

{
  "WSResponseHeader": {
    "System": {
      "name": "Kioskos",
      "correlationID": "Kioskos-21062022-20451",
      "processingServer": "SERVER01"
    },
    "Service": {
      "status": "FAIL",
      "responseDate": "2022-06-21T20:45:00",
      "processingServer": "SERVER01",
      "statusDetail": [
        {
          "errorCode": "ERROR_03",
          "errorMessage": "La solicitud Kioskos-21062022-20451 no fue exitosa. No fue posible validar la petición",
          "errorDetailCode": "ERROR_03",
          "errorMessageUser": "Error en la validación de la petición"
        }
      ]
    },
    "Property": []
  },
  "WSResponseBody": null
}

Diagramas Técnicos

3.1 Flujo de datos

mermaid

graph TD
  A[Recepción de la solicitud] --> B[PQRController.Agenda_v2]
  B --> C[PQRBusiness.Agenda_v2]
  C --> D[Auditoría de entrada]
  D --> E[Conversión de datos]
  E --> F[Consulta PQR existente]
  F --> G[Validación de PQR]
  G --> H[Creación agenda en ETA]
  H --> I[Actualización PQR]
  I --> J[Auditoría de salida]
  J --> K[Respuesta al cliente]

3.2 Arquitectura de clases

mermaid

classDiagram
  class PQRController {
    +Agenda_v2(BaseRequestAgenda_v2)
  }
  class PQRBusiness {
    +Agenda_v2(BaseRequest, string)
  }
  class PQRUtil {
    +GetBasicById(string)
  }
  class AgendaUtil {
    +CreateAgenda(AgendaModel)
  }
  class AuditUtil {
    +Save_Request(BaseRequest, string, bool)
  }
  PQRController --> PQRBusiness
  PQRBusiness --> PQRUtil
  PQRBusiness --> AgendaUtil
  PQRBusiness --> AuditUtil

3.3 Secuencia de ejecución

mermaid

sequenceDiagram
  participant Cliente
  participant PQRController
  participant PQRBusiness
  participant PQRUtil
  participant AgendaUtil
  participant AuditUtil
  Cliente->>PQRController: POST /api/pqr/v2/agenda
  PQRController->>PQRBusiness: Agenda_v2(request, name)
  PQRBusiness->>AuditUtil: Save_Request()
  PQRBusiness->>PQRUtil: GetBasicById(Id_PQR)
  PQRUtil-->>PQRBusiness: PQRModel
  PQRBusiness->>AgendaUtil: CreateAgenda(agenda)
  AgendaUtil-->>PQRBusiness: Result
  PQRBusiness->>AuditUtil: Save_Response()
  PQRBusiness-->>PQRController: BaseResponseAgenda_v2
  PQRController-->>Cliente: Response

Políticas y Consideraciones

Políticas de seguridad

Mecanismos de autenticación y autorización:

Autenticación mediante token Bearer
Validación de usuario asociado al servicio
Verificación de titularidad del servicio

Validaciones de seguridad implementadas:

Validación de formato de fecha (yyyy-MM-dd)
Validación de duración de visita técnica
Validación de franja horaria válida
Validación de existencia de PQR

Límites de tasa (rate limits):

No se especifican límites específicos en el código
Se recomienda implementar rate limiting por IP/usuario

SLAs aplicables:

Tiempo de respuesta esperado: < 5 segundos
Disponibilidad: 99.9%

Recomendaciones y mejores prácticas

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

Implementar validación más robusta de fechas y horarios
Agregar logging detallado para debugging
Implementar retry logic para fallos de ETA
Agregar métricas de performance

Optimizaciones posibles:

Cache de configuraciones de agenda
Validación asíncrona de disponibilidad
Implementar circuit breaker para ETA
Optimizar consultas a base de datos

Consideraciones de mantenimiento importantes:

Monitoreo de integración con ETA
Validación periódica de tipologías de PQR
Backup de configuraciones de agenda
Documentación de cambios en ETA

Sugerencias de seguridad aplicables:

Implementar rate limiting
Agregar validación de IP whitelist
Implementar audit trail completo
Validar formato de datos de entrada

Agendamiento de PQR - pqr-v2-agenda ​

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 ​

Agendamiento de PQR - pqr-v2-agenda

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