Consulta integral de cliente por tipo y número de documento - customers-v3-get

Información del Servicio

Endpoint: /api/customers/v3/get
Método: POST
Versión: v3
Categoría: Clientes / Gestión de Clientes

1. Documentación del Servicio

Descripción general

Este servicio permite consultar la información completa de un cliente a partir de su tipo y número de documento. Devuelve datos personales, direcciones, contactos, cuentas de facturación, servicios asociados, estado, información de MiETB y más.
Categoría de negocio: Gestión de clientes y servicios.
Casos de uso principales:

Obtener información detallada de un cliente para procesos de atención, soporte o ventas.
Integrar datos de cliente en portales de autoservicio, CRM o canales digitales.
Validar la existencia y estado de un cliente antes de realizar operaciones.

Especificación técnica

Endpoint: /api/customers/v3/get
Método HTTP: POST
Capas involucradas:
- Controlador: CustomersController (método Get_v3)
- Lógica de negocio: CustomerBusiness.Get_v3
- Acceso a datos: Utilidades de clientes y configuración (CustomerUtil2, ConfigurationUtil)
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 obtiene el origen y tipologías de la operación.
5. Se valida si el endpoint está habilitado.
6. Se consulta el cliente por tipo y número de documento.
7. Se retorna la información completa del cliente.
8. Se audita la salida y retorna la respuesta.
Dependencias principales:
- Modelos: BaseRequestGet_v3, GetRequest_v3, BaseResponseGet_v3, GetResponse_v3, CustomerModel
- Utilidades: AuditUtil, CustomerUtil2, 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
Document_Number	string	Sí	Número de documento del cliente
Document_Type	string	Sí	Tipo de documento del cliente
Filter	objeto	No	Filtros de búsqueda para limitar la información

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
Customer	objeto	Sí	Información completa del cliente

Customer (CustomerModel)

Campo	Tipo	Obligatorio	Descripción
Address	string	No	Dirección principal del cliente
Addresses	array	No	Listado de direcciones asociadas
Billings	array	No	Cuentas de facturación asociadas
City	objeto	No	Ciudad asociada
Civil_Status	string	No	Estado civil
Contacts	array	No	Contactos asociados
Creation_Date	objeto	No	Fecha de creación
Customer_Type	string	No	Tipo de cliente
Department	objeto	No	Departamento asociado
Directv_Subscription	objeto	No	Subscripción de Directv
Gender	string	No	Género
Habeas_Data	objeto	No	Decisión de tratamiento de datos personales
MiETBUser	objeto	No	Información de la cuenta MiETB
Phone	string	No	Teléfono del cliente
Services	array	No	Servicios asociados
State	string	No	Estado del cliente
Update_Date	objeto	No	Fecha de actualización
...	...	...	Hereda campos de Basic_Customer

Manejo de errores

Código	Descripción	Ejemplo
ERROR_04	Request nulo o mal formado	"El request es nulo"
ERROR_08	No existe cliente asociado	"No se encontró cliente para los datos"
BOTERROR	Excepción no controlada	"se ha generado una excepcion no controlada"

2. Análisis de Componentes

Modelos y componentes

Modelos base utilizados:
- BaseRequestGet_v3
- GetRequest_v3
- BaseResponseGet_v3
- GetResponse_v3
- CustomerModel
- BotBaseRequestHeader, BotBaseResponseHeader
Utilidades y servicios comunes:
- AuditUtil (auditoría de entrada/salida)
- CustomerUtil2 (consulta de clientes)
- 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 clientes.
- Utilidades de auditoría y consulta de clientes.
Referencias cruzadas:
- Endpoint /api/customers/v1/get y /api/customers/v2/get para otras versiones de consulta de cliente.
- Otros endpoints de clientes para actualización, validación y gestión de datos.

Ejemplos de Request/Response

Solicitud (request)

json

{
  "WSRequestHeader": {
    "System": {
      "Name": "KIOSKOS",
      "CorrelationID": "KIOSKOS-21062022-045820",
      "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": ""
    },
    "Document_Number": "98302931",
    "Document_Type": "CC",
    "Filter": null
  }
}

Respuesta exitosa

json

