Autenticación de Cobertura - security-v1-authcoverage

Información del Servicio

Endpoint: /api/security/v1/authcoverage
Método: POST
Versión: v1
Categoría: Seguridad

Documentación del Servicio

Descripción general

El servicio security-v1-authcoverage es un endpoint para obtener un token de autenticación para la cobertura. Este servicio permite autenticar un cliente consumidor con el servidor de aplicaciones y generar un token de seguridad para validar la cobertura de servicios de telecomunicaciones.

Categoría de negocio: Seguridad y Autenticación.

Casos de uso principales:

Autenticación de sistemas externos para consulta de cobertura
Generación de tokens de seguridad para validación de servicios
Integración con el mapa de coberturas de ETB
Validación de origen de peticiones de cobertura

Especificación técnica

Endpoint completo: /api/security/v1/authcoverage
Método HTTP: POST
Capas involucradas:
- Controlador: SecurityController
- Lógica de negocio: SecurityBusiness
- Acceso a datos: CoverageClient

Flujo de procesamiento:

Validación de la petición y conversión de datos
Obtención del origen de la petición
Verificación del estado del API (encendido/apagado)
Autenticación con el servicio de cobertura
Generación y retorno del token

Dependencias principales:

CoverageClient para comunicación con el mapa de coberturas
SecurityUtil para validaciones de seguridad
ConfigurationUtil para gestión de configuraciones
AuditUtil para auditoría de peticiones

Consideraciones de seguridad:

Validación de origen de la petición
Autenticación mediante credenciales configuradas
Auditoría completa de todas las peticiones
Manejo seguro de tokens de autenticació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 y propiedades

Body

Campo	Tipo	Obligatorio	Descripción
Audit	object	No	Información de auditoría de la petición
Billing_Account	string	No	Cuenta de facturación asociada
Customer	object	No	Información del cliente
Phone	string	No	Número de teléfono

Estructura de objetos anidados:

Estructura de WSRequestHeader

Campo	Tipo	Obligatorio	Descripción
System	object	No	Información asociada al sistema
Property	array	No	Propiedades asociadas al consumo del servicio web

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	Sí	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
Browser	string	No	Navegador de la petición
Browser_Id	string	No	Id del navegador
Browser_InputType	string	No	Tipo de input
Browser_Platform	string	No	Plataforma del navegador
Browser_Version	string	No	Versión del navegador
Encoding	string	No	Encoding de la petición
IP	string	No	IP de la petición
IP_X	string	No	IP de las server variables
IPs	array	No	Listado de IPs
MiETB_User	string	No	Id del usuario de MiETB
URL	string	No	URL de la petición
URL_Referrer	string	No	URL de referencia
User_Agent	string	No	Agente de usuario
User_Name	string	No	Nombre del usuario

Estructura de Customer

Campo	Tipo	Obligatorio	Descripción
Document_Number	string	No	Número de documento del cliente
Document_Type	string	No	Tipo de documento del cliente

Respuesta esperada (Response)

Headers

Campo	Tipo	Obligatorio	Descripción
WSResponseHeader	object	Sí	Cabecera de la respuesta con información del sistema y servicio

Body

Campo	Tipo	Obligatorio	Descripción
Token	string	No	Token devuelto por API de portaldirecciones para autenticar

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 WSResponseHeader.Service.StatusDetail

Campo	Tipo	Obligatorio	Descripción
ErrorCode	string	No	Código del error
ErrorDetailCode	string	No	Detalle del error
ErrorMessage	string	No	Mensaje del error
ErrorMessageUser	string	No	Mensaje del error para usuario

Manejo de errores

Código	Descripción	Ejemplo
ERROR_04	La solicitud no fue exitosa. Fueron enviados objetos no acordes a la petición	Error en conversión de datos
ERROR_06	Error en autenticación de cobertura	Fallo en comunicación con servicio de cobertura

Análisis de Componentes

