Catálogo APIs

Appearance

Consulta de Usuario MiETB por Número de Conexión - mietb-v1-getuserbyphone ​

Información del Servicio

Endpoint:  /api/mietb/v1/getuserbyphone
Método:  POST
Versión: v1
Categoría: MiETB / Usuarios

1. Documentación del Servicio ​

Descripción general ​

Este servicio permite consultar la información básica de un usuario registrado en MiETB a partir de su número de conexión (teléfono). Devuelve datos de identificación, correo electrónico y el tipo de registro (correo o red social).
Categoría de negocio: Gestión de usuarios MiETB.
Casos de uso principales:

  • Obtener datos de usuario para procesos de autenticación o validación.
  • Integrar información de usuario en flujos de autoservicio o soporte.
  • Validar existencia y tipo de registro de un usuario a partir de su teléfono.

Especificación técnica ​

  • Endpoint: /api/mietb/v1/getuserbyphone
  • Método HTTP: POST
  • Capas involucradas:
    • Controlador: MiETBController (método GetByPhone_v1)
    • Lógica de negocio: MiETBBusiness.GetUserByPhone_v1
    • Acceso a datos: Utilidades de consulta de servicios y usuarios (ServiceUtil, MiETBUtil)
  • 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 servicio asociado al número de conexión.
    7. Si existe, se obtiene el usuario asociado y se construye la respuesta.
    8. Se audita la salida y retorna la respuesta.
  • Dependencias principales:
    • Modelos: BaseRequestMiETBGetUserByPhone, MiETBGetUserByPhoneRequest, BaseResponseMiETBGetUserByPhone, MiETBGetUserByPhoneResponse
    • Utilidades: AuditUtil, ServiceUtil, MiETBUtil, 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 ​

CampoTipoObligatorioDescripción
System.NamestringSíNombre del sistema que realiza la petición
System.CorrelationIDstringSíIdentificador único de la transacción
System.ProcessingServerstringSíServidor de procesamiento
PropertyarrayNo*Propiedades adicionales de la petición

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

Body ​

CampoTipoObligatorioDescripción
AuditobjetoSíInformación de auditoría de la operación
PhonestringSíNúmero de conexión (teléfono) a consultar

Respuesta esperada (Response) ​

Headers ​

CampoTipoObligatorioDescripción
System.NamestringSíNombre del sistema que responde
System.CorrelationIDstringSíIdentificador único de la transacción
System.ProcessingServerstringSíServidor de procesamiento
Service.StatusstringSíEstado de la ejecución (OK/ERROR)
Service.ResponseDatedatetimeSíFecha de la respuesta
Service.ProcessingServerstringSíServidor de procesamiento
Service.StatusDetailarraySíDetalles de estado y errores
PropertyarrayNoPropiedades adicionales

  • StatusDetail (array de objetos)

    CampoTipoObligatorioDescripción
    ErrorCodestringSíCódigo de error o estado
    ErrorDetailCodestringNoDetalle funcional del error
    ErrorMessagestringNoMensaje técnico
    ErrorMessageUserstringNoMensaje para el usuario

Body ​

CampoTipoObligatorioDescripción
Document_NumberstringSíNúmero de identificación del cliente
Document_TypestringSíTipo de identificación del cliente
MailstringSíCorreo electrónico del usuario
Register_TypestringSíTipo de registro (Email, Facebook, Google+, etc.)

Manejo de errores ​

CódigoDescripciónEjemplo
ERROR_04Request nulo o mal formado"El request es nulo"
ERROR_06No existe servicio asociado al teléfono"No se encontró servicio para el número"
ERROR_07No existe usuario asociado al servicio"No se encontró usuario para el servicio"
BOTERRORExcepción no controlada"se ha generado una excepcion no controlada"

2. Análisis de Componentes ​

Modelos y componentes ​

  • Modelos base utilizados:
    • BaseRequestMiETBGetUserByPhone
    • MiETBGetUserByPhoneRequest
    • BaseResponseMiETBGetUserByPhone
    • MiETBGetUserByPhoneResponse
    • BotBaseRequestHeader, BotBaseResponseHeader
  • Utilidades y servicios comunes:
    • AuditUtil (auditoría de entrada/salida)
    • ServiceUtil (consulta de servicios por teléfono)
    • MiETBUtil (consulta de usuario por documento)
    • 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 MiETB.
    • Utilidades de auditoría y consulta de servicios.
  • Referencias cruzadas:
    • Endpoint /api/mietb/v1/getuserbyid para consulta por documento.
    • Otros endpoints de MiETB para registro, autenticación y actualización de usuario.

