Obtener Formulario de Confronta - customers-v1-getformconfronta

Información del Servicio

Endpoint: /api/customers/v1/getformconfronta
Método: POST
Versión: v1
Categoría: Gestión de clientes

Documentación del Servicio

Descripción general

El servicio customers-v1-getformconfronta es un endpoint para obtener las preguntas de validación de identidad (confronta) de un cliente. Este servicio permite validar la identidad del cliente mediante un formulario de preguntas personalizadas basadas en su información crediticia y personal.

Categoría: Gestión de clientes.

Casos de uso principales:

Validación de identidad para trámites de cambio de plan
Verificación de cliente antes de realizar operaciones sensibles
Obtención de preguntas de confronta para autenticación
Validación de score crediticio del cliente

Especificación técnica

Endpoint completo: /api/customers/v1/getformconfronta
Método HTTP: POST
Capas involucradas:
- Controlador: CustomersController
- Lógica de negocio: CustomerBusiness
- Acceso a datos: CustomerUtil, LSIM

Flujo de procesamiento:

Validación de parámetros de entrada obligatorios
Obtención del origen y configuración del servicio
Consulta del cliente en la base de datos
Validación de características del producto para confronta
Obtención de preguntas desde el servicio LSIM
Actualización de fase para órdenes de venta LTE
Construcción de respuesta con preguntas o score

Dependencias principales:

CustomerUtil para consulta de clientes
LSIM para obtención de preguntas de confronta
ConfigurationUtil para validaciones de configuración
AuditUtil para auditoría de transacciones

Consideraciones de seguridad:

Validación de parámetros obligatorios
Auditoría completa de entrada y salida
Validación de origen de la petición
Control de acceso por configuración

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
Document_Number	string	Sí	Número de identificación del cliente
Document_Type	string	Sí	Tipo de identificación del cliente
Expedition_Date	string	Sí	Fecha de expedición del documento (dd/MM/yyyy)
Num_Order	string	No	Número de la orden de venta fija asociada
Process	string	Sí	Trámite asociado a la validación (ej: VTA, ACTIVA_SIM)
Product	string	Sí	Producto asociado (MOVIL o FIJA)
Sub_Process	string	Sí	Subtramite asociado (ej: PREPAGO, POSPAGO)
Surname	string	Sí	Primer apellido del cliente

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

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	No	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

Body

Campo	Tipo	Obligatorio	Descripción
Form_Id	string	No	Identificación del formulario de confronta
NeedConfronta	bool	No	Bandera que determina si el cliente requiere confronta
Questions	array	No	Lista de preguntas del formulario de confronta
Score_Customer	string	No	Score obtenido por el cliente en caso de validación reciente

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 Questions

Campo	Tipo	Obligatorio	Descripción
Question	string	No	Pregunta del formulario de confronta
Answers	array	No	Lista de respuestas asociadas a una pregunta

Estructura de Questions.Answers

Campo	Tipo	Obligatorio	Descripción
Answer	string	No	Respuesta asociada a una pregunta en el formulario de confronta

Manejo de errores

Código	Descripción	Ejemplo
ERROR_04	La solicitud no fue exitosa. Fueron enviados objetos no acordes a la petición	Parámetros obligatorios faltantes
ERROR_08	Cliente no encontrado	El cliente no existe en la base de datos
ERROR_09	Error en obtención de preguntas	No fue posible obtener las preguntas del servicio LSIM
ERROR_10	Mock activo	Servicio en modo de prueba

Análisis de Componentes

Modelos y componentes

Modelos base utilizados:

BaseRequestGetFormContronta
BaseResponseGetFormConfronta
GetFormControntaRequest
GetFormConfrontaResponse

Utilidades y servicios comunes:

CustomerUtil para consulta de clientes
LSIM para validación de identidad
ConfigurationUtil para configuraciones
AuditUtil para auditoría

Patrones de diseño implementados:

Singleton para CustomerBusiness
Factory para creación de respuestas
Strategy para diferentes tipos de validación

Componentes reutilizados:

BotBaseRequestHeader/ResponseHeader
Audit para auditoría
ResultModel para manejo de errores

Referencias cruzadas:

ReplyFormConfronta_v1 para responder preguntas
CustomerBusiness para lógica de negocio
LSIM para servicio de validación

Ejemplos de Request/Response

Solicitud (request)

