Catálogo APIs

Appearance

Consulta de Agendas Disponibles - pqr-v2-agendaavailable ​

Información del Servicio

Endpoint: /api/pqr/v2/agendaavailable
Método: POST
Versión: v2
Categoría: Gestión de PQRs

Documentación del Servicio ​

Descripción general ​

El servicio pqr-v2-agendaavailable es un endpoint para consultar las agendas disponibles por el número de conexión sin depender de la creación de una PQR. Este servicio permite consultar la disponibilidad de cupos en ETA enviando las fechas a consultar (en formato yyyy-MM-dd) y el producto. En caso de enviar el número de la PQR, se consultará la agenda disponible para esa PQR específica.

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

Casos de uso principales:

  • Consulta de disponibilidad de agendas por número de conexión
  • Consulta de disponibilidad de agendas por PQR específica
  • Validación de cupos disponibles en ETA
  • Consulta por tipología de PQR (causal, clase, motivo, síntoma)

Especificación técnica ​

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

Flujo de procesamiento:

  1. Validación de auditoría de entrada
  2. Conversión y validación de datos de entrada
  3. Obtención del origen de la petición
  4. Validación de estado de la API
  5. Consulta por número de PQR o por filtros
  6. Consulta de información del cliente y servicio
  7. Consulta de agendas disponibles
  8. Generación de respuesta

Dependencias principales:

  • AuditUtil para auditoría
  • ConfigurationUtil para configuración
  • PQRUtil para gestión de PQRs
  • CustomerUtil para información de clientes

Consideraciones de seguridad:

  • Validación de autenticación SOAP
  • Auditoría completa de peticiones
  • Validación de origen de petición
  • Control de acceso por configuración

Parámetros de entrada (Request) ​

Headers ​

CampoTipoObligatorioDescripción
WSRequestHeaderobjectSíCabecera de la petición con información del sistema

Body ​

CampoTipoObligatorioDescripción
AuditobjectNoAuditoría de la aplicación
CausalstringNo*Este campo representa el causal de la PQR. Debe ser enviado junto al motivo, clase y síntoma de la PQR
ClassstringNo*Este campo representa la clase de la PQR. Debe ser enviado junto al motivo, causal y síntoma de la PQR
FailurestringNoFalla del bot petición. En caso de enviar este campo, no será tenido en cuenta el causal, síntoma, motivo ni clase
Filter_DatearrayNoFechas a consultar disponibilidad en ETA con formato yyyy-MM-dd
Id_PQRstringNo*Número de la PQR. Si se envía no se tendrán en cuenta los demás campos. Se consultará la disponibilidad del cupo para esa PQR
PhonestringNoNúmero de Conexión
ProductstringNoProducto instalado del servicio del cliente
ReasonstringNo*Este campo representa el motivo de la PQR. Debe ser enviado junto a la clase, causal y síntoma de la PQR
SymptomstringNo*Este campo representa el síntoma de la PQR. Debe ser enviado junto a la clase, causal y motivo de la PQR

Estructura de objetos anidados:

Estructura de WSRequestHeader ​

CampoTipoObligatorioDescripción
SystemobjectNoInformación asociada al sistema
PropertyarrayNoPropiedades asociadas al consumo del servicio web

Estructura de WSRequestHeader.System ​

CampoTipoObligatorioDescripción
NamestringSíNombre del sistema
CorrelationIDstringSíIdentificador de la petición
ProcessingServerstringSíServidor de procesamiento del sistema

Estructura de WSRequestHeader.Property ​

CampoTipoObligatorioDescripción
NamestringSíNombre de la propiedad
ValuestringSíValor de la propiedad

Estructura de Audit ​

CampoTipoObligatorioDescripción
CanalstringNoCanal sobre el cual se hizo la petición
Id_DevicestringNoIdentificador del dispositivo móvil
SOstringNoSistema operativo del dispositivo
IP_AddressstringNoDirección IP desde donde se realiza la petición
WhatsApp_Phone_NumberstringNoNúmero de WhatsApp desde donde se realiza la petición

Respuesta esperada (Response) ​

Headers ​

CampoTipoObligatorioDescripción
WSResponseHeaderobjectSíCabecera de la respuesta con información del sistema

Body ​

CampoTipoObligatorioDescripción
AgendasarrayNoLista de agendas disponibles
CountintNoNúmero total de agendas disponibles

Estructura de objetos anidados:

Estructura de WSResponseHeader ​

CampoTipoObligatorioDescripción
SystemobjectNoInformación asociada al sistema
ServiceobjectNoInformación asociada a la ejecución del servicio
PropertyarrayNoArreglo de propiedades asociado al servicio

Estructura de WSResponseHeader.System ​

CampoTipoObligatorioDescripción
NamestringNoNombre del sistema
CorrelationIDstringNoIdentificador de la petición
ProcessingServerstringNoServidor de procesamiento del sistema

Estructura de WSResponseHeader.Service ​

