Orders v4 Get – Consulta de Órdenes de Servicios de Telecomunicaciones

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 permite consultar las órdenes asociadas a un cliente, servicio o una orden específica en el sistema de gestión de órdenes de ETB. Este servicio es la versión más reciente y optimizada del endpoint de consulta de órdenes, implementando operaciones asíncronas para mejorar el rendimiento.

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 servicio (número de conexión)
Consulta de una orden específica por número de orden
Consulta de órdenes por CUN (Código Único de Negocio)
Filtrado de órdenes por estado, fechas y criterios específicos

Especificación técnica

Endpoint completo: /api/orders/v4/get
Método HTTP: POST
Tipo de respuesta: Asíncrona (async/await)

Capas involucradas:

Controlador: OrdersController.Get_v4() - Maneja la recepción de la petición HTTP
Lógica de negocio: OrderBusiness.Get_v4() - Procesa la lógica de consulta
Acceso a datos: OrderUtil2 - Realiza las consultas a las bases de datos MongoDB
Utilidades: ServiceUtil2, ConfigurationUtil, AuditUtil

Flujo de procesamiento:

Recepción de la petición HTTP en el controlador
Validación y conversión de datos de entrada
Auditoría de entrada
Obtención del origen y configuración del sistema
Validación de parámetros de consulta
Ejecución de consulta según el criterio proporcionado:
- Por cliente (Document_Type + Document_Number)
- Por número de orden (Num_Order)
- Por CUN (CUN)
- Por número de conexión (Phone)
Aplicación de filtros y enriquecimiento de datos
Construcción de la respuesta
Auditoría de salida

Dependencias principales:

OrderUtil2.GetInstance - Utilidad para consultas de órdenes
ServiceUtil2.GetInstance - Utilidad para consultas de servicios
ConfigurationUtil.GetInstance - Utilidad de configuración
AuditUtil.GetInstance - Utilidad de auditoría
CRUD_MDM_ORDEN - Acceso a datos de órdenes móviles
CRUD_MDM_CD_ORDEN - Acceso a datos de órdenes fijas

Consideraciones de seguridad:

Autenticación mediante token Bearer
Validación de origen del sistema
Auditoría completa de entrada y salida
Validación de parámetros de entrada

Parámetros de entrada (Request)

Headers

Campo	Tipo	Obligatorio	Descripción
Authorization	string	Sí	Token Bearer para autenticación
X_SYSTEM	string	Sí	Nombre del sistema que origina la petición
X_CHANNEL	string	No	Canal de origen de la petición
X_CORRELATION_ID	string	No	ID de correlación para seguimiento
X_CIV_REQUEST	string	No	Vector de inicialización para encriptación

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 los parámetros de consulta

Estructura WSRequestHeader:

Campo	Tipo	Obligatorio	Descripción
System	object	Sí	Información del sistema
Property	array	No	Propiedades adicionales de la petición

Estructura System:

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

Estructura 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*	Información del 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 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 Filter:

Campo	Tipo	Obligatorio	Descripción
Address	boolean	No	Consultar dirección asignada
Billing_Account	boolean	No	Consultar cuenta de facturación
End_Date	datetime	No	Fecha fin de la consulta
Extend_Search	boolean	No	Realizar consulta extendida (6 meses)
New_Offer	boolean	No	Consultar nueva oferta
Old_Offer	boolean	No	Consultar oferta anterior
Schedule	boolean	No	Consultar información de agendamiento
Start_Date	datetime	No	Fecha inicio de la consulta
States	object	No	Filtrado de estados de la orden
Technician	boolean	No	Consultar información del técnico

Estructura States:

Campo	Tipo	Obligatorio	Descripción
Action	boolean	No	Incluir (true) o excluir (false) estados
Cancelled	boolean	No	Incluir órdenes canceladas
Completed	boolean	No	Incluir órdenes completadas
Pending	boolean	No	Incluir órdenes pendientes
States	array	No	Lista de estados específicos

