Consulta de Órdenes de Servicios - orders-v4-get

Información del Servicio

Endpoint: /api/orders/v4/get
Método: POST Versión: v4 Categoría: Gestión de Órdenes

Documentación del Servicio

Descripción general

El servicio orders-v4-get es un endpoint para consultar órdenes de servicios de telecomunicaciones. Este servicio permite obtener información detallada de órdenes asociadas a clientes, servicios específicos, números de orden particulares o códigos CUN, con capacidades de filtrado avanzado y soporte para consultas asíncronas.

Categoría de negocio: Gestión de Órdenes de Servicios de Telecomunicaciones.

Casos de uso principales:

Consulta de órdenes por cliente (tipo y número de documento)
Consulta de órdenes por número de conexión (teléfono)
Consulta de órdenes por número de orden específico
Consulta de órdenes por CUN (Código Único de Negocio)
Filtrado de órdenes por estado, fechas y otros criterios

Especificación técnica

Endpoint completo: /api/orders/v4/get
Método HTTP: POST
Capas involucradas:
- Controlador: OrdersController
- Lógica de negocio: OrderBusiness
- Acceso a datos: OrderUtil2, ServiceUtil2

Flujo de procesamiento:

Recepción y validación de la solicitud
Auditoría de entrada
Conversión y validación de datos
Consulta de órdenes según criterios (cliente, servicio, orden específica o CUN)
Procesamiento de filtros y aplicación de reglas de negocio
Generación de respuesta con información de órdenes
Auditoría de salida

Dependencias principales:

OrderUtil2 (utilidades de órdenes)
ServiceUtil2 (utilidades de servicios)
CRUD_MDM_ORDEN (acceso a datos de órdenes)
CRUD_MDM_CD_ORDEN (acceso a datos de códigos de órdenes)

Consideraciones de seguridad:

Autenticación mediante token Bearer
Validación de headers de seguridad
Auditoría completa de transacciones
Sanitización de datos de entrada

Parámetros de entrada (Request)

Headers

Campo	Tipo	Obligatorio	Descripción
Authorization	string	Sí	Token Bearer para autenticación
Content-Type	string	Sí	application/json
X-Request-ID	string	No	Identificador único de la solicitud

Body

Campo	Tipo	Obligatorio	Descripción
WSRequestHeader	object	Sí	Cabecera de la petición con información del sistema
WSRequestBody	object	Sí	Cuerpo de la petición con parámetros de consulta

Estructura de objetos anidados:

Estructura de WSRequestHeader

Campo	Tipo	Obligatorio	Descripción
System	object	Sí	Información del sistema solicitante
Property	object	No	Propiedades adicionales del sistema

Estructura de WSRequestHeader.System

Campo	Tipo	Obligatorio	Descripción
name	string	Sí	Nombre del sistema solicitante
correlationID	string	No	ID de correlación para seguimiento
processingServer	string	No	Servidor de procesamiento

Estructura de WSRequestHeader.Property

Campo	Tipo	Obligatorio	Descripción
key	string	Sí	Clave de la propiedad
value	string	Sí	Valor de la propiedad

Estructura de WSRequestBody

Campo	Tipo	Obligatorio	Descripción
Audit	object	No	Información de auditoría
CUN	string	No*	Número de CUN a consultar
Customer	object	No*	Cliente a consultar
Filter	object	No	Filtros aplicables a la consulta
Num_Order	string	No*	Número de orden a consultar
Phone	string	No*	Número de conexión a consultar

*Al menos uno de estos campos debe ser proporcionado

Estructura de Audit

Campo	Tipo	Obligatorio	Descripción
user	string	No	Usuario que realiza la consulta
timestamp	string	No	Timestamp de la consulta
session	string	No	ID de sesión

Estructura de Customer

Campo	Tipo	Obligatorio	Descripción
Document_Type	string	Sí	Tipo de documento del cliente
Document_Number	string	Sí	Número de documento del cliente

Estructura de Filter

Campo	Tipo	Obligatorio	Descripción
Status	string	No	Estado de las órdenes a filtrar
DateFrom	string	No	Fecha de inicio para filtrado
DateTo	string	No	Fecha de fin para filtrado
OrderType	string	No	Tipo de orden a filtrar

Respuesta esperada (Response)

Headers

Campo	Tipo	Obligatorio	Descripción
Content-Type	string	Sí	application/json
X-Request-ID	string	No	Identificador único de la solicitud

Body

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

Estructura de objetos anidados:

Estructura de WSResponseHeader

Campo	Tipo	Obligatorio	Descripción
System	object	Sí	Información del sistema que responde
Service	object	Sí	Información del servicio y estado
Property	object	No	Propiedades adicionales

Estructura de WSResponseHeader.System

