Max v2 Route – Enrutamiento de Conversaciones

Endpoint

Endpoint: /api/max/v2/route

Método: POSTVersión: v2Tipo de API: Experiencia Categoría: Atención y Soporte Estándar TM Forum: TMF673 Equipo Responsable: Equipo de Atención Digital Contacto: soporte.digital@etb.com.coFecha de Creación: 15 de enero de 2022 Última Actualización: 10 de julio de 2025

1. Resumen del Servicio

Max v2 Route es un servicio de la capa de experiencia diseñado para enrutar e inicializar conversaciones basadas en criterios del cliente (documento, cuenta o teléfono). Incluye validación OAuth2, transformación de datos, llamadas paralelas a servicios auxiliares y auditoría de transacciones.

2. Descripción Funcional

Validación y Autenticación: Verifica token OAuth2 y permisos.
Transformación de Datos: Convierte WSRequestHeader y WSRequestBody a modelos internos.
Selección de Criterio: Determina si la búsqueda es por documento, cuenta o teléfono.
Invocaciones Paralelas: Llama a normalize-papi, smallworld-sapi y neighbors-service.
Construcción de Respuesta: Ensambla WSResponseHeader y WSResponseBody.
Auditoría: Registra logs en ELK mediante AuditUtil.

3. Casos de Uso

Caso de Uso	Descripción
Chatbot Luz	Inicializa la conversación mostrando datos del cliente.
Portal Self-Service	Muestra historial de órdenes y estado de PQRs.
Dashboard CRM	Integra datos para monitoreo en tiempo real.

4. Especificación de Contrato

4.1 Endpoints y Métodos

Método	URI	Descripción
POST	`/api/max/v2/route`	Enruta e inicializa conversaciones según contexto del cliente.

4.2 Esquemas de Datos (JSON Schema)

4.2.1 RouteRequestBody_v2

Parámetros incluidos en el cuerpo de la petición:

Nombre del parámetro	Tipo	Obligatorio	Descripción
ID_Servicio	string	No	Identificador único del servicio
ID_Tipo_Servicio	string	No	Tipo de servicio
ID_Tipo_Activacion	string	Sí	Tipo de activación del servicio
ID_Tipo_Promocion	string	No	Tipo de promoción asociada
ID_Accion_Cambio_Plan	string	No	Acción para cambio de plan
Canales	string	No	Canales de atención soportados
Planes_Aplicar	string	No	Planes sobre los que aplica
Tramites_Aplicar	string	No	Trámites cubiertos
fields	string	No	Campos adicionales filtrables
offset	string	No	Registro inicial de paginación
limit	string	No	Límite de registros por página

json

{
  "$id": "#/components/schemas/RouteRequest_v2",
  "type": "object",
  "properties": {
    "WSRequestHeader": { "$ref": "#/components/schemas/WSRequestHeader" },
    "WSRequestBody":  { "$ref": "#/components/schemas/RouteRequestBody_v2" }
  },
  "required": ["WSRequestHeader","WSRequestBody"]
}

4.2.2 RouteResponseBody_v2

Parámetros incluidos en el cuerpo de la respuesta:

Nombre del parámetro	Tipo	Obligatorio	Descripción
CustomerInfo	object	Sí	Datos básicos del cliente (id, nombre)
Orders	array	No	Lista de órdenes del cliente
PQRs	array	No	Lista de PQRs asociadas al cliente

json

{
  "$id": "#/components/schemas/RouteResponse_v2",
  "type": "object",
  "properties": {
    "WSResponseHeader": { "$ref": "#/components/schemas/WSResponseHeader" },
    "WSResponseBody":  { "$ref": "#/components/schemas/RouteResponseBody_v2" }
  },
  "required": ["WSResponseHeader","WSResponseBody"]
}

4.3 Ejemplos de Request / Response

Para ilustrar el uso del servicio, a continuación se presentan tres casos de ejemplo:

Ejemplo 1: Solicitud

http

POST /api/max/v2/route HTTP/1.1
Host: api.etb.com.co
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "WSRequestHeader": {
    "requestId": "12345",
    "timestamp": "2025-07-10T14:30:00Z",
    "authorization": "Bearer eyJ..."
  },
  "WSRequestBody": {
    "ID_Tipo_Activacion": "ACT01",
    "Customer": {
      "documentType": "CC",
      "documentNumber": "1234567890"
    },
    "fields": [],
    "offset": 0,
    "limit": 10
  }
}

Ejemplo 2: Respuesta Exitosa

json

{
  "WSResponseHeader": {
    "responseId": "54321",
    "timestamp": "2025-07-10T14:30:01Z",
    "status": "OK_01"
  },
  "WSResponseBody": {
    "CustomerInfo": {
      "id": "C001",
      "name": "Juan Pérez"
    },
    "Orders": [
      {
        "orderId": "O1001",
        "status": "COMPLETED"
      }
    ],
    "PQRs": []
  }
}

Ejemplo 3: Respuesta de Error

json