json

{
  "WSRequestHeader": {
    "System": {
      "name": "MAX",
      "correlationID": "LUZ-0.4384614908304255",
      "processingServer": null
    },
    "Property": [
      {
        "name": null,
        "value": null
      }
    ]
  },
  "WSRequestBody": {
    "Document_Type": "CC",
    "Document_Number": "80008820",
    "Expedition_Date": "10/09/1997",
    "Surname": "Perez",
    "Min_Score": "0",
    "Product": "FIJA",
    "Process": "PRCH_FJ_WEB",
    "Sub_Process": "UPGRADE",
    "Audit": {
      "Canal": "whatsapp",
      "IP_Address": "169.60.82.89",
      "IP_Latitud": "4.8094",
      "IP_Longitude": "-74.0980",
      "IP_City": "COTA",
      "IP_Country": "COLOMBIA",
      "Date": "2025-08-04",
      "Hour": "09:46:51",
      "WhatsApp_Phone_Number": "",
      "Facebook_User": "",
      "Twitter_User": ""
    }
  }
}

Respuesta exitosa

json

{
  "WSResponseHeader": {
    "System": {
      "name": "MAX",
      "correlationID": "LUZ-0.4384614908304255",
      "processingServer": null
    },
    "Service": {
      "status": "OK",
      "responseDate": "2025-08-04T09:46:51.9759664Z",
      "processingServer": null,
      "statusDetail": [
        {
          "errorCode": "OK_01",
          "errorDetailCode": "La solicitud LUZ-0.4384614908304255 fue exitosa",
          "errorMessage": "Se obtuvieron las preguntas de validación confronta",
          "errorMessageUser": null
        }
      ]
    },
    "Property": [
      {
        "name": null,
        "value": null
      },
      {
        "name": null,
        "value": null
      }
    ]
  },
  "WSResponseBody": {
    "Form_Id": "3336463",
    "NeedConfronta": true,
    "Questions": [
      {
        "Answers": [
          {
            "Answer": "SI"
          },
          {
            "Answer": "NO"
          }
        ],
        "Question": "¿En algún momento usted ha tenido línea celular con MOVISTAR?"
      },
      {
        "Answers": [
          {
            "Answer": "COOMEVA COOPERATIVA FINANCIERA"
          },
          {
            "Answer": "BANAGRARIO"
          },
          {
            "Answer": "BBVA"
          },
          {
            "Answer": "Ninguna de las anteriores"
          }
        ],
        "Question": "¿Con cuál de las siguientes entidades usted tiene una cuenta de ahorros?"
      },
      {
        "Answers": [
          {
            "Answer": "3118769816"
          },
          {
            "Answer": "3125584253"
          },
          {
            "Answer": "3143700537"
          },
          {
            "Answer": "Ninguno de los anteriores"
          }
        ],
        "Question": "¿Con cuál de los siguientes números de teléfono tiene o ha tenido relación?"
      },
      {
        "Answers": [
          {
            "Answer": "ESTAR COMO DEUDOR PRINCIPAL DE LA OBLIGACIÓN"
          },
          {
            "Answer": "ESTAR COMO CODEUDOR, FIADOR, DEUDOR SOLIDARIO Ó AVALISTA DE LA OBLIGACIÓN"
          },
          {
            "Answer": "No estoy relacionado en ningún crédito de vivienda con esta entidad actualmente"
          }
        ],
        "Question": "En su crédito de vivienda con BBVA, su relación con la obligación es:"
      },
      {
        "Answers": [
          {
            "Answer": "MASTER CARD"
          },
          {
            "Answer": "VISA"
          },
          {
            "Answer": "DINERS"
          },
          {
            "Answer": "Ninguna de las anteriores"
          }
        ],
        "Question": "¿De qué marca es su tarjeta de crédito con BBVA?"
      }
    ],
    "Score_Customer": "0"
  }
}

Respuesta de error

json

{
    "WSResponseHeader": {
        "System": {
            "name": "KIOSKOS",
            "correlationID": "KIOSKOS-11072022158",
            "processingServer": "SERVER01"
        },
        "Service": {
            "status": "FAIL",
            "responseDate": "2024-12-19T10:30:00",
            "processingServer": "SERVER01",
            "statusDetail": [
                {
                    "errorCode": "ERROR_08",
                    "message": "Cliente no encontrado"
                }
            ]
        },
        "Property": []
    },
    "WSResponseBody": null
}