Respuesta esperada (Response)

Headers

Campo	Tipo	Obligatorio	Descripción
Content-Type	string	Sí	application/json
X-Correlation-ID	string	No	ID de correlación de la respuesta

Body

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

Estructura WSResponseHeader:

Campo	Tipo	Obligatorio	Descripción
System	object	Sí	Información del sistema
Service	object	Sí	Información del servicio y estado
Property	array	No	Propiedades adicionales de la respuesta

Estructura Service:

Campo	Tipo	Obligatorio	Descripción
Status	string	Sí	Estado del servicio (OK/FAIL)
StatusDetail	array	No	Detalles del estado y mensajes

Estructura WSResponseBody:

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

Estructura Order (elemento de Orders):

Campo	Tipo	Obligatorio	Descripción
Id	string	Sí	Identificador único de la orden
CUN	string	No	Código Único de Negocio
Order_Type	string	Sí	Tipo de orden (VTA, PRCH, CTEC, etc.)
State	string	Sí	Estado actual de la orden
Creation_Date	datetime	Sí	Fecha de creación de la orden
Phone	string	No	Número de conexión asociado
Customer	object	No	Información del cliente
Service	object	No	Información del servicio
Schedule	object	No	Información de agendamiento
New_Offer	object	No	Nueva oferta contratada
Old_Offer	object	No	Oferta anterior
Technician	object	No	Información del técnico asignado

Manejo de errores

Código	Descripción	Ejemplo
ERROR_04	Objetos no acordes a la petición	Request nulo o malformado
ERROR_06	Parámetros de consulta insuficientes	No se proporcionó criterio de búsqueda
OK_01	Consulta exitosa con resultados	Se encontraron órdenes
OK_02	Consulta exitosa sin resultados	No se encontraron órdenes
BOTERROR	Excepción no controlada	Error interno del sistema

Análisis de Componentes

Modelos y componentes

Modelos base utilizados:

BaseRequest - Clase base para todas las peticiones
BaseResponse - Clase base para todas las respuestas
BotBaseRequestHeader - Cabecera estándar de peticiones
BotBaseResponseHeader - Cabecera estándar de respuestas
Audit - Información de auditoría

Utilidades y servicios comunes:

OrderUtil2 - Utilidad principal para consultas de órdenes
ServiceUtil2 - Utilidad para consultas de servicios
ConfigurationUtil - Gestión de configuraciones del sistema
AuditUtil - Gestión de auditoría y logs
CRUD_MDM_ORDEN - Acceso a datos de órdenes móviles
CRUD_MDM_CD_ORDEN - Acceso a datos de órdenes fijas

Patrones de diseño implementados:

Singleton Pattern: Utilizado en las utilidades (GetInstance)
Factory Pattern: Para la creación de modelos de respuesta
Repository Pattern: En las clases CRUD para acceso a datos
Strategy Pattern: Para diferentes tipos de consulta según criterios

Componentes reutilizados:

OrderFilter - Filtros de consulta reutilizables
OrderStateFilter - Filtros de estado específicos
Basic_Service - Modelo básico de servicio
OrderModel - Modelo principal de orden

Referencias cruzadas:

/api/orders/v1/get - Versión anterior del servicio
/api/orders/v2/get - Versión con información de portabilidad
/api/orders/v3/get - Versión con consulta por usuario MiETB
/api/service/v4/get - Servicio relacionado para consulta de servicios

Ejemplos de Request/Response

Solicitud (request)

json