Campo	Tipo	Obligatorio	Descripción
name	string	Sí	Nombre del sistema que responde
correlationID	string	No	ID de correlación para seguimiento
processingServer	string	No	Servidor de procesamiento

Estructura de WSResponseHeader.Service

Campo	Tipo	Obligatorio	Descripción
status	string	Sí	Estado de la respuesta (OK/ERROR)
responseDate	string	Sí	Fecha y hora de la respuesta
processingServer	string	No	Servidor de procesamiento
statusDetail	array	No	Detalles del estado con códigos y mensajes

Estructura de WSResponseHeader.Service.statusDetail

Campo	Tipo	Obligatorio	Descripción
errorCode	string	No	Código de error específico
errorMessage	string	No	Mensaje de error técnico
errorMessageUser	string	No	Mensaje de error para el usuario

Estructura de WSResponseBody

Campo	Tipo	Obligatorio	Descripción
Orders	array	No	Lista de órdenes encontradas

Estructura de Order

Campo	Tipo	Obligatorio	Descripción
OrderId	string	Sí	ID único de la orden
OrderNumber	string	Sí	Número de la orden
OrderType	string	Sí	Tipo de orden
Status	string	Sí	Estado actual de la orden
Priority	string	No	Prioridad de la orden
CreationDate	string	Sí	Fecha de creación
LastUpdateDate	string	Sí	Fecha de última actualización
Customer	object	No	Información del cliente asociado
Service	object	No	Información del servicio asociado
Technician	object	No	Información del técnico asignado
Schedule	object	No	Información de agendamiento

Estructura de Order.Customer

Campo	Tipo	Obligatorio	Descripción
CustomerId	string	Sí	ID del cliente
DocumentType	string	Sí	Tipo de documento
DocumentNumber	string	Sí	Número de documento
Name	string	Sí	Nombre completo del cliente
Phone	string	No	Teléfono de contacto
Email	string	No	Correo electrónico

Estructura de Order.Service

Campo	Tipo	Obligatorio	Descripción
ServiceId	string	Sí	ID del servicio
ServiceType	string	Sí	Tipo de servicio
PhoneNumber	string	No	Número de teléfono
Address	string	No	Dirección del servicio
Status	string	Sí	Estado del servicio

Estructura de Order.Technician

Campo	Tipo	Obligatorio	Descripción
TechnicianId	string	No	ID del técnico
Name	string	No	Nombre del técnico
Phone	string	No	Teléfono del técnico
Email	string	No	Correo del técnico

Estructura of Order.Schedule

Campo	Tipo	Obligatorio	Descripción
ScheduleId	string	No	ID del agendamiento
ScheduledDate	string	No	Fecha programada
ScheduledTime	string	No	Hora programada
Status	string	No	Estado del agendamiento

Manejo de errores

Código	Descripción	Ejemplo
ERROR_04	Error en la conversión de datos del request	"El request es nulo"
ERROR_06	No se proporcionó criterio de búsqueda válido	"Debe proporcionar al menos un criterio de búsqueda"
OK_01	Consulta exitosa con resultados	"Consulta realizada exitosamente"
OK_02	Consulta exitosa sin resultados	"No se encontraron órdenes"
BOTERROR	Error interno del sistema	"Se ha generado una excepción no controlada"

Análisis de Componentes

Modelos y componentes

Modelos base utilizados:

BaseRequest (solicitud base)
BaseResponse (respuesta base)
BotBaseRequestHeader (cabecera de solicitud)
BotBaseResponseHeader (cabecera de respuesta)

Utilidades y servicios comunes:

OrderUtil2 (utilidades para manejo de órdenes)
ServiceUtil2 (utilidades para manejo de servicios)
AuditUtil (utilidades de auditoría)
ConfigurationUtil (utilidades de configuración)

Patrones de diseño implementados:

Patrón Singleton (OrderBusiness, ServiceUtil2)
Patrón Factory (creación de respuestas)
Patrón Repository (acceso a datos)

Componentes reutilizados:

BaseRequest/BaseResponse (estructura base)
Audit (auditoría de transacciones)
OrderFilter (filtros de órdenes)

Referencias cruzadas:

/api/orders/v1/get (versión anterior)
/api/orders/v2/get (versión anterior)
/api/orders/v3/get (versión anterior)

Ejemplos de Request/Response

Solicitud (request)

json

{
  "WSRequestHeader": {
    "System": {
      "name": "SISTEMA_CLIENTE",
      "correlationID": "REQ-12345-67890",
      "processingServer": "SRV-001"
    },
    "Property": [
      {
        "key": "version",
        "value": "1.0"
      }
    ]
  },
  "WSRequestBody": {
    "Audit": {
      "user": "usuario_sistema",
      "timestamp": "2024-01-15T10:30:00",
      "session": "SESS-12345"
    },
    "Customer": {
      "Document_Type": "CC",
      "Document_Number": "12345678"
    },
    "Filter": {
      "Status": "PENDIENTE",
      "DateFrom": "2024-01-01",
      "DateTo": "2024-12-31"
    }
  }
}

