WhatsApp v1 GetByPhone - Consulta de Clientes por Teléfono

Información del Servicio

Endpoint: /api/whatsapp/v1/getbyphone
Método: POST
Versión: v1
Categoría: Atención y Soporte

Documentación del Servicio

Descripción general

El servicio whatsapp-v1-getbyphone permite consultar los datos básicos de un cliente mediante el número de teléfono utilizado para acceder a los servicios de MAX WhatsApp. Este servicio pertenece a la categoría de Gestión de Clientes Digitales y forma parte del ecosistema de servicios de WhatsApp Business de ETB.

Casos de Uso Principales

Consulta de información de clientes registrados en el canal digital WhatsApp
Validación de existencia de registros digitales por número de teléfono
Obtención de datos básicos del cliente para procesos de autenticación y validación
Integración con sistemas MAX para gestión de usuarios WhatsApp

Especificación Técnica

Capas involucradas:

Controlador: WhatsAppController.GetByPhone_v1() - Maneja la recepción de la petición HTTP
Lógica de negocio: WhatsAppBusiness.GetByPhone_v1() - Procesa la lógica principal del servicio
Acceso a datos: WhatsAppUtil.Get() - Consulta la base de datos MongoDB
Auditoría: AuditUtil - Registra transacciones y métricas

Flujo de procesamiento:

Recepción de petición HTTP POST
Validación de autenticación y autorización
Conversión de datos de entrada
Obtención del origen de la petición
Consulta del registro digital por número de teléfono
Construcción de respuesta
Auditoría de transacción
Retorno de respuesta

Dependencias principales:

WhatsAppUtil - Utilidades específicas de WhatsApp
ConfigurationUtil - Gestión de configuraciones y tipologías
AuditUtil - Auditoría de transacciones
CRUD_MDM_REGISTRO_DIGITAL - Acceso a datos de registros digitales
MongoContext - Conexión a base de datos MongoDB

Consideraciones de Seguridad

Autenticación mediante atributo [Authorize]
Validación de origen de petición
Auditoría completa de transacciones
Validación de parámetros de entrada

Parámetros de Entrada (Request)

Headers

Campo	Tipo	Obligatorio	Descripción
Authorization	string	Sí	Token de autenticación Bearer
Content-Type	string	Sí	application/json

Body

Campo	Tipo	Obligatorio	Descripción
WSRequestHeader	object	Sí	Cabecera estándar de la petición
WSRequestBody	object	Sí	Cuerpo de la petición con datos específicos

WSRequestHeader

Campo	Tipo	Obligatorio	Descripción
System	object	Sí	Información del sistema origen
CorrelationID	string	Sí	Identificador único de correlación
Timestamp	datetime	Sí	Marca de tiempo de la petición

WSRequestBody

Campo	Tipo	Obligatorio	Descripción
Audit	object	No	Información de auditoría
Phone	string	Sí	Número de teléfono usado en MAX WhatsApp

Audit

Campo	Tipo	Obligatorio	Descripción
User	string	No	Usuario que realiza la petición
Channel	string	No	Canal de origen
Application	string	No	Aplicación origen

Respuesta Esperada (Response)

Headers

Campo	Tipo	Obligatorio	Descripción
Content-Type	string	Sí	application/json
Status	string	Sí	Código de estado HTTP

Body

Campo	Tipo	Obligatorio	Descripción
WSResponseHeader	object	Sí	Cabecera estándar de la respuesta
WSResponseBody	object	Sí	Cuerpo de la respuesta con datos del cliente

WSResponseHeader

Campo	Tipo	Obligatorio	Descripción
Service	object	Sí	Información del estado del servicio
CorrelationID	string	Sí	Identificador de correlación de la petición
Timestamp	datetime	Sí	Marca de tiempo de la respuesta

WSResponseBody

Campo	Tipo	Obligatorio	Descripción
Customer	object	Sí	Información del cliente
Access	object	Sí	Información del canal de acceso

Customer