{
  "WSResponseHeader": {
    "responseId": "99999",
    "timestamp": "2025-07-14T10:00:00Z",
    "status": "400"
  },
  "WSResponseBody": {
    "errorCode": "400",
    "errorMessage": "ID_Tipo_Activacion es obligatorio"
  }
}

4.4 Códigos de Error Códigos de Error

Código	Significado	Descripción detallada
400	Bad Request	Parámetros faltantes o inválidos
401	Unauthorized	Token faltante o inválido
ERROR_02	Origen no encontrado	No se pudo determinar criterio de búsqueda
ERROR_03	Validación fallida	Token o esquema de request inválido
ERROR_06	Información no válida	Datos incompletos o inconsistentes
ERROR_07	Cliente o servicio no encontrado	No existen registros en CRM
500	Internal Server Error	Error inesperado en el procesamiento
OK_01	Procesamiento exitoso	Respuesta correcta sin errores de negocio

5. Métricas y SLA

Métrica	Valor
Tiempo promedio de respuesta	120 ms
Percentil 95 (P95)	250 ms
Percentil 99 (P99)	400 ms
SLA de disponibilidad	99.9% mensual

6. Dependencias y Compatibilidad

Componente	Versión	Compatibilidad
normalize-papi	v3.2	Compatible con v2
smallworld-sapi	v1.5	Compatible con v2
neighbors-service	v1.0	Compatible con v2
AuditUtil	v2.0	Compatible con v2

7. Diagramas

7.1 Arquitectura Global

mermaid

graph LR
    subgraph API Gateway
        GW[API Gateway]
    end
    subgraph Servicio MAX
        MC[MaxController]
        MB[MaxBusiness]
    end
    subgraph Utilitarios
        NP[normalize-papi]
        SW[smallworld-sapi]
        NB[neighbors-service]
        AU[AuditUtil]
    end
    subgraph DataStores
        CU[(CustomerDB)]
        OU[(OrderDB)]
        PQ[(PQRDB)]
    end
    GW --> MC --> MB
    MB --> NP --> SW --> NB
    MB --> AU
    MB --> CU & OU & PQ

7.2 Flujo de Datos

mermaid

graph TD
    A[Cliente envía petición] --> B[MaxController.Route_v2]
    B --> C[Validación de autenticación]
    C --> D[Conversión de datos]
    D --> E[Obtención de origen]
    E --> F[Validación de API activa]
    F --> G{¿Qué criterio usar?}
    G -->|Documento| H[Consulta por cliente]
    G -->|Cuenta| I[Consulta por servicio]
    G -->|Teléfono| J[Consulta por teléfono]
    H --> K[Obtener órdenes y PQRs]
    I --> K
    J --> K
    K --> L[Construir respuesta]
    L --> M[Auditoría de salida]
    M --> N[Respuesta al cliente]

7.3 Diagrama de Clases

mermaid

classDiagram
    class MaxController {
        +Route_v2(BaseRequestRoute_v2) BaseResponseRoute_v2
    }
    class MaxBusiness {
        +GetInstance() MaxBusiness
        +Route_v2(BaseRequestRoute_v2) BaseResponseRoute_v2
    }
    class BaseRequestRoute_v2 {
        +WSRequestHeader BotBaseRequestHeader
        +WSRequestBody RouteRequestBody_v2
    }
    class RouteRequestBody_v2 {
        +Audit Audit
        +Billing_Account string
        +Customer RouteRequestCustomer_v2
        +Phone string
    }
    class BaseResponseRoute_v2 {
        +WSResponseHeader BotBaseResponseHeader
        +WSResponseBody RouteResponseBody_v2
    }
    class RouteResponseBody_v2 {
        +Customer CustomerModel
        +Orders List~OrderModel~
        +PQRs   List~PQRModel~
    }
    class CustomerUtil2 {
        +GetById(RequestModel,string) CustomerModel
    }
    class ServiceUtil2 {
        +GetByBilling(RequestModel,string) ServiceModel
    }
    MaxController --> MaxBusiness
    MaxBusiness --> CustomerUtil2
    MaxBusiness --> ServiceUtil2
    MaxController --> BaseRequestRoute_v2
    MaxController --> BaseResponseRoute_v2

8. Plan de Retiro (Sunset)

v1.0: Retirado el 30 de junio de 2025.
v2.0: Planeado retiro el 31 de diciembre de 2026.
Post-sunset: Migración obligatoria a v3.0 con autenticación mTLS.

9. Políticas y Dependencias

Autenticación (OAuth2/Mule OAuth Provider)
1. Cliente solicita access token mediante Client Credentials.
2. Token en header Authorization: Bearer <token>.
3. API Gateway valida token, vigencia y scope.
4. Token inválido genera 401 Unauthorized.
Rate Limiting: 1000 peticiones/minuto (100 RPS). Superar límites genera 429 Too Many Requests.

10. Logs y Auditoría