Ejemplos de Request/Response ​

Solicitud (request) ​

json
{
  "WSRequestHeader": {
    "System": {
      "name": "MAX",
      "correlationID": "LUZ-0.318637281780503",
      "processingServer": null
    },
    "Property": []
  },
  "WSRequestBody": {
    "Phone": "6012325999",
    "Audit": {
      "Canal": "whatsapp",
      "Date": "2025-04-16",
      "Hour": "22:39:56"
    }
  }
}

Respuesta exitosa ​

json
{
  "WSResponseHeader": {
    "System": {
      "name": "MAX",
      "correlationID": "LUZ-0.318637281780503",
      "processingServer": null
    },
    "Service": {
      "status": "OK",
      "responseDate": "2025-04-16T22:39:57.1276286Z",
      "processingServer": null,
      "statusDetail": [
        {
          "errorCode": "OK_01",
          "errorDetailCode": "Se valido la existencia del usuario exitosamente",
          "errorMessage": "La solicitud LUZ-0.318637281780503 fue exitosa",
          "errorMessageUser": null
        }
      ]
    },
    "Property": []
  },
  "WSResponseBody": {
    "Document_Number": "39659110",
    "Document_Type": "CC",
    "Mail": "prueba@hotmail.com",
    "Register_Type": "Registro Light"
  }
}

Respuesta de error ​

json
{
  "WSResponseHeader": {
    "System": {
      "Name": "MiETB",
      "CorrelationID": "123e4567-e89b-12d3-a456-426614174000",
      "ProcessingServer": "server-01"
    },
    "Service": {
      "Status": "ERROR",
      "ResponseDate": "2024-06-01T12:35:00Z",
      "ProcessingServer": "server-01",
      "StatusDetail": [
        {
          "ErrorCode": "ERROR_06",
          "ErrorDetailCode": "No se encontró servicio para el número",
          "ErrorMessage": "No existe servicio asociado al teléfono",
          "ErrorMessageUser": "No se encontró información para el número ingresado."
        }
      ]
    },
    "Property": []
  },
  "WSResponseBody": null
}

3. Diagramas Técnicos ​

3.1 Flujo de datos ​

mermaid
graph TD
  A["Cliente/API Consumer"] --> B["MiETBController"]
  B --> C["MiETBBusiness"]
  C --> D["ServiceUtil (Consulta Servicio)"]
  C --> E["MiETBUtil (Consulta Usuario)"]
  C --> F["AuditUtil (Auditoría)"]
  D --> G["Base de datos"]
  E --> G

3.2 Arquitectura de clases ​

mermaid
classDiagram
  class MiETBController {
    +GetByPhone_v1(request)
  }
  class MiETBBusiness {
    +GetUserByPhone_v1(request, name)
  }
  class BaseRequestMiETBGetUserByPhone
  class MiETBGetUserByPhoneRequest
  class BaseResponseMiETBGetUserByPhone
  class MiETBGetUserByPhoneResponse
  class BotBaseRequestHeader
  class BotBaseResponseHeader

  MiETBController --> MiETBBusiness
  MiETBController --> BaseRequestMiETBGetUserByPhone
  BaseRequestMiETBGetUserByPhone --> MiETBGetUserByPhoneRequest
  MiETBBusiness --> BaseResponseMiETBGetUserByPhone
  BaseResponseMiETBGetUserByPhone --> MiETBGetUserByPhoneResponse
  BaseResponseMiETBGetUserByPhone --> BotBaseResponseHeader
  BotBaseRequestHeader <.. BaseRequestMiETBGetUserByPhone

3.3 Secuencia de ejecución ​

mermaid
sequenceDiagram
  participant Cliente
  participant API as MiETBController
  participant Negocio as MiETBBusiness
  participant Servicio as ServiceUtil
  participant Usuario as MiETBUtil
  participant Auditoria as AuditUtil

  Cliente->>API: POST /api/mietb/v1/getuserbyphone
  API->>Negocio: GetUserByPhone_v1(request)
  Negocio->>Auditoria: Save_Request(entrada)
  Negocio->>Servicio: Get_By_Phone
  Servicio-->>Negocio: Datos de servicio
  Negocio->>Usuario: Get_By_Id
  Usuario-->>Negocio: Datos de usuario
  Negocio->>Auditoria: Save_Request(salida)
  Negocio-->>API: BaseResponseMiETBGetUserByPhone
  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 del usuario.
  • 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.