Campo	Tipo	Obligatorio	Descripción
Document_Type	string	Sí	Tipo de documento de identidad
Document_Number	string	Sí	Número de documento de identidad
Names	string	Sí	Nombres del cliente
Lastnames	string	Sí	Apellidos del cliente
Email	string	Sí	Correo electrónico del cliente

Access

Campo	Tipo	Obligatorio	Descripción
Name	string	Sí	Nombre del canal de registro digital
Creation_Date	datetime	Sí	Fecha de creación del registro en el canal

Manejo de Errores

Código	Descripción	Ejemplo
ERROR_00	Excepción técnica general	"La solicitud no fue exitosa. Se ha generado una excepción técnica"
ERROR_03	No se pudo validar la petición	"La solicitud no fue exitosa. No fue posible validar la petición"
ERROR_04	Objetos no acordes a la petición	"La solicitud no fue exitosa. Fueron enviados objetos no acordes a la petición"
ERROR_06	No se encontró información válida	"La solicitud no fue exitosa. No se encontró información válida"
OK_01	Procesamiento exitoso	"La solicitud fue exitosa"

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 petición
BotBaseResponseHeader - Cabecera estándar de respuesta
BotBaseResponseService - Información de estado del servicio
BotBaseResponseStatusDetail - Detalles de estado y errores

Utilidades y servicios comunes:

ConfigurationUtil - Gestión de configuraciones y tipologías
AuditUtil - Auditoría de transacciones
WhatsAppUtil - Operaciones específicas de WhatsApp
Util.FillBaseRequest - Llenado de información base de la petición

Patrones de diseño implementados:

Singleton Pattern: WhatsAppBusiness.GetInstance, WhatsAppUtil.GetInstance
Template Method: Flujo de procesamiento estándar con regiones
Factory Pattern: Creación de objetos de respuesta
Repository Pattern: CRUD_MDM_REGISTRO_DIGITAL para acceso a datos

Componentes reutilizados:

Modelos de respuesta estándar (BaseResponseGetByPhoneWhatsApp)
Utilidades de configuración y auditoría
Clases de base de datos MongoDB (MDM_REGISTRO_DIGITAL)

Referencias Cruzadas

Servicio SOAP equivalente: /soap/whatsapp/v1/getbyphone
Servicio de actualización: whatsapp-v1-update
Servicio de consulta por nombre: whatsapp-v1-getbyname

Ejemplos de Request/Response

Solicitud (Request)

json

{
  "WSRequestHeader": {
    "System": {
      "name": "MAX",
      "correlationID": "LUZ-0.16316496738717456",
      "processingServer": ""
    },
    "Property": []
  },
  "WSRequestBody": {
    "Phone": "3052957123",
    "Audit": {
      "Canal": "whatsapp",
      "Date": "2025-07-12",
      "Hour": "17:04:20"
    }
  }
}

Respuesta Exitosa

json

{
  "WSResponseHeader": {
    "System": {
      "name": "MAX",
      "correlationID": "LUZ-0.16316496738717456",
      "processingServer": ""
    },
    "Service": {
      "status": "OK",
      "responseDate": "2025-07-12T17:04:21.1627351Z",
      "processingServer": null,
      "statusDetail": [
        {
          "errorCode": "OK_01",
          "errorDetailCode": "Se consulto el cliente de manera exitosa.",
          "errorMessage": "La solicitud LUZ-0.16316496738717456 fue exitosa",
          "errorMessageUser": null
        }
      ]
    },
    "Property": []
  },
  "WSResponseBody": {
    "Access": {
      "Creation_Date": "2024-06-17T16:15:40.992Z",
      "Name": "WhatsApp"
    },
    "Customer": {
      "Document_Number": "1080277123",
      "Document_Type": "CC",
      "Email": "pruebas@etb.com",
      "Names": "Juan",
      "Lastnames": "Morales"
    }
  }
}

Respuesta de Error

json