CampoTipoObligatorioDescripción
StatusstringNoEstado de la ejecución del servicio web
ResponseDateDateTimeNoFecha de la respuesta
ProcessingServerstringNoServidor de procesamiento de la solicitud
StatusDetailarrayNoDetalle del procesamiento de la solicitud

Estructura de WSResponseHeader.Property ​

CampoTipoObligatorioDescripción
NamestringNoNombre de la propiedad
ValuestringNoValor de la propiedad

Estructura de Agendas ​

CampoTipoObligatorioDescripción
Id_ETAstringNoIdentificador en ETA
DurationstringNoDuración de la agenda
Order_NumberstringNoNúmero de la PQR
Query_DatestringNoFecha de la agenda
SkillstringNoSkill
TimeslotstringNoFranja horaria técnica
Timeslot_UserstringNoFranja horaria a mostrar al usuario final
ZonestringNoZona de la locación del cliente

Manejo de errores ​

CódigoDescripciónEjemplo
ERROR_04El request es nuloError en la conversión de datos de entrada
ERROR_05PQR no encontrada o inactivaLa PQR especificada no existe o no está activa
ERROR_06Cliente no encontradoNo se pudo obtener información del cliente
ERROR_07Servicio no encontradoNo se pudo obtener información del servicio
ERROR_08No hay agendas disponiblesNo se encontraron agendas disponibles para los criterios especificados

Análisis de Componentes ​

Modelos y componentes ​

Modelos base utilizados:

  • BaseRequestAgendaAvailableV2
  • BaseResponseAgendaAvailableV2
  • AgendaAvailableRequest_v2
  • AgendaAvailableResponse_v2
  • AgendaAvailableItemResponse_v2

Utilidades y servicios comunes:

  • AuditUtil para auditoría
  • ConfigurationUtil para configuración
  • PQRUtil para gestión de PQRs
  • CustomerUtil para información de clientes

Patrones de diseño implementados:

  • Singleton para instancias de negocio
  • Factory para creación de respuestas
  • Strategy para diferentes tipos de consulta

Componentes reutilizados:

  • BotBaseRequestHeader/ResponseHeader
  • Audit para auditoría
  • ResultModel para manejo de errores

Referencias cruzadas:

  • PQRController para endpoint REST
  • PQR.asmx para endpoint SOAP
  • PQRBusiness para lógica de negocio

Ejemplos de Request/Response ​

Solicitud (request) ​

json
{
    "WSRequestHeader": {
        "System": {
            "name": "Kioskos",
            "correlationID": "Kioskos-21062022-20451",
            "processingServer": null
        },
        "Property": []
    },
    "WSRequestBody": {
        "Audit": {
            "Canal": "web",
            "Id_Device": null,
            "SO": null,
            "IP_Address": null,
            "IP_Latitude": null,
            "IP_Longitude": null,
            "WhatsApp_Phone_Number": null,
            "Facebook_User": null
        },
        "Causal": "FALLA_TECNICA",
        "Class": "INTERNET",
        "Failure": null,
        "Filter_Date": ["2024-12-20", "2024-12-21"],
        "Id_PQR": "MDM-PQR-4085967",
        "Phone": null,
        "Product": null,
        "Reason": "SIN_SERVICIO",
        "Symptom": "SIN_CONECTIVIDAD"
    }
}

Respuesta exitosa ​

json
{
  "WSRequestHeader": {
    "System": {
      "name": "MAX",
      "correlationID": "LUZ-0.5656121512688825",
      "processingServer": null
    },
    "Property": []
  },
  "WSRequestBody": {
    "Filter_Date": [
      "2025-07-31",
      "2025-08-01",
      "2025-08-02",
      "2025-08-03",
      "2025-08-04",
      "2025-08-05",
      "2025-08-06"
    ],
    "Id_PQR": "",
    "Phone": "6012937005",
    "Product": "Internet",
    "Failure": "Parámetros mal_Internet_FO",
    "Audit": {
      "Canal": "whatsapp",
      "Date": "2025-07-31",
      "Hour": "01:04:13"
    }
  }
}

Respuesta de error ​

