Consulta Avanzada de Facturas de Servicios - services-v4-getinvoices

Información del Servicio

Endpoint:  /api/services/v4/getinvoices
Método:  POST
Versión: v4
Categoría: Servicios / Facturación

1. Documentación del Servicio

Descripción general

Este servicio permite consultar las facturas asociadas a un servicio, soportando filtros por número de conexión, cuenta de facturación, número de factura o código de barras. Devuelve la factura pendiente de pago (si existe), las últimas facturas, información de pagos a cuotas y ajustes aplicados.
Categoría de negocio: Facturación y gestión de servicios.
Casos de uso principales:

• Consultar facturas pendientes y pagadas de un servicio.
• Obtener detalle de pagos a cuotas y ajustes aplicados a facturas.
• Integrar información de facturación en portales de autoservicio, kioskos o canales digitales.
• Facilitar la gestión de pagos y seguimiento de obligaciones.

Especificación técnica

• Endpoint: /api/services/v4/getinvoices
• Método HTTP: POST
• Capas involucradas:
  • Controlador: ServicesController (método GetInvoices_v4)
  • Lógica de negocio: ServiceBusiness.GetInvoices_v4
  • Acceso a datos: Utilidades de facturación y servicios (BillingUtil, ServiceUtil)
• Flujo de procesamiento:
  1. El controlador recibe la petición y construye el request estándar.
  2. Se audita la entrada.
  3. Se valida la estructura y datos del request.
  4. Se determina el filtro de consulta (número, cuenta, factura, código de barras).
  5. Se consulta la información de facturación asociada.
  6. Se identifican facturas pendientes y se ordenan las últimas facturas.
  7. Se incluye información de pagos a cuotas y ajustes si aplica.
  8. Se audita la salida y retorna la respuesta.
• Dependencias principales:
  • Modelos: BaseRequestGetInvoices_v4, GetInvoiceRequest_v4, BaseResponseGetInvoices_v4, GetInvoicesResponse_v4, GetInvoicesItemResponse_v4, GetInvoicesPaymentResponse_v4, GetInvoicesInfoCuota_v4, GetInvoicesAdjustResponse_v4, GetInvoicesValueResponse_v4
  • Utilidades: AuditUtil, BillingUtil, ServiceUtil, ConfigurationUtil
• Seguridad y autenticación:
  • Requiere autenticación (atributo [Authorize] en el controlador).
  • Valida cabecera de sistema y canal.
  • Control de acceso por roles y origen.

Parámetros de entrada (Request)

Headers

Campo	Tipo	Obligatorio	Descripción
System.Name	string	Sí	Nombre del sistema que realiza la petición
System.CorrelationID	string	Sí	Identificador único de la transacción
System.ProcessingServer	string	Sí	Servidor de procesamiento
Property	array	No*	Propiedades adicionales de la petición

*Opcional, pero puede ser requerido según integración.

Body

Campo	Tipo	Obligatorio	Descripción
Audit	objeto	Sí	Información de auditoría de la operación
Barcode	string	No*	Código de barras de la factura
Billing_Account	string	No*	Cuenta de facturación
Billing_Number	string	No*	Número de la factura
Phone	string	No*	Número de conexión

*Al menos uno de estos campos debe estar presente.

Respuesta esperada (Response)

Headers

Campo	Tipo	Obligatorio	Descripción
System.Name	string	Sí	Nombre del sistema que responde
System.CorrelationID	string	Sí	Identificador único de la transacción
System.ProcessingServer	string	Sí	Servidor de procesamiento
Service.Status	string	Sí	Estado de la ejecución (OK/ERROR)
Service.ResponseDate	datetime	Sí	Fecha de la respuesta
Service.ProcessingServer	string	Sí	Servidor de procesamiento
Service.StatusDetail	array	Sí	Detalles de estado y errores
Property	array	No	Propiedades adicionales

• StatusDetail (array de objetos)

  Campo	Tipo	Obligatorio	Descripción
  ErrorCode	string	Sí	Código de error o estado
  ErrorDetailCode	string	No	Detalle funcional del error
  ErrorMessage	string	No	Mensaje técnico
  ErrorMessageUser	string	No	Mensaje para el usuario