{
  "WSRequestHeader": {
    "System": {
      "name": "PORTALWEB",
      "correlationID": "PORTALWEB-2025712-163437553",
      "processingServer": null
    },
    "Property": []
  },
  "WSRequestBody": {
    "Audit": {
      "Canal": "WEB",
      "Id_Device": null,
      "SO": null,
      "IP_Address": null,
      "WhatsApp_Phone_Number": null
    },
    "CUN": "",
    "Customer": {
      "Document_Number": "10411445740",
      "Document_Type": "CC"
    },
    "Filter": {
      "Address": false,
      "Billing_Account": false,
      "End_Date": null,
      "New_Offer": true,
      "Old_Offer": true,
      "Schedule": true,
      "Start_Date": null,
      "States": {
        "Action": true,
        "Completed": false,
        "Cancelled": false,
        "Pending": true
      },
      "Technician": true,
      "Types": {
        "Action": true,
        "Aseguramiento": true,
        "Cambio_Plan": true,
        "Suspension_Reconexion": true,
        "Tramites": true,
        "Traslado": true,
        "Venta": true
      }
    },
    "Num_Order": "",
    "Phone": ""
  }
}

Respuesta exitosa

json

{
  "WSResponseHeader": {
    "System": {
      "name": "BOT_SYSTEM",
      "correlationID": "12345-67890-abcde",
      "processingServer": "BOT-SERVER-01"
    },
    "Service": {
      "Status": "OK",
      "StatusDetail": [
        {
          "ErrorCode": "OK_01",
          "ErrorDetailCode": "Consulta exitosa. Se encontraron 2 órdenes.",
          "Origin": "BOT_SYSTEM"
        }
      ]
    }
  },
  "WSResponseBody": {
    "Orders": [
      {
        "Id": "ORD-2024-001",
        "CUN": "CUN123456789",
        "Order_Type": "VTA",
        "State": "O160",
        "Creation_Date": "2024-01-15T10:30:00",
        "Phone": "3001234567",
        "Customer": {
          "Document_Type": "CC",
          "Document_Number": "12345678",
          "Name": "Juan Pérez"
        },
        "Service": {
          "Phone": "3001234567",
          "Technology": "FTTH",
          "State": "Activo"
        },
        "Schedule": {
          "Date": "2024-01-20T14:00:00",
          "Status": "Agendado"
        },
        "New_Offer": {
          "Name": "Plan Hogar 100MB",
          "Price": 50000
        }
      },
      {
        "Id": "ORD-2024-002",
        "CUN": "CUN987654321",
        "Order_Type": "PRCH",
        "State": "O40",
        "Creation_Date": "2024-01-10T09:15:00",
        "Phone": "3001234567",
        "Customer": {
          "Document_Type": "CC",
          "Document_Number": "12345678",
          "Name": "Juan Pérez"
        },
        "Service": {
          "Phone": "3001234567",
          "Technology": "FTTH",
          "State": "Activo"
        }
      }
    ]
  }
}

Respuesta de error

json

{
  "WSResponseHeader": {
    "System": {
      "name": "BOT_SYSTEM",
      "correlationID": "12345-67890-abcde",
      "processingServer": "BOT-SERVER-01"
    },
    "Service": {
      "Status": "FAIL",
      "StatusDetail": [
        {
          "ErrorCode": "ERROR_06",
          "ErrorDetailCode": "No se proporcionó criterio de búsqueda válido. Debe enviar al menos uno de los siguientes: Customer, Num_Order, CUN o Phone.",
          "Origin": "BOT_SYSTEM"
        }
      ]
    }
  },
  "WSResponseBody": {
    "Orders": null
  }
}

Diagramas Técnicos

3.1 Flujo de datos

mermaid

graph TD
    A[Cliente HTTP Request] --> B[OrdersController.Get_v4]
    B --> C[Validación de Headers]
    C --> D[Conversión BaseRequest]
    D --> E[AuditUtil.Save_Request_Async]
    E --> F[OrderBusiness.Get_v4]
    F --> G{Validación Request}
    G -->|Válido| H[ConfigurationUtil.Get_Origin]
    G -->|Inválido| I[Error ERROR_04]
    H --> J[Validación Parámetros]
    J --> K{Criterio de Consulta}
    K -->|Customer| L[OrderUtil2.GetByCustomer]
    K -->|Num_Order| M[OrderUtil2.GetByNumOrder]
    K -->|CUN| N[OrderUtil2.GetByCUN]
    K -->|Phone| O[ServiceUtil2.GetBasicByPhone]
    O --> P[OrderUtil2.GetByService]
    L --> Q[Construcción Response]
    M --> Q
    N --> Q
    P --> Q
    Q --> R[AuditUtil.Save_Request_Async]
    R --> S[HTTP Response]
    I --> S