Respuesta exitosa

json

{
  "WSResponseHeader": {
    "System": {
      "name": "SISTEMA_ORDENES",
      "correlationID": "REQ-12345-67890",
      "processingServer": "SRV-001"
    },
    "Service": {
      "status": "OK",
      "responseDate": "2024-01-15T10:30:05",
      "processingServer": "SRV-001",
      "statusDetail": [
        {
          "errorCode": "OK_01",
          "errorMessage": "Consulta realizada exitosamente",
          "errorMessageUser": "Se encontraron 2 órdenes"
        }
      ]
    }
  },
  "WSResponseBody": {
    "Orders": [
      {
        "OrderId": "ORD-001",
        "OrderNumber": "123456789",
        "OrderType": "INSTALACION",
        "Status": "PENDIENTE",
        "Priority": "ALTA",
        "CreationDate": "2024-01-10T08:00:00",
        "LastUpdateDate": "2024-01-15T09:30:00",
        "Customer": {
          "CustomerId": "CUST-001",
          "DocumentType": "CC",
          "DocumentNumber": "12345678",
          "Name": "Juan Pérez",
          "Phone": "3001234567",
          "Email": "juan.perez@email.com"
        },
        "Service": {
          "ServiceId": "SERV-001",
          "ServiceType": "INTERNET_FIJO",
          "PhoneNumber": "6012345678",
          "Address": "Calle 123 #45-67, Bogotá",
          "Status": "ACTIVO"
        },
        "Technician": {
          "TechnicianId": "TECH-001",
          "Name": "Carlos Rodríguez",
          "Phone": "3009876543",
          "Email": "carlos.rodriguez@etb.com"
        },
        "Schedule": {
          "ScheduleId": "SCH-001",
          "ScheduledDate": "2024-01-20",
          "ScheduledTime": "14:00",
          "Status": "CONFIRMADO"
        }
      }
    ]
  }
}

Respuesta de error

json

{
  "WSResponseHeader": {
    "System": {
      "name": "SISTEMA_ORDENES",
      "correlationID": "REQ-12345-67890",
      "processingServer": "SRV-001"
    },
    "Service": {
      "status": "ERROR",
      "responseDate": "2024-01-15T10:30:00",
      "processingServer": "SRV-001",
      "statusDetail": [
        {
          "errorCode": "ERROR_06",
          "errorMessage": "Debe proporcionar al menos un criterio de búsqueda",
          "errorMessageUser": "Por favor, especifique un criterio de búsqueda válido"
        }
      ]
    }
  },
  "WSResponseBody": {
    "Orders": null
  }
}

Diagramas Técnicos

3.1 Flujo de datos

mermaid

graph TD
  A[Recepción de la solicitud] --> B[OrdersController.Get_v4]
  B --> C[Validación de autenticación]
  C --> D[OrderBusiness.Get_v4]
  D --> E[Auditoría de entrada]
  E --> F[Conversión de datos]
  F --> G{Validación de criterios}
  G -->|Cliente| H[OrderUtil2.GetByCustomer]
  G -->|Número de orden| I[OrderUtil2.GetByNumOrder]
  G -->|CUN| J[OrderUtil2.GetByCUN]
  G -->|Teléfono| K[ServiceUtil2.GetBasicByPhone]
  K --> L[OrderUtil2.GetByService]
  H --> M[Procesamiento de filtros]
  I --> M
  J --> M
  L --> M
  M --> N[Generación de respuesta]
  N --> O[Auditoría de salida]
  O --> P[Respuesta al cliente]

3.2 Arquitectura de clases

mermaid

classDiagram
  class OrdersController {
    +Get_v4(BaseRequestGet_v4)
  }
  class OrderBusiness {
    +Get_v4(BaseRequest, string)
  }
  class OrderUtil2 {
    +GetByCustomer(RequestModel, string, string, OrderFilter)
    +GetByNumOrder(RequestModel, string, OrderFilter)
    +GetByCUN(RequestModel, string, OrderFilter)
    +GetByService(RequestModel, Basic_Service, OrderFilter)
  }
  class ServiceUtil2 {
    +GetBasicByPhone(string)
  }
  class CRUD_MDM_ORDEN {
    +GetByCustomer(string, string, OrderFilter)
    +GetByNumOrder(string)
  }
  class CRUD_MDM_CD_ORDEN {
    +GetByCustomer(string, string, OrderFilter)
    +GetByNumOrder(string)
  }
  OrdersController --> OrderBusiness
  OrderBusiness --> OrderUtil2
  OrderBusiness --> ServiceUtil2
  OrderUtil2 --> CRUD_MDM_ORDEN
  OrderUtil2 --> CRUD_MDM_CD_ORDEN