Modelos y componentes

Modelos base utilizados:

BaseRequestAuthCoverage: Modelo de petición para autenticación de cobertura
BaseResponseAuthCoverage: Modelo de respuesta para autenticación de cobertura
AuthCoverageResponse: Contenido de la respuesta con el token
AuthCoverageRequest: Modelo interno para comunicación con servicio de cobertura

Utilidades y servicios comunes:

SecurityUtil: Utilidades de seguridad y autenticación
CoverageClient: Cliente para comunicación con el mapa de coberturas
ConfigurationUtil: Gestión de configuraciones del sistema
AuditUtil: Auditoría de peticiones y respuestas

Patrones de diseño implementados:

Singleton Pattern: Para instancias únicas de servicios
Factory Pattern: Para creación de clientes HTTP
Strategy Pattern: Para diferentes tipos de autenticación

Componentes reutilizados:

BotBaseRequestHeader: Cabecera base para peticiones
BotBaseResponseHeader: Cabecera base para respuestas
BaseAudit: Modelo base para auditoría

Referencias cruzadas:

SecurityController: Controlador principal de seguridad
SecurityBusiness: Lógica de negocio de seguridad
CoverageClient: Cliente de comunicación con cobertura

Ejemplos de Request/Response

Solicitud (request)

json

{
  "WSRequestHeader": {
    "System": {
      "name": "MAX",
      "correlationID": "LUZ-0.636276659263253",
      "processingServer": null
    },
    "Property": [
      {
        "name": null,
        "value": null
      },
      {
        "name": null,
        "value": null
      }
    ]
  }
}

Respuesta exitosa

json

{
  "WSResponseHeader": {
    "System": {
      "name": "MAX",
      "correlationID": "LUZ-0.636276659263253",
      "processingServer": null
    },
    "Service": {
      "status": "OK",
      "responseDate": "2025-07-31T09:42:16.1354329Z",
      "processingServer": null,
      "statusDetail": [
        {
          "errorCode": "OK_01",
          "errorDetailCode": "La solicitud fue exitosa ",
          "errorMessage": "La solicitud LUZ-0.636276659263253 fue exitosa. Se genero el token de autenticacion",
          "errorMessageUser": null
        }
      ]
    },
    "Property": [
      {
        "name": null,
        "value": null
      }
    ]
  },
  "WSResponseBody": {
    "Token": "QjBNNy9uL090V0lBR3ErVW5TcVE0R0NYb0lDb2dRdytURklxN2hVMlV6QlUvVlRKZGJ3cXl3PT0="
  }
}

Respuesta de error

json

{
  "WSResponseHeader": {
    "System": {
      "Name": "SISTEMA_COBERTURA",
      "CorrelationID": "CORR-001-2024",
      "ProcessingServer": "SRV-PROD-01"
    },
    "Service": {
      "Status": "FAIL",
      "ResponseDate": "2024-12-19T10:30:00Z",
      "ProcessingServer": "SRV-PROD-01",
      "StatusDetail": [
        {
          "ErrorCode": "ERROR_06",
          "ErrorDetailCode": "Error en autenticación de cobertura",
          "ErrorMessage": "La solicitud no fue exitosa. Error en autenticación de cobertura",
          "ErrorMessageUser": "La solicitud no fue exitosa. Error en autenticación de cobertura"
        }
      ]
    },
    "Property": []
  },
  "WSResponseBody": {
    "Token": null
  }
}

Diagramas Técnicos

3.1 Flujo de datos

mermaid

graph TD
  A[Recepción de la solicitud] --> B[SecurityController]
  B --> C[SecurityBusiness]
  C --> D[Auditoría de entrada]
  D --> E[Conversión de datos]
  E --> F[Obtención del origen]
  F --> G[Verificación API]
  G --> H[Autenticación Coverage]
  H --> I[CoverageClient]
  I --> J[Generación token]
  J --> K[Respuesta final]