Body

Campo	Tipo	Obligatorio	Descripción
Pending_Invoice	objeto	No*	Factura pendiente de pago
Invoices	array	Sí	Listado de facturas asociadas

*Solo si existe factura pendiente.

• Pending_Invoice / Invoices[] (GetInvoicesItemResponse_v4)

  Campo	Tipo	Obligatorio	Descripción
  Adjust	objeto	No	Información de ajuste aplicado a la factura
  Barcode	string	Sí	Código de barras del pago
  Billed_Period	string	Sí	Periodo facturado
  Billing_Account	string	Sí	Cuenta de facturación
  Billing_Address	string	No	Dirección de facturación
  Billing_Cutoff_Date	string	No	Fecha de corte de facturación
  Billing_Phone	string	No	Celular asociado a la facturación
  Billing_Number	string	Sí	Número de la factura
  Billing_Number_PSE	string	No	Número de la factura para PSE
  Cuotas_Factura	array	No	Detalle de pagos a cuotas
  Creation_Date	datetime	No	Fecha de registro de la factura
  Delivery_Type	string	No	Tipo de entrega de la factura
  Email	string	No	Correo electrónico de facturación
  Extemporaneous	bool	No	Indica si el pago es extemporáneo
  Information_Value	array	No	Mensajes informativos sobre el valor a pagar
  Invoice_Origin	string	No	Origen de la factura
  Is_Receipt_Of_Payment	bool	No	Indica si es un recibo de pago
  Payday_Limit	datetime	No	Fecha límite de pago
  Payment	objeto	No	Información de pago de la factura
  Payment_Date	datetime	No	Fecha de pago
  Phone	string	No	Número de conexión
  State	string	Sí	Estado de la factura
  Value_Final	objeto	Sí	Valor final de la factura
  Value_Original	objeto	Sí	Valor original de la factura
  Value_Previous	objeto	No	Valor del mes anterior
  Value_Service	objeto	No	Valor del servicio (plan + opcionales)

• Cuotas_Factura[] (GetInvoicesInfoCuota_v4)

  Campo	Tipo	Obligatorio	Descripción
  Cuota	string	Sí	Número de la cuota
  Estado	string	Sí	Estado de la cuota
  Fecha_Pago_Cuota	string	No	Fecha de pago de la cuota
  Fecha_Vencimiento	string	No	Fecha límite para pago de la cuota
  Referencia_Pago_Cuota	string	No	Referencia de pago para la cuota
  Valor_Acumulado	string	No	Valor acumulado
  Valor_Pagado	string	No	Valor pagado
  Valor_Pagar	string	No	Valor a pagar

• Payment (GetInvoicesPaymentResponse_v4)

  Campo	Tipo	Obligatorio	Descripción
  Bank	string	No	Banco donde se realizó el pago
  Franchise	string	No	Franquicia utilizada
  Payment_Date	datetime	No	Fecha de pago
  State	string	No	Estado del pago
  Type	string	No	Tipo de pago (Presencial/Digital)
  Value	number	No	Valor recaudado
  Value_Str	string	No	Valor recaudado en formato moneda
  Visible_Number	string	No	Número visible de la tarjeta

• Adjust (GetInvoicesAdjustResponse_v4)

  Campo	Tipo	Obligatorio	Descripción
  Date	datetime	No	Fecha del ajuste
  Num_PQR	string	No	Número de PQR asociado al ajuste
  Origin	string	No	Origen del ajuste
  Value	number	No	Valor del ajuste
  Value_Str	string	No	Valor del ajuste en formato moneda

• Value_Final / Value_Original / Value_Previous / Value_Service (GetInvoicesValueResponse_v4)

  Campo	Tipo	Obligatorio	Descripción
  Tens_Setting	number	No	Ajuste de decenas
  Value	number	Sí	Valor total a pagar
  Value_Str	string	Sí	Valor total a pagar en formato moneda
  Value_Pay	number	No	Valor del mes
  Value_Pay_Str	string	No	Valor del mes en formato moneda

