Catálogo APIs

Appearance

Consulta de Agenda Disponible para Órdenes - orders-v2-agendaavailable ​

Información del Servicio

Endpoint: /api/orders/v2/agendaavailable
Método: POST
Versión: 2.0.0
Categoría: Gestión de Órdenes

Documentación del Servicio ​

Descripción general ​

El servicio orders-v2-agendaavailable es un endpoint para consultar las fechas y franjas horarias disponibles para el agendamiento de una orden de servicio fijo. Este servicio permite obtener la agenda disponible para una orden específica, devolviendo las fechas y horarios en los que se puede programar la visita técnica.

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

Casos de uso principales:

  • Consulta de disponibilidad de agenda para órdenes de instalación
  • Consulta de horarios disponibles para reprogramación de visitas técnicas
  • Validación de fechas disponibles antes de confirmar agendamiento

Especificación técnica ​

  • Endpoint completo: /api/orders/v2/agendaavailable
  • Método HTTP: POST
  • Capas involucradas:
    • Controlador: OrdersController.AgendaAvailable_v2
    • Lógica de negocio: OrderBusiness.AgendaAvailable_v2
    • Acceso a datos: Servicios de agenda y órdenes

Flujo de procesamiento:

  1. Validación de la solicitud y parámetros de entrada
  2. Consulta de la orden en el sistema
  3. Validación del estado de la orden (debe estar en agendamiento pendiente o en proceso)
  4. Consulta de fechas y franjas disponibles en el sistema de agenda
  5. Formateo y retorno de la respuesta

Dependencias principales:

  • BotBaseRequestHeader para validación de headers
  • Audit para información de auditoría
  • Sistema de gestión de órdenes
  • Sistema de agenda y disponibilidad

Consideraciones de seguridad:

  • Autenticación requerida mediante [Authorize]
  • Validación de parámetros obligatorios
  • Auditoría de todas las consultas realizadas

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
Num_OrderstringSíNúmero de la orden

Estructura de objetos anidados:

Estructura de WSRequestHeader ​

CampoTipoObligatorioDescripción
SystemobjectSíInformació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
ProcessingServerstringNoServidor 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
Agenda_AvailablearrayNoLista de agendas disponibles con fechas y franjas horarias

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.Service.StatusDetail ​

CampoTipoObligatorioDescripción
ErrorCodestringNoCódigo de error
ErrorDetailCodestringNoDetalle del código de error
ErrorMessagestringNoMensaje de error
ErrorMessageUserstringNoMensaje de error para el usuario

Estructura de WSResponseHeader.Property ​

CampoTipoObligatorioDescripción
NamestringNoNombre de la propiedad
ValuestringNoValor de la propiedad

Estructura de Agenda_Available ​

CampoTipoObligatorioDescripción
Agenda_DatestringNoFecha de la agenda en formato dd/MM/yyyy
TimeslotarrayNoFranjas horarias disponibles

Estructura de Agenda_Available.Timeslot ​

CampoTipoObligatorioDescripción
TimeslotstringNoFranja horaria
Timeslot_UserstringNoFranja horaria a mostrar al usuario

Manejo de errores ​

CódigoDescripciónEjemplo
OK_01La solicitud fue exitosaLa solicitud mietb-pruebas fue exitosa
ERROR_01Error en la validación de parámetrosEl número de orden es obligatorio
ERROR_02Orden no encontradaLa orden especificada no existe
ERROR_03Orden no está en estado válidoLa orden debe estar en agendamiento pendiente o en proceso

Análisis de Componentes ​

Modelos y componentes ​

Modelos base utilizados:

  • BaseRequestAgendaOrdersAvailable_v2
  • BaseResponseAgendaOrdersAvailable_v2
  • AgendaOrdersAvailableRequest_v2
  • AgendaOrdersAvailableResponse_v2

Utilidades y servicios comunes:

  • BotBaseRequestHeader para validación de headers
  • BotBaseResponseHeader para estructura de respuesta
  • Audit para información de auditoría

Patrones de diseño implementados:

  • Patrón Request/Response para estructura de datos
  • Patrón Factory para creación de respuestas
  • Patrón Builder para construcción de objetos complejos

Componentes reutilizados:

  • BotBaseRequestSystem para información del sistema
  • BotBaseResponseService para información del servicio
  • Audit para auditoría de transacciones

Referencias cruzadas:

  • OrdersController para gestión de órdenes
  • OrderBusiness para lógica de negocio
  • Sistema de agenda para consulta de disponibilidad

Ejemplos de Request/Response ​

Solicitud (request) ​