json
{
  "WSResponseHeader": {
    "System": {
      "name": "MAX",
      "correlationID": "LUZ-0.5656121512688825",
      "processingServer": null
    },
    "Service": {
      "status": "OK",
      "responseDate": "2025-07-31T01:04:14.7740457Z",
      "processingServer": null,
      "statusDetail": [
        {
          "errorCode": "OK_01",
          "errorDetailCode": "La solicitud LUZ-0.4257861330708129 fue exitosa",
          "errorMessage": "La solicitud fue exitosa",
          "errorMessageUser": null
        }
      ]
    },
    "Property": []
  },
  "WSResponseBody": {
    "Agendas": [
      {
        "Id_ETA": null,
        "Duration": "120",
        "Order_Number": null,
        "Query_Date": "2025-08-02",
        "Skill": "ASEGFTTH_Plata",
        "Timeslot": "AM2 - 08:00 10:00",
        "Timeslot_User": "08:00 - 10:00",
        "Zone": "HOLANDA"
      },
      {
        "Id_ETA": null,
        "Duration": "120",
        "Order_Number": null,
        "Query_Date": "2025-08-02",
        "Skill": "ASEGFTTH_Plata",
        "Timeslot": "AM3 - 10:00 12:00",
        "Timeslot_User": "10:00 - 12:00",
        "Zone": "HOLANDA"
      },
      {
        "Id_ETA": null,
        "Duration": "120",
        "Order_Number": null,
        "Query_Date": "2025-08-02",
        "Skill": "ASEGFTTH_Plata",
        "Timeslot": "PM1 - 13:00 15:00",
        "Timeslot_User": "13:00 - 15:00",
        "Zone": "HOLANDA"
      },
      {
        "Id_ETA": null,
        "Duration": "120",
        "Order_Number": null,
        "Query_Date": "2025-08-02",
        "Skill": "ASEGFTTH_Plata",
        "Timeslot": "PM2 - 15:00 17:00",
        "Timeslot_User": "15:00 - 17:00",
        "Zone": "HOLANDA"
      },
      {
        "Id_ETA": null,
        "Duration": "120",
        "Order_Number": null,
        "Query_Date": "2025-08-01",
        "Skill": "ASEGFTTH_Plata",
        "Timeslot": "AM2 - 08:00 10:00",
        "Timeslot_User": "08:00 - 10:00",
        "Zone": "HOLANDA"
      },
      {
        "Id_ETA": null,
        "Duration": "120",
        "Order_Number": null,
        "Query_Date": "2025-08-01",
        "Skill": "ASEGFTTH_Plata",
        "Timeslot": "AM3 - 10:00 12:00",
        "Timeslot_User": "10:00 - 12:00",
        "Zone": "HOLANDA"
      },
      {
        "Id_ETA": null,
        "Duration": "120",
        "Order_Number": null,
        "Query_Date": "2025-08-01",
        "Skill": "ASEGFTTH_Plata",
        "Timeslot": "PM1 - 13:00 15:00",
        "Timeslot_User": "13:00 - 15:00",
        "Zone": "HOLANDA"
      },
      {
        "Id_ETA": null,
        "Duration": "120",
        "Order_Number": null,
        "Query_Date": "2025-08-01",
        "Skill": "ASEGFTTH_Plata",
        "Timeslot": "PM2 - 15:00 17:00",
        "Timeslot_User": "15:00 - 17:00",
        "Zone": "HOLANDA"
      }
    ],
    "Count": 8
  }
}

Diagramas Técnicos ​

3.1 Flujo de datos ​

mermaid
graph TD
    A[Recepción de la solicitud] --> B[PQRController]
    B --> C[PQRBusiness.AgendaAvailable_v2]
    C --> D[AuditUtil.Save_Request]
    C --> E[Conversión de datos]
    E --> F[ConfigurationUtil.Get_Origin]
    F --> G[Validación API]
    G --> H[Consulta PQR/Cliente]
    H --> I[Consulta Agendas]
    I --> J[Generación Respuesta]
    J --> K[AuditUtil.Save_Response]

3.2 Arquitectura de clases ​

mermaid
classDiagram
    class PQRController {
        +AgendaAvailable_v2()
    }
    class PQRBusiness {
        +AgendaAvailable_v2()
    }
    class PQRUtil {
        +Get_By_Id()
        +Is_Active()
    }
    class ConfigurationUtil {
        +Get_Origin()
        +Is_Api_Turned_On()
    }
    class AuditUtil {
        +Save_Request()
        +Save_Response()
    }
    PQRController --> PQRBusiness
    PQRBusiness --> PQRUtil
    PQRBusiness --> ConfigurationUtil
    PQRBusiness --> AuditUtil

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/v2/agendaavailable
    PQRController->>PQRBusiness: AgendaAvailable_v2()
    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: BaseResponseAgendaAvailableV2
    PQRController-->>Cliente: Respuesta JSON

Políticas y Consideraciones ​

Políticas de seguridad ​

Mecanismos de autenticación y autorización:

  • Validación de autenticación SOAP para endpoints SOAP
  • Auditoría completa de todas las peticiones
  • Validación de origen de petición

Validaciones de seguridad implementadas:

  • Validación de datos de entrada
  • Control de acceso por configuración de API
  • Validación de PQRs activas

Límites de tasa (rate limits):

  • Control por configuración de API
  • Auditoría de consumo por sistema

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:

  1. Implementar cache para consultas frecuentes de configuración
  2. Optimizar consultas a base de datos MongoDB
  3. Implementar circuit breaker para servicios externos

Optimizaciones posibles:

  1. Paralelizar consultas de cliente y servicio
  2. Implementar paginación para grandes volúmenes de agendas
  3. Cache de agendas disponibles por zona y fecha

Consideraciones de mantenimiento importantes:

  1. Monitoreo de performance de consultas ETA
  2. Validación periódica de configuraciones
  3. Backup y recuperación de datos de auditoría

Sugerencias de seguridad aplicables:

  1. Implementar rate limiting por IP
  2. Validación de tokens JWT para endpoints REST
  3. Encriptación de datos sensibles en auditoría