• Information_Value[] (GetInvoicesInformationItemResponse_v4)

  Campo	Tipo	Obligatorio	Descripción
  Date	datetime	No	Fecha del mensaje
  Message	string	Sí	Mensaje informativo

Manejo de errores

Código	Descripción	Ejemplo
ERROR_04	Request nulo o sin filtros válidos	"El request es nulo o no contiene filtros"
ERROR_06	No existe servicio asociado	"No se encontró servicio para el filtro"
ERROR_07	No existen facturas asociadas	"No se encontraron facturas"
BOTERROR	Excepción no controlada	"se ha generado una excepcion no controlada"

2. Análisis de Componentes

Modelos y componentes

• Modelos base utilizados:
  • BaseRequestGetInvoices_v4
  • GetInvoiceRequest_v4
  • BaseResponseGetInvoices_v4
  • GetInvoicesResponse_v4
  • GetInvoicesItemResponse_v4
  • GetInvoicesPaymentResponse_v4
  • GetInvoicesInfoCuota_v4
  • GetInvoicesAdjustResponse_v4
  • GetInvoicesValueResponse_v4
  • GetInvoicesInformationItemResponse_v4
  • BotBaseRequestHeader, BotBaseResponseHeader
• Utilidades y servicios comunes:
  • AuditUtil (auditoría de entrada/salida)
  • BillingUtil (consulta y procesamiento de facturas)
  • ServiceUtil (consulta de servicios)
  • ConfigurationUtil (tipologías y control de endpoint)
• Patrones de diseño:
  • Singleton para utilidades de negocio y auditoría.
  • Separación de capas (controlador, negocio, datos).
• Componentes reutilizados:
  • Modelos de request/response estándar en otros endpoints de facturación.
  • Utilidades de auditoría y consulta de servicios.
• Referencias cruzadas:
  • Endpoint /api/services/v4/requestinvoice para obtener el archivo PDF/URL de la factura.
  • Otros endpoints de facturación para consulta y gestión de pagos.

Ejemplos de Request/Response

Solicitud (request)

{
  "WSRequestHeader": {
    "System": {
      "Name": "KIOSKOS",
      "CorrelationID": "LUZ-21062022-05000545",
      "ProcessingServer": "server-01"
    },
    "Property": [
      { "Name": "CANAL", "Value": "KIOSKOS" }
    ]
  },
  "WSRequestBody": {
    "Audit": {
      "Canal": "KIOSKOS",
      "Id_Device": null,
      "SO": null,
      "IP_Address": "169.60.82.89",
      "IP_Latitude": null,
      "IP_Longitude": "-74.0980",
      "WhatsApp_Phone_Number": "",
      "Facebook_User": "",
      "Twitter_User": ""
    },
    "Barcode": null,
    "Billing_Account": "15052876387",
    "Billing_Number": null,
    "Phone": null
  }
}

Respuesta exitosa

{
  "WSRequestHeader": {
    "System": {
      "name": "LUZ",
      "correlationID": "LUZ-0.9089321304002383",
      "processingServer": "PRD"
    },
    "Property": []
  },
  "WSRequestBody": {
    "Billing_Account": "",
    "Phone": "3111576555",
    "Barcode": "",
    "Billing_Number": "",
    "Audit": {
      "Canal": "whatsapp",
      "Id_Device": "",
      "SO": ""
    }
  }
}

Respuesta de error

{
  "WSResponseHeader": {
    "System": {
      "name": "LUZ",
      "correlationID": "LUZ-0.9089321304002383",
      "processingServer": "PRD"
    },
    "Service": {
      "status": "OK",
      "responseDate": "2025-04-16T22:58:08.5073084Z",
      "processingServer": null,
      "statusDetail": [
        {
          "errorCode": "OK_02",
          "errorDetailCode": "No se encontraron facturas del servicio",
          "errorMessage": "La solicitud LUZ-0.9089321304002383 fue exitosa",
          "errorMessageUser": null
        }
      ]
    },
    "Property": []
  },
  "WSResponseBody": null
}

3. Diagramas Técnicos