json
{
  "WSRequestHeader": {
    "System": {
      "name": "MAX",
      "correlationID": "LUZ-0.7081201448367586",
      "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": "6013565288",
    "Product": "Internet",
    "Failure": "Parámetros mal_Internet_FO",
    "Audit": {
      "Canal": "whatsapp",
      "Date": "2025-07-31",
      "Hour": "19:45:43"
    }
  }
}

Respuesta exitosa ​

json
{
  "WSResponseHeader": {
    "System": {
      "name": "MAX",
      "correlationID": "LUZ-0.7081201448367586",
      "processingServer": null
    },
    "Service": {
      "status": "OK",
      "responseDate": "2025-07-31T19:45:44.0108522Z",
      "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-04",
        "Skill": "ASEGFTTH_Plata",
        "Timeslot": "AM4 - 08:00 12:00",
        "Timeslot_User": "08:00 - 12:00",
        "Zone": "FONTIBON"
      },
      {
        "Id_ETA": null,
        "Duration": "120",
        "Order_Number": null,
        "Query_Date": "2025-08-04",
        "Skill": "ASEGFTTH_Plata",
        "Timeslot": "PM3 - 13:00 16:00",
        "Timeslot_User": "13:00 - 16:00",
        "Zone": "FONTIBON"
      }
    ],
    "Count": 2
  }
}

Respuesta de error ​

json
{
    "WSResponseHeader": {
        "System": {
            "name": "MIETB",
            "correlationID": "mietb-pruebas",
            "processingServer": ""
        },
        "Service": {
            "status": "ERROR",
            "responseDate": "2022-03-03T09:44:44.8834226-05:00",
            "processingServer": null,
            "statusDetail": [
                {
                    "errorCode": "ERROR_02",
                    "errorDetailCode": "Orden no encontrada",
                    "errorMessage": "La orden MDM-FIBRA-008997553 no existe en el sistema"
                }
            ]
        },
        "Property": []
    },
    "WSResponseBody": {
        "Agenda_Available": null
    }
}

Diagramas Técnicos ​

3.1 Flujo de datos ​

mermaid
graph TD
  A[Recepción de la solicitud] --> B[OrdersController.AgendaAvailable_v2]
  B --> C[Validación de parámetros]
  C --> D[OrderBusiness.AgendaAvailable_v2]
  D --> E[Consulta de orden]
  E --> F[Validación de estado]
  F --> G[Consulta de agenda disponible]
  G --> H[Formateo de respuesta]
  H --> I[Retorno de resultado]

3.2 Arquitectura de clases ​

mermaid
classDiagram
  class OrdersController {
    +AgendaAvailable_v2(BaseRequestAgendaOrdersAvailable_v2)
  }
  class OrderBusiness {
    +AgendaAvailable_v2(BaseRequest, string)
  }
  class BaseRequestAgendaOrdersAvailable_v2 {
    +WSRequestHeader
    +WSRequestBody
  }
  class BaseResponseAgendaOrdersAvailable_v2 {
    +WSResponseHeader
    +WSResponseBody
  }
  OrdersController --> OrderBusiness
  OrderBusiness --> BaseResponseAgendaOrdersAvailable_v2

3.3 Secuencia de ejecución ​

mermaid
sequenceDiagram
  participant Cliente
  participant OrdersController
  participant OrderBusiness
  participant SistemaAgenda
  participant BaseDatos
  Cliente->>OrdersController: POST /api/orders/v2/agendaavailable
  OrdersController->>OrderBusiness: AgendaAvailable_v2()
  OrderBusiness->>BaseDatos: Consultar orden
  BaseDatos-->>OrderBusiness: Datos de orden
  OrderBusiness->>SistemaAgenda: Consultar disponibilidad
  SistemaAgenda-->>OrderBusiness: Fechas y horarios disponibles
  OrderBusiness-->>OrdersController: BaseResponseAgendaOrdersAvailable_v2
  OrdersController-->>Cliente: Respuesta JSON

Políticas y Consideraciones ​

Políticas de seguridad ​

Mecanismos de autenticación y autorización:

  • Autenticación requerida mediante atributo [Authorize]
  • Validación de tokens de acceso
  • Control de acceso basado en roles

Validaciones de seguridad implementadas:

  • Validación de parámetros obligatorios
  • Sanitización de entrada de datos
  • Auditoría completa de transacciones

Límites de tasa (rate limits):

  • Máximo 100 consultas por minuto por usuario
  • Máximo 1000 consultas por hora por IP

SLAs aplicables:

  • Tiempo de respuesta máximo: 2 segundos
  • Disponibilidad del servicio: 99.9%
  • Tolerancia a fallos: 3 reintentos automáticos

Recomendaciones y mejores prácticas ​

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

  1. Implementar cache para consultas frecuentes de agenda
  2. Agregar validación de formato de fecha en el request
  3. Optimizar consultas a base de datos con índices apropiados

Optimizaciones posibles:

  1. Implementar paginación para respuestas con muchas fechas
  2. Agregar filtros por tipo de servicio en la consulta
  3. Implementar compresión de respuesta para reducir ancho de banda

Consideraciones de mantenimiento importantes:

  1. Monitoreo de performance de consultas de agenda
  2. Backup regular de configuraciones de horarios
  3. Documentación de cambios en estructura de respuesta

Sugerencias de seguridad aplicables:

  1. Implementar rate limiting más granular
  2. Agregar validación de IP para consultas críticas
  3. Implementar logging detallado para auditoría
  4. Considerar encriptación de datos sensibles en tránsito