3.2 Arquitectura de clases

mermaid

classDiagram
    class OrdersController {
        +Get_v4(BaseRequestGet_v4) Task~BaseResponseGet_v4~
    }
    
    class OrderBusiness {
        +Get_v4(BaseRequest, string) Task~BaseResponseGet_v4~
    }
    
    class OrderUtil2 {
        +GetByCustomer(RequestModel, string, string, OrderFilter) Task~List~OrderModel~~
        +GetByNumOrder(RequestModel, string, OrderFilter) Task~OrderModel~
        +GetByCUN(RequestModel, string, OrderFilter) Task~OrderModel~
        +GetByService(RequestModel, Basic_Service, OrderFilter) Task~List~OrderModel~~
    }
    
    class ServiceUtil2 {
        +GetBasicByPhone(string) Task~Basic_Service~
    }
    
    class BaseRequestGet_v4 {
        +WSRequestHeader BotBaseRequestHeader
        +WSRequestBody GetRequest_v4
    }
    
    class GetRequest_v4 {
        +Audit Audit
        +string CUN
        +GetRequestClient_v4 Customer
        +OrderFilter Filter
        +string Num_Order
        +string Phone
    }
    
    class BaseResponseGet_v4 {
        +WSResponseHeader BotBaseResponseHeader
        +WSResponseBody GetResponse_v4
    }
    
    class GetResponse_v4 {
        +List~OrderModel~ Orders
    }
    
    OrdersController --> OrderBusiness
    OrderBusiness --> OrderUtil2
    OrderBusiness --> ServiceUtil2
    OrdersController --> BaseRequestGet_v4
    OrdersController --> BaseResponseGet_v4
    BaseRequestGet_v4 --> GetRequest_v4
    BaseResponseGet_v4 --> GetResponse_v4

3.3 Secuencia de ejecución

mermaid

sequenceDiagram
    participant Client
    participant OrdersController
    participant OrderBusiness
    participant OrderUtil2
    participant ServiceUtil2
    participant CRUD_MDM_ORDEN
    participant CRUD_MDM_CD_ORDEN
    participant AuditUtil
    
    Client->>OrdersController: POST /api/orders/v4/get
    OrdersController->>AuditUtil: Save_Request_Async (entrada)
    OrdersController->>OrderBusiness: Get_v4(request, request_name)
    
    OrderBusiness->>OrderBusiness: Validación de request
    alt Request válido
        OrderBusiness->>OrderBusiness: Obtener origen y configuración
        OrderBusiness->>OrderBusiness: Validar criterios de consulta
        
        alt Consulta por Customer
            OrderBusiness->>OrderUtil2: GetByCustomer(Origin, DocType, DocNum, Filter)
            OrderUtil2->>CRUD_MDM_ORDEN: GetByCustomer(DocType, DocNum, Filter)
            OrderUtil2->>CRUD_MDM_CD_ORDEN: GetByCustomer(DocType, DocNum, Filter)
            CRUD_MDM_ORDEN-->>OrderUtil2: List<MDM_ORDEN>
            CRUD_MDM_CD_ORDEN-->>OrderUtil2: List<MDM_CD_ORDEN>
            OrderUtil2-->>OrderBusiness: List<OrderModel>
        else Consulta por Phone
            OrderBusiness->>ServiceUtil2: GetBasicByPhone(Phone)
            ServiceUtil2-->>OrderBusiness: Basic_Service
            OrderBusiness->>OrderUtil2: GetByService(Origin, Service, Filter)
            OrderUtil2-->>OrderBusiness: List<OrderModel>
        else Consulta por Num_Order
            OrderBusiness->>OrderUtil2: GetByNumOrder(Origin, NumOrder, Filter)
            OrderUtil2-->>OrderBusiness: OrderModel
        else Consulta por CUN
            OrderBusiness->>OrderUtil2: GetByCUN(Origin, CUN, Filter)
            OrderUtil2-->>OrderBusiness: OrderModel
        end
        
        OrderBusiness->>OrderBusiness: Construir respuesta
        OrderBusiness-->>OrdersController: BaseResponseGet_v4
    else Request inválido
        OrderBusiness->>OrderBusiness: Generar error ERROR_04
        OrderBusiness-->>OrdersController: BaseResponseGet_v4 con error
    end
    
    OrdersController->>AuditUtil: Save_Request_Async (salida)
    OrdersController-->>Client: HTTP Response