3.1 Flujo de datos

graph TD
  A["Cliente/API Consumer"] --> B["ServicesController"]
  B --> C["ServiceBusiness"]
  C --> D["BillingUtil (Facturación)"]
  C --> E["ServiceUtil (Servicios)"]
  C --> F["AuditUtil (Auditoría)"]
  D --> G["Base de datos"]
  E --> G

3.2 Arquitectura de clases

classDiagram
  class ServicesController {
    +GetInvoices_v4(request)
  }
  class ServiceBusiness {
    +GetInvoices_v4(request, name)
  }
  class BaseRequestGetInvoices_v4
  class GetInvoiceRequest_v4
  class BaseResponseGetInvoices_v4
  class GetInvoicesResponse_v4
  class GetInvoicesItemResponse_v4
  class GetInvoicesPaymentResponse_v4
  class GetInvoicesInfoCuota_v4
  class GetInvoicesAdjustResponse_v4
  class GetInvoicesValueResponse_v4
  class GetInvoicesInformationItemResponse_v4
  class BotBaseRequestHeader
  class BotBaseResponseHeader

  ServicesController --> ServiceBusiness
  ServicesController --> BaseRequestGetInvoices_v4
  BaseRequestGetInvoices_v4 --> GetInvoiceRequest_v4
  ServiceBusiness --> BaseResponseGetInvoices_v4
  BaseResponseGetInvoices_v4 --> GetInvoicesResponse_v4
  GetInvoicesResponse_v4 --> GetInvoicesItemResponse_v4
  GetInvoicesItemResponse_v4 --> GetInvoicesPaymentResponse_v4
  GetInvoicesItemResponse_v4 --> GetInvoicesInfoCuota_v4
  GetInvoicesItemResponse_v4 --> GetInvoicesAdjustResponse_v4
  GetInvoicesItemResponse_v4 --> GetInvoicesValueResponse_v4
  GetInvoicesItemResponse_v4 --> GetInvoicesInformationItemResponse_v4
  BaseResponseGetInvoices_v4 --> BotBaseResponseHeader
  BotBaseRequestHeader <.. BaseRequestGetInvoices_v4

3.3 Secuencia de ejecución

sequenceDiagram
  participant Cliente
  participant API as ServicesController
  participant Negocio as ServiceBusiness
  participant Facturacion as BillingUtil
  participant Servicios as ServiceUtil
  participant Auditoria as AuditUtil

  Cliente->>API: POST /api/services/v4/getinvoices
  API->>Negocio: GetInvoices_v4(request)
  Negocio->>Auditoria: Save_Request(entrada)
  Negocio->>Servicios: Consultar servicio/filtro
  Servicios-->>Negocio: Datos de servicio
  Negocio->>Facturacion: Consultar facturas
  Facturacion-->>Negocio: Listado de facturas
  Negocio->>Auditoria: Save_Request(salida)
  Negocio-->>API: BaseResponseGetInvoices_v4
  API-->>Cliente: WSResponseHeader + WSResponseBody

4. Políticas y Consideraciones

Políticas de seguridad

• Autenticación: Requiere autenticación mediante [Authorize] en el controlador.
• Validaciones: Se valida la estructura del request, la existencia del servicio y de facturas.
• Auditoría: Todas las operaciones son auditadas (entrada y salida).
• Rate limits: No explícitos en el código, pero el control de acceso y origen actúa como limitador.
• SLA: No especificado en el código fuente, depende de la política de la plataforma.

Recomendaciones y mejores prácticas

• Validar exhaustivamente los datos de entrada para evitar requests nulos o sin filtros válidos.
• Centralizar la gestión de errores para mensajes más claros y homogéneos.
• Implementar rate limits explícitos si se detectan abusos o automatizaciones no deseadas.
• Monitorear el uso del endpoint para detectar patrones anómalos o intentos de acceso indebido.
• Mantener actualizada la documentación de los modelos y flujos, ya que el endpoint depende de varios componentes reutilizables.
• Revisar y actualizar las tipologías de error para alinearlas con la experiencia de usuario y necesidades de negocio.

---