{
  "WSResponseHeader": {
    "Service": {
      "Status": "FAIL",
      "StatusDetails": [
        {
          "Code": "ERROR_06",
          "Message": "La solicitud no fue exitosa. No se encontró información válida",
          "Description": "La solicitud no fue exitosa. No se encontró información válida"
        }
      ]
    },
    "CorrelationID": "12345678-1234-1234-1234-123456789012",
    "Timestamp": "2024-01-15T10:30:01Z"
  },
  "WSResponseBody": {
    "Customer": {
      "Document_Type": null,
      "Document_Number": null,
      "Names": null,
      "Lastnames": null,
      "Email": null
    },
    "Access": {
      "Name": null,
      "Creation_Date": "0001-01-01T00:00:00Z"
    }
  }
}

Diagramas Técnicos

3.1 Flujo de Datos

mermaid

graph TD
    A[Cliente MAX WhatsApp] --> B[WhatsAppController]
    B --> C[Validación de Autenticación]
    C --> D[Creación BaseRequest]
    D --> E[WhatsAppBusiness.GetByPhone_v1]
    E --> F[Auditoría de Entrada]
    F --> G[Conversión de Datos]
    G --> H[Validación de Parámetros]
    H --> I[Obtención de Origen]
    I --> J[Consulta MDM_REGISTRO_DIGITAL]
    J --> K{¿Registro encontrado?}
    K -->|Sí| L[Construcción de Respuesta]
    K -->|No| M[Error ERROR_06]
    L --> N[Auditoría de Salida]
    M --> N
    N --> O[BAM - Save_WhatsApp_Get_Phone]
    O --> P[Respuesta al Cliente]

3.2 Arquitectura de Clases

mermaid

classDiagram
    class WhatsAppController {
        +GetByPhone_v1(BaseRequestGetByPhoneWhatsApp) BaseResponseGetByPhoneWhatsApp
    }
    
    class WhatsAppBusiness {
        +GetByPhone_v1(BaseRequest, string) BaseResponseGetByPhoneWhatsApp
    }
    
    class WhatsAppUtil {
        +Get(string) MDM_REGISTRO_DIGITAL
        +Update(MDM_REGISTRO_DIGITAL) bool
    }
    
    class CRUD_MDM_REGISTRO_DIGITAL {
        +Get(string) MDM_REGISTRO_DIGITAL
        +Update(MDM_REGISTRO_DIGITAL) bool
    }
    
    class MDM_REGISTRO_DIGITAL {
        +string Apellidos
        +string Nombres
        +string Email
        +string Numero_Documento
        +string Tipo_Documento
        +MDM_REGISTRO_DIGITAL_CANAL Canal_Acceso
    }
    
    class GetByPhoneWhatsAppResponse {
        +GetByPhoneCustomerResponse Customer
        +GetByPhoneAccessResponse Access
    }
    
    WhatsAppController --> WhatsAppBusiness
    WhatsAppBusiness --> WhatsAppUtil
    WhatsAppUtil --> CRUD_MDM_REGISTRO_DIGITAL
    CRUD_MDM_REGISTRO_DIGITAL --> MDM_REGISTRO_DIGITAL
    WhatsAppBusiness --> GetByPhoneWhatsAppResponse

3.3 Secuencia de Ejecución

mermaid

sequenceDiagram
    participant Client as Cliente MAX
    participant Controller as WhatsAppController
    participant Business as WhatsAppBusiness
    participant Util as WhatsAppUtil
    participant DB as MongoDB
    participant Audit as AuditUtil
    
    Client->>Controller: POST /api/whatsapp/v1/getbyphone
    Controller->>Business: GetByPhone_v1(request)
    Business->>Audit: Save_Request_Async(entrada)
    Business->>Business: Conversión de datos
    Business->>Business: Validación de parámetros
    Business->>Business: Obtención de origen
    Business->>Util: Get(phone)
    Util->>DB: Consulta MDM_REGISTRO_DIGITAL
    DB-->>Util: Registro digital
    Util-->>Business: MDM_REGISTRO_DIGITAL
    Business->>Business: Construcción respuesta
    Business->>Audit: Save_Request_Async(salida)
    Business->>Audit: Save_WhatsApp_Get_Phone
    Business-->>Controller: BaseResponseGetByPhoneWhatsApp
    Controller-->>Client: JSON Response