3.3 Secuencia de ejecución

mermaid

sequenceDiagram
  participant Cliente
  participant OrdersController
  participant OrderBusiness
  participant OrderUtil2
  participant ServiceUtil2
  participant Database
  Cliente->>OrdersController: POST /api/orders/v4/get
  OrdersController->>OrderBusiness: Get_v4(request, request_name)
  OrderBusiness->>OrderBusiness: Auditoría de entrada
  OrderBusiness->>OrderBusiness: Conversión de datos
  alt Consulta por cliente
    OrderBusiness->>OrderUtil2: GetByCustomer(origin, docType, docNumber, filter)
    OrderUtil2->>Database: Consulta MDM_ORDEN y MDM_CD_ORDEN
  else Consulta por número de orden
    OrderBusiness->>OrderUtil2: GetByNumOrder(origin, numOrder, filter)
    OrderUtil2->>Database: Consulta por número de orden
  else Consulta por CUN
    OrderBusiness->>OrderUtil2: GetByCUN(origin, cun, filter)
    OrderUtil2->>Database: Consulta por CUN
  else Consulta por teléfono
    OrderBusiness->>ServiceUtil2: GetBasicByPhone(phone)
    ServiceUtil2->>Database: Consulta servicio básico
    OrderBusiness->>OrderUtil2: GetByService(origin, service, filter)
    OrderUtil2->>Database: Consulta órdenes por servicio
  end
  Database-->>OrderUtil2: Resultados
  OrderUtil2-->>OrderBusiness: Lista de órdenes
  OrderBusiness->>OrderBusiness: Procesamiento de filtros
  OrderBusiness->>OrderBusiness: Auditoría de salida
  OrderBusiness-->>OrdersController: BaseResponseGet_v4
  OrdersController-->>Cliente: Respuesta JSON

Políticas y Consideraciones

Políticas de seguridad

Mecanismos de autenticación y autorización:

Autenticación mediante token Bearer
Validación de headers de seguridad obligatorios
Auditoría completa de todas las transacciones

Validaciones de seguridad implementadas:

Validación de IP de origen
Verificación de permisos por sistema
Sanitización de datos de entrada

Límites de tasa (rate limits):

Máximo 1000 consultas por minuto por sistema
Límite de 100 consultas por segundo por IP

SLAs aplicables:

Tiempo de respuesta máximo: 5 segundos
Disponibilidad: 99.9%
Tolerancia a fallos: 3 reintentos automáticos

Recomendaciones y mejores prácticas

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

Implementar cache distribuido para mejorar rendimiento
Agregar validación de formato de documentos
Implementar paginación para grandes volúmenes de datos
Mejorar manejo de excepciones específicas

Optimizaciones posibles:

Usar índices compuestos en base de datos
Implementar consultas paralelas para múltiples criterios
Optimizar consultas de base de datos con proyecciones
Implementar cache de configuración de tipologías

Consideraciones de mantenimiento importantes:

Monitorear tiempos de respuesta de base de datos
Revisar logs de auditoría regularmente
Mantener actualizada la configuración de tipologías
Validar integridad de datos periódicamente

Sugerencias de seguridad aplicables:

Implementar encriptación de datos sensibles en tránsito
Agregar validación de tokens JWT
Implementar rate limiting por usuario
Agregar logging de eventos de seguridad

Consulta de Órdenes de Servicios - orders-v4-get ​

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 WSRequestBody ​

Estructura de Audit ​

Estructura de Customer ​

Estructura de Filter ​

Respuesta esperada (Response) ​

Headers ​

Body ​

Estructura de WSResponseHeader ​

Estructura de WSResponseHeader.System ​

Estructura de WSResponseHeader.Service ​

Estructura de WSResponseHeader.Service.statusDetail ​

Estructura de WSResponseBody ​

Estructura de Order ​

Estructura de Order.Customer ​

Estructura de Order.Service ​

Estructura de Order.Technician ​

Estructura of Order.Schedule ​

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 ​

Consulta de Órdenes de Servicios - orders-v4-get

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 WSRequestBody

Estructura de Audit

Estructura de Customer

Estructura de Filter

Respuesta esperada (Response)

Headers

Body

Estructura de WSResponseHeader

Estructura de WSResponseHeader.System

Estructura de WSResponseHeader.Service

Estructura de WSResponseHeader.Service.statusDetail

Estructura de WSResponseBody

Estructura de Order

Estructura de Order.Customer

Estructura de Order.Service

Estructura de Order.Technician

Estructura of Order.Schedule

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