3.2 Arquitectura de clases

mermaid

classDiagram
  class SecurityController {
    +AuthCoverage_v1()
  }
  class SecurityBusiness {
    +AuthCoverage_v1()
  }
  class CoverageClient {
    +Authentication()
  }
  class SecurityUtil {
    +Authentication_Coverage()
  }
  SecurityController --> SecurityBusiness
  SecurityBusiness --> CoverageClient
  SecurityBusiness --> SecurityUtil

3.3 Secuencia de ejecución

mermaid

sequenceDiagram
  participant Cliente
  participant SecurityController
  participant SecurityBusiness
  participant CoverageClient
  participant ServicioCobertura
  Cliente->>SecurityController: POST /api/security/v1/authcoverage
  SecurityController->>SecurityBusiness: AuthCoverage_v1()
  SecurityBusiness->>SecurityBusiness: Auditoría entrada
  SecurityBusiness->>SecurityBusiness: Conversión datos
  SecurityBusiness->>SecurityBusiness: Obtener origen
  SecurityBusiness->>SecurityBusiness: Verificar API
  SecurityBusiness->>CoverageClient: Authentication()
  CoverageClient->>ServicioCobertura: POST /auth
  ServicioCobertura-->>CoverageClient: Token
  CoverageClient-->>SecurityBusiness: Token
  SecurityBusiness-->>SecurityController: BaseResponseAuthCoverage
  SecurityController-->>Cliente: Respuesta con token

Políticas y Consideraciones

Políticas de seguridad

Mecanismos de autenticación y autorización:

Validación de origen de la petición mediante configuración
Autenticación con credenciales específicas por sistema
Verificación de estado del API (encendido/apagado)

Validaciones de seguridad implementadas:

Validación de cabeceras de petición
Auditoría completa de todas las peticiones
Manejo seguro de tokens de autenticación
Validación de configuración de parámetros

Límites de tasa (rate limits):

Control mediante configuración de parámetros
Auditoría de todas las peticiones para monitoreo

SLAs aplicables:

Tiempo de respuesta esperado: < 2 segundos
Disponibilidad: 99.9%
Tolerancia a fallos: Configurable por sistema

Recomendaciones y mejores prácticas

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

Implementar cache de tokens para mejorar rendimiento
Agregar validación de expiración de tokens
Implementar retry automático en caso de fallo del servicio de cobertura
Mejorar logging de errores para facilitar debugging

Optimizaciones posibles:

Implementar pool de conexiones HTTP para CoverageClient
Agregar circuit breaker para el servicio de cobertura
Implementar cache distribuido para tokens
Optimizar serialización/deserialización de JSON

Consideraciones de mantenimiento importantes:

Mantener actualizadas las configuraciones de parámetros
Monitorear el rendimiento del servicio de cobertura
Revisar periódicamente los logs de auditoría
Validar la seguridad de los tokens generados

Sugerencias de seguridad aplicables:

Implementar rotación automática de claves de autenticación
Agregar validación de IP de origen
Implementar rate limiting por IP/sistema
Agregar validación de integridad de tokens

Autenticación de Cobertura - security-v1-authcoverage ​

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 ​

Estructura de Customer ​

Respuesta esperada (Response) ​

Headers ​

Body ​

Estructura de WSResponseHeader ​

Estructura de WSResponseHeader.System ​

Estructura de WSResponseHeader.Service ​

Estructura de WSResponseHeader.Property ​

Estructura de WSResponseHeader.Service.StatusDetail ​

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 ​

Autenticación de Cobertura - security-v1-authcoverage

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

Estructura de Customer

Respuesta esperada (Response)

Headers

Body

Estructura de WSResponseHeader

Estructura de WSResponseHeader.System

Estructura de WSResponseHeader.Service

Estructura de WSResponseHeader.Property

Estructura de WSResponseHeader.Service.StatusDetail

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