Consulta de Saldos de Línea Móvil - services-v2-getbalance

Información del Servicio

Endpoint: /api/services/v2/getbalance
Método: POST
Versión: v2
Categoría: Consulta de Saldos

Documentación del Servicio

Descripción general

El servicio services-v2-getbalance es un endpoint para consultar los saldos de una línea móvil. A diferencia de la primera versión, esta versión proporciona los totales agregados de los recursos disponibles.

Categoría de negocio: Consulta de Saldos de Servicios Móviles.

Casos de uso principales:

Consulta de saldos monetarios disponibles
Consulta de recursos de datos (3G/4G)
Consulta de minutos disponibles
Consulta de saldos promocionales
Consulta de recursos adicionales (WhatsApp, redes sociales, etc.)

Especificación técnica

Endpoint completo: /api/services/v2/getbalance
Método HTTP: POST
Capas involucradas:
- Controlador: ServicesController.GetBalance_v2()
- Lógica de negocio: ServiceBusiness.GetBalance_v2()
- Acceso a datos: ServiceUtil2.GetBalance()

Flujo de procesamiento:

Validación de la petición y auditoría de entrada
Conversión de datos del request
Obtención del origen de la petición
Consulta del servicio móvil
Procesamiento de saldos y recursos
Generación de respuesta con totales agregados
Auditoría de salida

Dependencias principales:

BotModel.Services.Service.GetBalance_v2
BotBusiness.Controllers.ServiceBusiness
BotBusiness.Util.ServiceUtil2
BotBusiness.Util.AuditUtil

Consideraciones de seguridad:

Validación de autenticación SOAP (para endpoints SOAP)
Auditoría completa de entrada y salida
Validación de datos de entrada
Manejo de excepciones controlado

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
Phone	string	Sí	Número de conexión del servicio (ejemplo: 3102001010)

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	Sí	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 con información del sistema y servicio

Body

Campo	Tipo	Obligatorio	Descripción
Available_Coin	string	No	Total en saldo monetario (formato string)
Available_Coin_Value	double?	No	Total en saldo monetario (valor numérico)
Detailed	object	No	Información detallada de los recursos
Promotion_Coin	string	No	Saldo promocional valor string
Promotion_Coin_Value	double?	No	Saldo promocional
Resume	object	No	Información resumida de los recursos

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

Estructura de Detailed

Campo	Tipo	Obligatorio	Descripción
Detail	array	No	Detalle de los saldos

Estructura de Detailed.Detail

Campo	Tipo	Obligatorio	Descripción
Boxs	array	No	Agrupaciones de ofertas
Section_Name	string	No	Nombre de la sección (Estructurales, Promocionales, Adicionales, Linea)

Estructura de Detailed.Detail.Boxs

Campo	Tipo	Obligatorio	Descripción
Available	string	No	Recurso disponible
Box_Name	string	No	Nombre de la agrupación
Consume	string	No	Consumo realizado
Group_Name	string	No	Nombre del grupo para sumatoria
Offers	array	No	Ofertas asociadas
Provisioned	string	No	Provisionado
Unity_Type	string	No	Tipo de unidad (MIN, DAT, SMS, $)

Estructura de Detailed.Detail.Boxs.Offers

Campo	Tipo	Obligatorio	Descripción
Available_Balance_User	string	No	Saldo disponible en Charging a mostrar al usuario
Available_Balance_Charging	double?	No	Saldo disponible en Charging
Balance_Consumed	double?	No	Saldo consumido en Charging
Balance_Consumed_User	string	No	Saldo consumido en Charging a mostrar al usuario
Expiration_Date	string	No	Fecha de expiración de la oferta
Max_Capacity_Charging	string	No	Máxima capacidad en Charging
Offer_Id	string	No	Identificador de la oferta
Unity_Type	string	No	Tipo de unidad

Estructura de Resume

Campo	Tipo	Obligatorio	Descripción
Resource	array	No	Recursos del servicio

Estructura de Resume.Resource

Campo	Tipo	Obligatorio	Descripción
Additional	object	No	Detalle del recurso (adicional)
Available	string	No	Cantidad disponible
Consumed	string	No	Cantidad consumida
Expiration_Date	string	No	Fecha de expiración de la oferta
Name	string	No	Recurso asociado
Promotion	object	No	Detalle del recurso (promocional)
Provisioned	string	No	Cantidad adquirida
Rollover	object	No	Detalle del recurso (salva recursos)
Structural	object	No	Detalle del recurso (estructural)

Manejo de errores

Código	Descripción	Ejemplo
ERROR_04	La solicitud no fue exitosa. Fueron enviados objetos no acordes a la petición	Request nulo o Phone vacío
ERROR_03	La solicitud no fue exitosa. No fue posible validar la petición	Error en descifrado de petición
ERROR_02	La solicitud no fue exitosa. No fue posible obtener el origen	Error al obtener origen de la petición
ERROR_01	La solicitud no fue exitosa. No fue posible obtener el usuario asociado	Error de autenticación
ERROR_00	La solicitud no fue exitosa. Se ha generado una excepción técnica	Excepción no controlada
BOTERROR	Se ha generado una excepción no controlada	Error interno del sistema