Políticas y Consideraciones

Políticas de Seguridad

Mecanismos de autenticación y autorización:

Autenticación mediante token Bearer en header Authorization
Validación de origen de petición mediante ConfigurationUtil.Get_Origin()
Verificación de permisos por sistema y canal

Validaciones de seguridad implementadas:

Validación de parámetros de entrada obligatorios
Sanitización de datos de entrada
Validación de formato de número de teléfono
Control de acceso por IP y origen

Límites de tasa (rate limits):

No se identifican límites específicos de tasa en el código
Se recomienda implementar rate limiting por IP/origen

SLAs aplicables:

Tiempo de respuesta esperado: < 2 segundos
Disponibilidad: 99.9%
Tolerancia a fallos: Circuit breaker pattern recomendado

Recomendaciones y Mejores Prácticas

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

Manejo de excepciones:

csharp

// Actual - Captura genérica
catch (Exception ex)
{
    _BotBaseResponse = new BaseResponseGetByPhoneWhatsApp();
    _BotBaseResponse.WSResponseHeader.Service.Status = Constants.Error;
    _BotBaseResponse.WSResponseHeader.Service.AddStatusDetailItem(
        new BotBaseResponseStatusDetail(Constants.ERROR_00, Constants.ERROR_00_Msg, ex.Message), 
        _BotBaseRequest.CorrelationID);
}

// Recomendado - Captura específica
catch (MongoException ex)
{
    // Manejo específico para errores de base de datos
}
catch (ValidationException ex)
{
    // Manejo específico para errores de validación
}

Validación de entrada mejorada:

csharp

// Agregar validación de formato de teléfono
if (!Regex.IsMatch(_Request.Phone, @"^\d{10}$"))
{
    continuar = false;
    _BotBaseResponse.WSResponseHeader.Service.AddStatusDetailItem(
        new BotBaseResponseStatusDetail("ERROR_07", "Formato de teléfono inválido"), 
        _BotBaseRequest.CorrelationID);
}

Implementación de caché:

csharp

// Agregar caché para consultas frecuentes
public async Task<MDM_REGISTRO_DIGITAL> Get(string Phone) 
{
    string cacheKey = $"whatsapp_registro_{Phone}";
    var cached = UtilCacheHelper.GetInstance.Get<MDM_REGISTRO_DIGITAL>(cacheKey);
    if (cached != null) return cached;
    
    var result = await CRUD_MDM_REGISTRO_DIGITAL.GetInstance.Get(Phone);
    if (result != null)
    {
        UtilCacheHelper.GetInstance.Set(cacheKey, result, 300); // 5 minutos
    }
    return result;
}

Optimizaciones posibles:

Consultas paralelas: Para servicios que requieran múltiples fuentes de datos
Paginación: Si se requiere consultar múltiples registros
Compresión: Implementar gzip para respuestas grandes
Logging estructurado: Mejorar el logging para monitoreo

Consideraciones de mantenimiento importantes:

Monitoreo: Implementar métricas de rendimiento y disponibilidad
Logs: Mejorar el logging para debugging y auditoría
Documentación: Mantener documentación actualizada de cambios
Testing: Implementar pruebas unitarias y de integración

Sugerencias de seguridad aplicables:

Rate Limiting: Implementar límites por IP y usuario
Validación de entrada: Sanitizar todos los parámetros de entrada
Encriptación: Encriptar datos sensibles en tránsito y reposo
Auditoría: Mantener logs de auditoría completos
Monitoreo de seguridad: Implementar alertas para actividades sospechosas

Notas Adicionales

El servicio está diseñado para ser escalable y mantener alta disponibilidad
Se recomienda implementar health checks para monitoreo de salud del servicio
Considerar implementar versionado de API para futuras actualizaciones
Mantener compatibilidad con el servicio SOAP equivalente

WhatsApp v1 GetByPhone - Consulta de Clientes por Teléfono ​

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 ​

WhatsApp v1 GetByPhone - Consulta de Clientes por Teléfono

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