Políticas y Consideraciones

Políticas de seguridad

Mecanismos de autenticación y autorización:

Autenticación mediante token Bearer JWT
Validación obligatoria del header X_SYSTEM
Verificación de origen del sistema en configuración
Auditoría completa de todas las transacciones

Validaciones de seguridad implementadas:

Validación de formato de token de autenticación
Verificación de IP de origen en auditoría
Validación de parámetros de entrada contra inyección
Sanitización de datos de consulta

Límites de tasa (rate limits):

No se implementan rate limits específicos en esta versión
Se recomienda implementar límites por sistema/origen

SLAs aplicables:

Tiempo de respuesta esperado: < 2 segundos
Disponibilidad del servicio: 99.9%
Tolerancia a fallos: Circuit breaker implementado en capa de datos

Recomendaciones y mejores prácticas

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

Implementar rate limiting: Agregar límites de tasa por sistema para prevenir abuso
Optimizar consultas paralelas: Mejorar el uso de Task.WhenAll en consultas múltiples
Agregar métricas de rendimiento: Implementar logging de tiempos de respuesta
Mejorar manejo de errores: Implementar retry policies para consultas a base de datos

Optimizaciones posibles:

csharp

// Ejemplo de optimización de consultas paralelas
var tasks = new List<Task>();
tasks.Add(GetOrdersByCustomerAsync(customer));
tasks.Add(GetOrdersByServiceAsync(service));
var results = await Task.WhenAll(tasks);

Consideraciones de mantenimiento importantes:

Monitorear el rendimiento de consultas a MongoDB
Revisar regularmente los índices de las colecciones MDM_ORDEN y MDM_CD_ORDEN
Mantener actualizada la configuración de tipologías de error
Validar periódicamente la integridad de los datos de auditoría

Sugerencias de seguridad aplicables:

Implementar rate limiting por IP y sistema
Agregar validación de formato de documentos
Implementar logging de consultas sensibles
Agregar encriptación de datos sensibles en logs
Implementar timeout configurable para consultas

Ejemplo de implementación de rate limiting:

csharp

[RateLimit(MaxRequests = 100, TimeWindow = 60)] // 100 requests por minuto
public async Task<BaseResponseGet_v4> Get_v4(BaseRequestGet_v4 request)
{
    // Implementación actual
}

Notas adicionales:

El servicio es compatible con versiones anteriores (v1, v2, v3)
Se recomienda migrar a esta versión para mejor rendimiento
La consulta asíncrona mejora significativamente el tiempo de respuesta
Los filtros son opcionales pero recomendados para optimizar consultas

Orders v4 Get – Consulta de Órdenes de Servicios de Telecomunicaciones ​

Documentación del Servicio ​

Descripción general ​

Especificación técnica ​

Parámetros de entrada (Request) ​

Headers ​

Body ​

Respuesta esperada (Response) ​

Headers ​

Body ​

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 ​

Orders v4 Get – Consulta de Órdenes de Servicios de Telecomunicaciones

Documentación del Servicio

Descripción general

Especificación técnica

Parámetros de entrada (Request)

Headers

Body

Respuesta esperada (Response)

Headers

Body

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