{
  "WSResponseHeader": {
    "System": {
      "Name": "KIOSKOS",
      "CorrelationID": "KIOSKOS-21062022-045820",
      "ProcessingServer": "server-01"
    },
    "Service": {
      "Status": "OK",
      "ResponseDate": "2024-06-01T12:34:56Z",
      "ProcessingServer": "server-01",
      "StatusDetail": [
        {
          "ErrorCode": "OK_01",
          "ErrorDetailCode": "Consulta exitosa",
          "ErrorMessage": "Cliente encontrado",
          "ErrorMessageUser": "Cliente consultado correctamente"
        }
      ]
    },
    "Property": []
  },
  "WSResponseBody": {
    "Customer": {
      "Address": "Calle 123 #45-67",
      "Addresses": [
        { "Street": "Calle 123 #45-67", "City": "Bogotá" }
      ],
      "Billings": [
        { "Billing_Account": "15052876387", "State": "ACTIVO" }
      ],
      "City": { "Name": "Bogotá" },
      "Civil_Status": "Soltero",
      "Contacts": [
        { "Type": "Móvil", "Value": "3001234567" }
      ],
      "Creation_Date": { "Date": "2020-01-01T00:00:00Z" },
      "Customer_Type": "Hogar",
      "Department": { "Name": "Cundinamarca" },
      "Directv_Subscription": null,
      "Gender": "M",
      "Habeas_Data": { "Decision": "Autorizado" },
      "MiETBUser": { "User": "usuario@ejemplo.com" },
      "Phone": "3001234567",
      "Services": [
        { "Phone": "3001234567", "State": "ACTIVO" }
      ],
      "State": "ACTIVO",
      "Update_Date": { "Date": "2024-05-01T00:00:00Z" }
    }
  }
}

Respuesta de error

json

{
  "WSResponseHeader": {
    "System": {
      "Name": "KIOSKOS",
      "CorrelationID": "KIOSKOS-21062022-045820",
      "ProcessingServer": "server-01"
    },
    "Service": {
      "Status": "ERROR",
      "ResponseDate": "2024-06-01T12:35:00Z",
      "ProcessingServer": "server-01",
      "StatusDetail": [
        {
          "ErrorCode": "ERROR_08",
          "ErrorDetailCode": "No se encontró cliente para los datos",
          "ErrorMessage": "No existe cliente asociado",
          "ErrorMessageUser": "No se encontró información para el cliente ingresado."
        }
      ]
    },
    "Property": []
  },
  "WSResponseBody": null
}

3. Diagramas Técnicos

3.1 Flujo de datos

mermaid

graph TD
  A["Cliente/API Consumer"] --> B["CustomersController"]
  B --> C["CustomerBusiness"]
  C --> D["CustomerUtil2 (Consulta Cliente)"]
  C --> E["ConfigurationUtil (Tipologías)"]
  C --> F["AuditUtil (Auditoría)"]
  D --> G["Base de datos"]

3.2 Arquitectura de clases

mermaid

classDiagram
  class CustomersController {
    +Get_v3(request)
  }
  class CustomerBusiness {
    +Get_v3(request, name)
  }
  class BaseRequestGet_v3
  class GetRequest_v3
  class BaseResponseGet_v3
  class GetResponse_v3
  class CustomerModel
  class BotBaseRequestHeader
  class BotBaseResponseHeader

  CustomersController --> CustomerBusiness
  CustomersController --> BaseRequestGet_v3
  BaseRequestGet_v3 --> GetRequest_v3
  CustomerBusiness --> BaseResponseGet_v3
  BaseResponseGet_v3 --> GetResponse_v3
  GetResponse_v3 --> CustomerModel
  BaseResponseGet_v3 --> BotBaseResponseHeader
  BotBaseRequestHeader <.. BaseRequestGet_v3

3.3 Secuencia de ejecución

mermaid

sequenceDiagram
  participant Cliente
  participant API as CustomersController
  participant Negocio as CustomerBusiness
  participant Clientes as CustomerUtil2
  participant Config as ConfigurationUtil
  participant Auditoria as AuditUtil

  Cliente->>API: POST /api/customers/v3/get
  API->>Negocio: Get_v3(request)
  Negocio->>Auditoria: Save_Request(entrada)
  Negocio->>Config: Get_Origin
  Negocio->>Clientes: GetById
  Clientes-->>Negocio: Datos de cliente
  Negocio->>Auditoria: Save_Request(salida)
  Negocio-->>API: BaseResponseGet_v3
  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 cliente y el estado.
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 mal formados.
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.

Consulta integral de cliente por tipo y número de documento - customers-v3-get ​

1. 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 ​

2. Análisis de Componentes ​

Modelos y componentes ​

Ejemplos de Request/Response ​

Solicitud (request) ​

Respuesta exitosa ​

Respuesta de error ​

3. Diagramas Técnicos ​

3.1 Flujo de datos ​

3.2 Arquitectura de clases ​

3.3 Secuencia de ejecución ​

4. Políticas y Consideraciones ​

Políticas de seguridad ​

Recomendaciones y mejores prácticas ​

Consulta integral de cliente por tipo y número de documento - customers-v3-get

1. 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

2. Análisis de Componentes

Modelos y componentes

Ejemplos de Request/Response

Solicitud (request)

Respuesta exitosa

Respuesta de error

3. Diagramas Técnicos

3.1 Flujo de datos

3.2 Arquitectura de clases

3.3 Secuencia de ejecución

4. Políticas y Consideraciones

Políticas de seguridad

Recomendaciones y mejores prácticas