Diagramas Técnicos

3.1 Flujo de datos

mermaid

graph TD
  A[Recepción de la solicitud] --> B[CustomersController]
  B --> C[CustomerBusiness.GetFormConfronta_v1]
  C --> D[Validación de parámetros]
  D --> E[Obtención de origen]
  E --> F[Consulta de cliente]
  F --> G[Validación de producto]
  G --> H[Obtención de preguntas LSIM]
  H --> I[Construcción de respuesta]
  I --> J[Auditoría de salida]
  J --> K[Respuesta al cliente]

3.2 Arquitectura de clases

mermaid

classDiagram
  class CustomersController {
    +GetFormConfronta_v1()
  }
  class CustomerBusiness {
    +GetFormConfronta_v1()
  }
  class CustomerUtil {
    +Get()
    +Get_Form_Confronta()
  }
  class LSIM {
    +GetQuestions()
  }
  CustomersController --> CustomerBusiness
  CustomerBusiness --> CustomerUtil
  CustomerBusiness --> LSIM

3.3 Secuencia de ejecución

mermaid

sequenceDiagram
  participant Cliente
  participant CustomersController
  participant CustomerBusiness
  participant CustomerUtil
  participant LSIM
  participant AuditUtil
  Cliente->>CustomersController: POST /api/customers/v1/getformconfronta
  CustomersController->>CustomerBusiness: GetFormConfronta_v1()
  CustomerBusiness->>AuditUtil: Save_Request (entrada)
  CustomerBusiness->>CustomerUtil: Get()
  CustomerUtil-->>CustomerBusiness: Customer
  CustomerBusiness->>LSIM: Get_Form_Confronta()
  LSIM-->>CustomerBusiness: Questions/Score
  CustomerBusiness->>AuditUtil: Save_Request (salida)
  CustomerBusiness-->>CustomersController: BaseResponseGetFormConfronta
  CustomersController-->>Cliente: Response

Evaluación TM Forum

Categorización TM Forum

Categoría TM Forum sugerida: Customer Management

TMF_ID correspondiente: TMF620

Justificación de la selección: Este servicio se alinea con la categoría Customer Management de TM Forum ya que maneja la validación de identidad de clientes mediante confronta, que es un componente fundamental de la gestión de clientes en telecomunicaciones. El servicio obtiene preguntas de validación personalizadas basadas en información crediticia del cliente, lo cual es parte del proceso de autenticación y verificación de identidad requerido en la gestión de relaciones con clientes (CRM).

Políticas y Consideraciones

Políticas de seguridad

Mecanismos de autenticación y autorización:

Validación de parámetros obligatorios en el request
Verificación de origen de la petición
Auditoría completa de transacciones

Validaciones de seguridad implementadas:

Validación de tipo y número de documento
Verificación de fecha de expedición
Control de acceso por configuración de API

Límites de tasa (rate limits):

Controlado por configuración de origen
Validación de intentos por cliente

SLAs aplicables:

Tiempo de respuesta: < 5 segundos
Disponibilidad: 99.9%

Recomendaciones y mejores prácticas

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

Implementar cache para preguntas frecuentes
Optimizar consultas a base de datos
Mejorar manejo de errores específicos

Optimizaciones posibles:

Paralelizar consultas a servicios externos
Implementar circuit breaker para LSIM
Agregar métricas de rendimiento

Consideraciones de mantenimiento importantes:

Monitoreo de respuestas del servicio LSIM
Validación periódica de configuraciones
Revisión de logs de auditoría

Sugerencias de seguridad aplicables:

Implementar rate limiting por IP
Agregar validación de tokens JWT
Encriptar datos sensibles en logs

Obtener Formulario de Confronta - customers-v1-getformconfronta ​

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

Estructura de Questions.Answers ​

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 ​

Evaluación TM Forum ​

Categorización TM Forum ​

Políticas y Consideraciones ​

Políticas de seguridad ​

Recomendaciones y mejores prácticas ​

Obtener Formulario de Confronta - customers-v1-getformconfronta

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 Questions

Estructura de Questions.Answers

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

Evaluación TM Forum

Categorización TM Forum

Políticas y Consideraciones

Políticas de seguridad

Recomendaciones y mejores prácticas