Stack: ELK (Elasticsearch, Logstash, Kibana)
Índice: `api-max-route-logs-*
Retención: 30 días (configurable por ILM)
Formato: JSON con campos clave (timestamp, transactionId, level, component, message, payload, context)
Log4j2 Appender:

xml

<Appenders>
  <Console name="JSON_CONSOLE" target="SYSTEM_OUT">
    <JsonLayout eventEol="true" compact="false" />
  </Console>
</Appenders>
<Loggers>
  <Root level="info">
    <AppenderRef ref="JSON_CONSOLE"/>
  </Root>
</Loggers>

11. Calidad, Monitoreo y Pruebas

Cobertura de pruebas unitarias: 85%
Integración continua (CI/CD): Pipelines en Jenkins/GitLab ejecutan suites unitarias y de integración en cada commit, con validación automática de contratos Swagger/OpenAPI.
Pruebas de rendimiento y carga: Ejecución regular de tests (k6/JMeter) apuntando a 3000 RPS sin errores; monitoreo de percentiles (P95/P99) tras cada prueba.
Monitoreo y observabilidad: Dashboards en Grafana y Kibana con métricas de latencia, errores y throughput; alertas configuradas para:
- Tasa de errores > 1%
- Latencia P95 > 300 ms
Retención de métricas y logs: 30 días (configurable via ILM en Elasticsearch).
Cumplimiento PII/GDPR: Enmascaramiento de campos sensibles (e.g., customerId, documentNumber); cifrado en tránsito y reposo; políticas de retención y eliminación según normativa.

12. Ciclo de Vida y Roadmap

Versión	Fecha	Estado	Descripción
v1.0	2022-01-15	Activa	Lanzamiento inicial
v1.1	2023-06-10	Activa	Refinamiento de contrato y validaciones de headers
v2.0	2025-03-20	Activa	Rediseño de flujo y ajustes de OAuth

Próximas versiones

v2.1 (2025-Q3): Métricas avanzadas y dashboards.
v2.2 (2025-Q4): Nuevos criterios de enrutamiento.
v3.0 (2026-Q1): Autenticación mTLS y mejoras de seguridad.

13. Restricciones de Diseño Restricciones de Diseño

Convención REST: /recurso/v{versión}/{acción}.
Longitud de URI: Máximo 4096 bytes (recomendado < 2000 bytes).
Longitud de headers:
- Encabezado individual: hasta 16384 bytes.
- Total de headers: hasta 32768 bytes.
Payload máximo: 1 MB.
Nomenclatura: camelCase para parámetros y propiedades JSON.
Datos sensibles: No enviar PII en query parameters; usar body cifrado si es necesario.
Versionado en ruta: Incluir siempre la versión en el path (e.g., v2).

14. Referencias

TM Forum API Guidelines – TMF673
MuleSoft Anypoint Platform
Documentación interna ETB (SharePoint)

Max v2 Route – Enrutamiento de Conversaciones ​

1. Resumen del Servicio ​

2. Descripción Funcional ​

3. Casos de Uso ​

4. Especificación de Contrato ​

4.1 Endpoints y Métodos ​

4.2 Esquemas de Datos (JSON Schema) ​

4.2.1 RouteRequestBody_v2 ​

4.2.2 RouteResponseBody_v2 ​

4.3 Ejemplos de Request / Response ​

Ejemplo 1: Solicitud ​

Ejemplo 2: Respuesta Exitosa ​

Ejemplo 3: Respuesta de Error ​

4.4 Códigos de Error Códigos de Error ​

5. Métricas y SLA ​

6. Dependencias y Compatibilidad ​

7. Diagramas ​

7.1 Arquitectura Global ​

7.2 Flujo de Datos ​

7.3 Diagrama de Clases ​

8. Plan de Retiro (Sunset) ​

9. Políticas y Dependencias ​

10. Logs y Auditoría ​

11. Calidad, Monitoreo y Pruebas ​

12. Ciclo de Vida y Roadmap ​

13. Restricciones de Diseño Restricciones de Diseño ​

14. Referencias ​

Max v2 Route – Enrutamiento de Conversaciones

1. Resumen del Servicio

2. Descripción Funcional

3. Casos de Uso

4. Especificación de Contrato

4.1 Endpoints y Métodos

4.2 Esquemas de Datos (JSON Schema)

4.2.1 RouteRequestBody_v2

4.2.2 RouteResponseBody_v2

4.3 Ejemplos de Request / Response

Ejemplo 1: Solicitud

Ejemplo 2: Respuesta Exitosa

Ejemplo 3: Respuesta de Error

4.4 Códigos de Error Códigos de Error

5. Métricas y SLA

6. Dependencias y Compatibilidad

7. Diagramas

7.1 Arquitectura Global

7.2 Flujo de Datos

7.3 Diagrama de Clases

8. Plan de Retiro (Sunset)

9. Políticas y Dependencias

10. Logs y Auditoría

11. Calidad, Monitoreo y Pruebas

12. Ciclo de Vida y Roadmap

13. Restricciones de Diseño Restricciones de Diseño

14. Referencias