Análisis de Componentes

Modelos y componentes

Modelos base utilizados:

BotModel.Services.Service.GetBalance_v2.BaseRequestGetBalance_v2
BotModel.Services.Service.GetBalance_v2.BaseResponseGetBalance_v2
BotModel.Services.Service.GetBalance_v2.GetBalanceRequest_v2
BotModel.Services.Service.GetBalance_v2.GetBalanceResponse_v2

Utilidades y servicios comunes:

BotBusiness.Util.ServiceUtil2.GetBalance()
BotBusiness.Util.AuditUtil.Save_Request_Async()
BotBusiness.Util.ConfigurationUtil.Get_Tipology()

Patrones de diseño implementados:

Patrón Singleton para ServiceBusiness
Patrón Factory para creación de respuestas
Patrón Strategy para manejo de diferentes tipos de saldos

Componentes reutilizados:

BotBaseRequestHeader/BotBaseResponseHeader
BotBaseRequestSystem/BotBaseResponseSystem
BotBaseResponseService para manejo de errores

Referencias cruzadas:

Servicio GetBalance_v1 (versión anterior)
Servicio GetBalanceTransferHistory_v1
Servicio ServicesGetBalance (MiETB API)

Ejemplos de Request/Response

Solicitud (request)

json

{
  "WSRequestHeader": {
    "System": {
      "name": "MAX",
      "correlationID": "LUZ-0.5058314057277247",
      "processingServer": null
    },
    "Property": [
      {
        "name": null,
        "value": null
      }
    ]
  },
  "WSRequestBody": {
    "Phone": "3160009921",
    "Audit": {
      "Canal": null,
      "IP_Address": "169.60.82.89",
      "IP_Latitud": "4.8094",
      "IP_Longitude": "-74.0980",
      "IP_City": "COTA",
      "IP_Country": "COLOMBIA",
      "Date": "2025-07-31",
      "Hour": "18:25:53",
      "WhatsApp_Phone_Number": null,
      "Facebook_User": "",
      "Twitter_User": ""
    }
  }
}

Respuesta exitosa

json

{
  "WSResponseHeader": {
    "System": {
      "Name": "SISTEMA_CLIENTE",
      "CorrelationID": "123456789",
      "ProcessingServer": "SERVER_01"
    },
    "Service": {
      "Status": "OK",
      "ResponseDate": "2024-12-19T10:30:00",
      "ProcessingServer": "SERVER_01",
      "StatusDetail": []
    },
    "Property": [
      {
        "Name": "CHANNEL",
        "Value": "WEB"
      }
    ]
  },
  "WSResponseBody": {
    "Available_Coin": "50000",
    "Available_Coin_Value": 50000.0,
    "Promotion_Coin": "10000",
    "Promotion_Coin_Value": 10000.0,
    "Detailed": {
      "Detail": [
        {
          "Section_Name": "Estructurales",
          "Boxs": [
            {
              "Box_Name": "DATOS 4G",
              "Available": "5GB",
              "Consume": "2GB",
              "Provisioned": "7GB",
              "Unity_Type": "DAT",
              "Group_Name": "DATOS 4G",
              "Offers": [
                {
                  "Offer_Id": "OFFER_001",
                  "Available_Balance_User": "5GB",
                  "Available_Balance_Charging": 5.0,
                  "Balance_Consumed": 2.0,
                  "Balance_Consumed_User": "2GB",
                  "Max_Capacity_Charging": "7GB",
                  "Unity_Type": "DAT",
                  "Expiration_Date": "2024-12-31"
                }
              ]
            }
          ]
        }
      ]
    },
    "Resume": {
      "Resource": [
        {
          "Name": "DATOS 4G",
          "Available": "5GB",
          "Consumed": "2GB",
          "Provisioned": "7GB",
          "Expiration_Date": "2024-12-31",
          "Structural": {
            "Available": "5GB",
            "Consumed": "2GB",
            "Provisioned": "7GB"
          }
        }
      ]
    }
  }
}

Respuesta de error

json

{
  "WSResponseHeader": {
    "System": {
      "Name": "SISTEMA_CLIENTE",
      "CorrelationID": "123456789",
      "ProcessingServer": "SERVER_01"
    },
    "Service": {
      "Status": "FAIL",
      "ResponseDate": "2024-12-19T10:30:00",
      "ProcessingServer": "SERVER_01",
      "StatusDetail": [
        {
          "ErrorCode": "ERROR_04",
          "ErrorMessage": "La solicitud 123456789 no fue exitosa. Fueron enviados objetos no acordes a la petición",
          "ErrorMessageUser": "La solicitud 123456789 no fue exitosa. Fueron enviados objetos no acordes a la petición"
        }
      ]
    },
    "Property": []
  },
  "WSResponseBody": null
}

Diagramas Técnicos

3.1 Flujo de datos

mermaid

graph TD
  A[Recepción de la solicitud] --> B[ServicesController.GetBalance_v2]
  B --> C[Auditoría de entrada]
  C --> D[Conversión de datos]
  D --> E[Validación de request]
  E --> F[Obtención del origen]
  F --> G[Consulta del servicio móvil]
  G --> H[ServiceUtil2.GetBalance]
  H --> I[Procesamiento de saldos]
  I --> J[Generación de respuesta]
  J --> K[Auditoría de salida]
  K --> L[Respuesta al cliente]

3.2 Arquitectura de clases

mermaid

classDiagram
  class ServicesController {
    +GetBalance_v2(BaseRequestGetBalance_v2)
  }
  class ServiceBusiness {
    +GetBalance_v2(BaseRequest, string)
  }
  class ServiceUtil2 {
    +GetBalance(RequestModel, ServiceModel)
  }
  class GetBalanceRequest_v2 {
    +Audit Audit
    +string Phone
  }
  class GetBalanceResponse_v2 {
    +string Available_Coin
    +double? Available_Coin_Value
    +GetBalanceGroupDetailResponse_v2 Detailed
    +string Promotion_Coin
    +double? Promotion_Coin_Value
    +GetBalanceGroupResourceResponse_v2 Resume
  }
  ServicesController --> ServiceBusiness
  ServiceBusiness --> ServiceUtil2
  ServiceBusiness --> GetBalanceRequest_v2
  ServiceBusiness --> GetBalanceResponse_v2

3.3 Secuencia de ejecución

mermaid

sequenceDiagram
  participant Cliente
  participant ServicesController
  participant ServiceBusiness
  participant ServiceUtil2
  participant AuditUtil
  participant ConfigurationUtil
  
  Cliente->>ServicesController: POST /api/services/v2/getbalance
  ServicesController->>AuditUtil: Save_Request_Async (entrada)
  ServicesController->>ServiceBusiness: GetBalance_v2()
  ServiceBusiness->>ServiceBusiness: Validación de datos
  ServiceBusiness->>ServiceBusiness: Conversión de request
  ServiceBusiness->>ServiceBusiness: Obtención del origen
  ServiceBusiness->>ServiceUtil2: GetBalance()
  ServiceUtil2-->>ServiceBusiness: Datos del servicio
  ServiceBusiness->>ServiceBusiness: Procesamiento de saldos
  ServiceBusiness->>ConfigurationUtil: Get_Tipology("OK_01")
  ServiceBusiness->>AuditUtil: Save_Request_Async (salida)
  ServiceBusiness-->>ServicesController: BaseResponseGetBalance_v2
  ServicesController-->>Cliente: Respuesta JSON

Políticas y Consideraciones

Políticas de seguridad

Mecanismos de autenticación y autorización:

Validación de headers de autenticación para endpoints SOAP
Validación de token Bearer para endpoints REST
Validación de usuario MiETB para endpoints protegidos

Validaciones de seguridad implementadas:

Validación de IP de origen
Auditoría completa de todas las transacciones
Validación de datos de entrada
Sanitización de parámetros

Límites de tasa (rate limits):

No se implementan rate limits específicos
Se recomienda implementar throttling por IP/usuario

SLAs aplicables:

Tiempo de respuesta esperado: < 2 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 rate limiting para prevenir abuso del servicio
Agregar validación de formato de número telefónico
Implementar caché para consultas frecuentes del mismo número
Mejorar el manejo de excepciones con logging estructurado

Optimizaciones posibles:

Implementar paginación para respuestas con muchos recursos
Agregar compresión de respuesta para reducir ancho de banda
Implementar versionado de API más robusto
Agregar métricas de rendimiento y monitoreo

Consideraciones de mantenimiento importantes:

Mantener compatibilidad con versiones anteriores
Documentar cambios en la estructura de respuesta
Implementar tests automatizados para validar regresiones
Monitorear el uso de recursos del servicio

Sugerencias de seguridad aplicables:

Implementar autenticación OAuth 2.0
Agregar validación de JWT tokens
Implementar rate limiting por IP y usuario
Agregar logging de auditoría más detallado
Implementar encriptación de datos sensibles en tránsito

Consulta de Saldos de Línea Móvil - services-v2-getbalance ​

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 ​

Estructura de Detailed ​

Estructura de Detailed.Detail ​

Estructura de Detailed.Detail.Boxs ​

Estructura de Detailed.Detail.Boxs.Offers ​

Estructura de Resume ​

Estructura de Resume.Resource ​

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 Saldos de Línea Móvil - services-v2-getbalance

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

Estructura de Detailed

Estructura de Detailed.Detail

Estructura de Detailed.Detail.Boxs

Estructura de Detailed.Detail.Boxs.Offers

Estructura de Resume

Estructura de Resume.Resource

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