Experience XAPI Services

Información General

Experience XAPI Services es el API Gateway principal para servicios de experiencia del cliente en ETB, proporcionando una interfaz unificada para múltiples sistemas backend con arquitectura de microservicios.

Descripción General

Experience XAPI Services actúa como API Gateway centralizado que orquesta y gestiona las comunicaciones entre aplicaciones frontend y múltiples sistemas backend de ETB. Esta API proporciona una capa de abstracción que simplifica la integración y mejora la experiencia del usuario final.

Propósito Principal

API Gateway: Centraliza el acceso a múltiples servicios backend
Orquestación: Coordina llamadas a diferentes sistemas
Transformación: Adapta formatos de datos entre sistemas
Seguridad: Implementa autenticación y autorización centralizada
Logging: Registra todas las transacciones para auditoría

Arquitectura del Sistema

Diagrama de Arquitectura General

mermaid

graph TD
    %% Cliente
    A[Cliente/Frontend] --> B[Experience XAPI Services]
    
    %% Capa de Entrada
    B --> C[HTTP Listener HTTPS]
    C --> D[APIKit Router]
    D --> E[Initial Logging]
    
    %% Capa de Routing
    E --> F{Endpoint Router}
    
    %% Endpoints Principales
    F -->|/operations/v1/orders| G[Orders Handler]
    F -->|/operations/v1/incident| H[Incident Handler]
    F -->|/operations/v1/customer/privacy| I[Privacy Handler]
    F -->|/billing/v1/billing_accounts| J[Billing Handler]
    F -->|/support/v1/imei| K[Support Handler]
    F -->|/v1/login| L[Login Handler]
    
    %% Capa de Orquestación
    G --> M[Orders Orchestrator]
    H --> N[Incident Orchestrator]
    I --> O[Privacy Orchestrator]
    J --> P[Billing Orchestrator]
    K --> Q[Support Orchestrator]
    L --> R[Login Orchestrator]
    
    %% Capa de Clientes
    M --> S[Operations PAPI Client]
    N --> T[Remedy SAPI Client]
    O --> U[Mongo SAPI Client]
    P --> V[Billing PAPI Client]
    Q --> W[Support Client]
    R --> X[Login Client]
    
    %% Sistemas Externos
    S --> Y[Operations PAPI Services]
    T --> Z[Remedy SAPI Services]
    U --> AA[Mongo SAPI Services]
    V --> BB[Billing PAPI Services]
    W --> CC[Support Services]
    X --> DD[Login Services]
    
    %% Base de Datos
    AA --> EE[(MongoDB)]
    Y --> FF[(Oracle DB)]
    Z --> GG[(Remedy System)]
    BB --> HH[(Billing System)]
    
    %% Utilidades
    B --> II[ETB Common Library]
    B --> JJ[Error Handler]
    B --> KK[Logging System]
    
    %% Estilos
    classDef client fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    classDef api fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    classDef handler fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px
    classDef orchestrator fill:#fff3e0,stroke:#e65100,stroke-width:2px
    classDef service fill:#e0f2f1,stroke:#004d40,stroke-width:2px
    classDef database fill:#f1f8e9,stroke:#33691e,stroke-width:2px
    classDef utility fill:#fafafa,stroke:#424242,stroke-width:2px
    
    class A client
    class B,C,D,E,F api
    class G,H,I,J,K,L handler
    class M,N,O,P,Q,R orchestrator
    class S,T,U,V,W,X service
    class Y,Z,AA,BB,CC,DD service
    class EE,FF,GG,HH database
    class II,JJ,KK utility

Capas del Sistema

Capa	Componente	Responsabilidad
API Gateway	HTTP Listener + APIKit Router	Recepción y enrutamiento de requests
Handler Layer	Endpoint Handlers	Validación y preparación de requests
Orchestrator Layer	Business Orchestrators	Lógica de negocio y orquestación
Client Layer	Service Clients	Comunicación con servicios externos
External Services	SAPI/PAPI Services	Servicios backend especializados

Sistemas Integrados

Sistema	Propósito	Tipo	Descripción
Mongo SAPI Services	Gestión de parámetros y datos del cliente	Base de Datos	Almacenamiento de configuraciones y datos dinámicos
Operations PAPI Services	Operaciones de red y servicios	Proceso	Gestión de órdenes y operaciones de red
Remedy SAPI Services	Gestión de incidentes y tickets	Soporte	Sistema de tickets y gestión de incidentes
Billing PAPI Services	Servicios de facturación	Negocio	Procesamiento de facturación y pagos
SAP SAPI Services	Integración con sistema ERP	Legacy	Integración con sistemas empresariales
Support PAPI Services	Servicios de soporte técnico	Soporte	Gestión de soporte al cliente
ETB MDM Services	Master Data Management	Datos	Gestión de datos maestros

Flujos de Datos

Flujo General de Comunicación entre Capas

mermaid

sequenceDiagram
    participant Client as Cliente/Frontend
    participant Gateway as API Gateway
    participant Handler as Handler Layer
    participant Orchestrator as Orchestrator Layer
    participant Client as Client Layer
    participant External as External Services
    participant DB as Database Layer
    
    Note over Client,DB: Flujo de Request
    Client->>Gateway: HTTP Request + Headers
    Gateway->>Gateway: Initial Logging
    Gateway->>Handler: Route Request
    Handler->>Handler: Validate & Transform
    Handler->>Orchestrator: Business Logic
    Orchestrator->>Client: Service Call
    Client->>External: External API Call
    External->>DB: Database Query
    DB-->>External: Data Response
    External-->>Client: Service Response
    Client-->>Orchestrator: Transformed Data
    Orchestrator-->>Handler: Business Response
    Handler-->>Gateway: Final Response
    Gateway->>Gateway: Async Logging
    Gateway-->>Client: HTTP Response

Patrones de Comunicación

Scatter-Gather Pattern

mermaid

graph TD
    A[Orchestrator] --> B[Scatter]
    B --> C[Service Call 1]
    B --> D[Service Call 2]
    B --> E[Service Call 3]
    
    C --> F[Response 1]
    D --> G[Response 2]
    E --> H[Response 3]
    
    F --> I[Gather]
    G --> I
    H --> I
    
    I --> J[DataWeave Transform]
    J --> K[Final Response]

Error Handling Pattern

mermaid

graph TD
    A[Request] --> B{Try}
    B --> C[Process Request]
    C --> D[Success Response]
    
    B --> E{Catch}
    E --> F[Error Handler]
    F --> G[Error Response]
    F --> H[Error Logging]
    
    D --> I[Final Response]
    G --> I

Dependencias del Sistema

mermaid

graph LR
    %% Experience XAPI Services
    A[Experience XAPI Services] --> B[ETB Common Library]
    A --> C[Error Handler]
    A --> D[Logging System]
    
    %% Dependencias Externas
    A --> E[Mongo SAPI Services]
    A --> F[Operations PAPI Services]
    A --> G[Remedy SAPI Services]
    A --> H[Billing PAPI Services]
    A --> I[SAP SAPI Services]
    A --> J[Support PAPI Services]
    A --> K[ETB MDM Services]
    A --> L[Audits Mongo SAPI Services]
    
    %% Base de Datos
    E --> M[(MongoDB)]
    F --> N[(Oracle DB)]
    G --> O[(Remedy System)]
    H --> P[(Billing System)]
    I --> Q[(SAP ERP)]
    J --> R[(Support System)]
    K --> S[(ETB MDM)]
    L --> M
    
    %% Estilos
    classDef main fill:#e1f5fe,stroke:#0277bd,stroke-width:3px
    classDef dependency fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
    classDef database fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px
    
    class A main
    class B,C,D,E,F,G,H,I,J,K,L dependency
    class M,N,O,P,Q,R,S database

🚀 Endpoints Principales

Operaciones de Cliente

Gestión de Privacidad

http

GET /operations/v1/customer/privacy
GET /operations/v2/customer/privacy
PATCH /operations/v1/customer/privacy

Gestión de Contacto

http

GET /operations/v1/customer/{client}/contact
POST /operations/v1/customer/{client}/contact
PATCH /operations/v1/customer/{client}/contact

Autenticación y Validación

http

GET /v1/login
POST /operations/v1/customer/otp
POST /operations/v1/customer/otp/validation
POST /operations/v1/customer/checkChannel

Operaciones de Servicio

Gestión de Órdenes

http

GET /operations/v1/orders/{orderNumber}
POST /operations/v1/orders/cancelOrder
POST /operations/v1/cancelOrder
PATCH /operations/v1/orders/{orderNumber}

Gestión de Incidentes

http

GET /operations/v1/incident/{ticketNumber}
POST /operations/v1/incident
POST /v1/incident

Inventario y Disponibilidad

http

GET /operations/v1/inventory/{serviceAccount}
POST /operations/v1/availability/confirm
POST /operations/v1/provisioning
POST /operations/v1/provisioning/confirm

Facturación

Cuentas y Ciclos

http

GET /billing/v1/billing_accounts/{account_id}/cycles
GET /billing/v1/hierarchy-account
POST /billing/v1/getInvoice

Negociaciones

http

POST /billing/v1/negociaciones/block_invoice
POST /billing/v1/negociaciones/change_invoice
POST /billing/v1/negociaciones/payment_notif
POST /billing/v1/negociaciones/solfact_checkdata
POST /billing/v1/negociaciones/solfact_getdata

Soporte Técnico

http

GET /support/v1/imei
POST /support/v1/positiveRecord

🔧 Configuración Técnica

Requisitos del Sistema

Mule Runtime: 4.4.0+
Java: JDK 11
Maven: 3.6.3+
Anypoint Platform: Acceso a CloudHub

Dependencias Principales

xml

<dependencies>
    <!-- Mule Connectors -->
    <dependency>
        <groupId>org.mule.connectors</groupId>
        <artifactId>mule-http-connector</artifactId>
        <version>1.7.1</version>
    </dependency>
    
    <!-- ETB Common Library -->
    <dependency>
        <groupId>com.etb</groupId>
        <artifactId>etb-common-lib</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </dependency>
    
    <!-- APIKit Module -->
    <dependency>
        <groupId>org.mule.modules</groupId>
        <artifactId>mule-apikit-module</artifactId>
        <version>1.9.0</version>
    </dependency>
</dependencies>

Configuración de Despliegue

mule-artifact.json

json

{
    "minMuleVersion": "4.3.0",
    "javaSpecificationVersions": ["11"],
    "secureProperties": [
        "autodiscovery",
        "anypoint.platform.client_id",
        "anypoint.platform.client_secret",
        "env"
    ]
}

Variables de Entorno Requeridas

Variable	Descripción	Ejemplo
`autodiscovery`	ID de autodescubrimiento en Anypoint Platform	`12345-67890`
`anypoint.platform.client_id`	Client ID para autenticación	`client_id_qa`
`anypoint.platform.client_secret`	Client Secret para autenticación	`client_secret_qa`
`env`	Ambiente de ejecución	`qa`, `prod`

📊 Ejemplo de Flujo Completo

Consulta de Privacidad del Cliente

mermaid

sequenceDiagram
    participant Client as Cliente
    participant XAPI as Experience XAPI
    participant Handler as Privacy Handler
    participant Orchestrator as Privacy Orchestrator
    participant MongoClient as Mongo Client
    participant MongoSAPI as Mongo SAPI
    participant MongoDB as MongoDB
    
    Client->>XAPI: GET /operations/v2/customer/privacy?operation=CANALES_HORARIOS
    XAPI->>XAPI: Initial Logging
    XAPI->>Handler: Route to Privacy Handler v2
    Handler->>Orchestrator: Execute Privacy Orchestrator v2
    Orchestrator->>Orchestrator: Scatter-Gather Pattern
    
    par Canales Query
        Orchestrator->>MongoClient: Query Canales
        MongoClient->>MongoSAPI: GET /parameters/canales
        MongoSAPI->>MongoDB: Query Database
        MongoDB-->>MongoSAPI: Canales Data
        MongoSAPI-->>MongoClient: Response
        MongoClient-->>Orchestrator: Canales Response
    and Horarios Query
        Orchestrator->>MongoClient: Query Horarios
        MongoClient->>MongoSAPI: GET /parameters/horarios
        MongoSAPI->>MongoDB: Query Database
        MongoDB-->>MongoSAPI: Horarios Data
        MongoSAPI-->>MongoClient: Response
        MongoClient-->>Orchestrator: Horarios Response
    end
    
    Orchestrator->>Orchestrator: DataWeave Transform
    Orchestrator-->>Handler: Transformed Response
    Handler-->>XAPI: Response
    XAPI->>XAPI: Async Logging
    XAPI-->>Client: Final Response

🔐 Enmascaramiento y Seguridad de Datos

Flujo de Encriptación/Desencriptación

mermaid

graph TD;
  A[Generar Payload] --> B[Encriptar con Servicio]
  B --> C[Obtener IV y Payload Encriptado]
  C --> D[Enviar a API Destino]
  D --> E[Recibir Respuesta Encriptada]
  E --> F[Desencriptar usando IV]
  F --> G[Obtener Respuesta en Texto Plano]

Manejo de Payloads y Variables

Payload Original: Guardar siempre en variable separada si se requiere reutilización
IV (Vector de Inicialización): Esencial para seguridad, enviar junto con payload encriptado
Manejo de Errores: Implementar robusto para evitar pérdida de información

Configuración Dinámica de Endpoints

java

// Ejemplo de lógica dinámica por ambiente
if (processEnv.equals("qa")) {
    endpoint = "box.services.qa";
} else if (processEnv.equals("prod")) {
    endpoint = "box.services.prod";
}

Variables Secretas Críticas

azure_secret
client_id
client_secret
env

⚠️ Importante: Estas variables no deben estar en el código fuente. Solicítalas al equipo responsable o configúralas como variables de entorno.

📝 Logging y Monitoreo

Estructura de Logs

json

{
    "timestamp": "2024-01-15T10:30:00Z",
    "level": "INFO",
    "category": "experience-xapi-services",
    "correlationId": "12345-67890",
    "message": "Request processed successfully",
    "endpoint": "/operations/v2/customer/privacy",
    "duration": 150,
    "status": 200
}

Categorías de Log

initial-loggin: Logging inicial de requests
loggin-client-call: Logging de llamadas a clientes
error_loggin: Logging de errores
experience-xapi-services: Logs generales de la aplicación

🧪 Testing

Pruebas MUnit

La aplicación incluye pruebas unitarias usando MUnit:

bash

# Ejecutar pruebas
mvn test

# Generar reporte de cobertura
mvn munit:coverage-report

Casos de Prueba Principales

Validación de endpoints
Manejo de errores
Transformación de datos
Integración con servicios externos
Flujo de enmascaramiento y desencriptación

🚀 Despliegue

Obtención del Código Fuente

bash

# Clonar el repositorio desde Azure DevOps
git clone https://informaticaetb.visualstudio.com/_git/MULESOFT
cd MULESOFT/APIS/experience-xapi-services

# O navegar directamente a la carpeta de la API
cd APIS/experience-xapi-services

Despliegue Local

bash

# Compilar
mvn clean package

# Ejecutar localmente
mvn mule:run

Despliegue en CloudHub

bash

# Desplegar en QA
mvn deploy -Denv=qa -Dusername=<username> -Dpassword=<password>

# Desplegar en Producción
mvn deploy -Denv=prod -Dusername=<username> -Dpassword=<password>

Pipeline de CI/CD

El proyecto utiliza Azure DevOps Pipelines para automatizar el proceso de build y deploy:

Build Pipeline: Compilación automática en cada commit
Test Pipeline: Ejecución de pruebas MUnit
Deploy Pipeline: Despliegue automático a CloudHub
Quality Gates: Validaciones de calidad antes del merge

Configuración del Pipeline

yaml

# Ejemplo de azure-pipelines.yml
trigger:
  branches:
    include:
    - main
    - develop

pool:
  vmImage: 'ubuntu-latest'

steps:
- task: Maven@3
  inputs:
    mavenPomFile: 'APIS/experience-xapi-services/pom.xml'
    goals: 'clean package'
    publishJUnitResults: true
    testResultsFiles: '**/TEST-*.xml'

Configuración de CloudHub

xml

<cloudHubDeployment>
    <objectStoreV2>true</objectStoreV2>
    <uri>https://anypoint.mulesoft.com</uri>
    <muleVersion>4.4.0</muleVersion>
    <applicationName>experience-xapi-services</applicationName>
    <environment>${environment}</environment>
    <region>${region}</region>
    <workers>${workers}</workers>
    <workerType>${workerType}</workerType>
</cloudHubDeployment>

📚 Buenas Prácticas

Convenciones de Código

Usar nombres descriptivos para flows y variables
Documentar endpoints con comentarios
Implementar manejo de errores robusto
Seguir patrones de logging establecidos
Centralizar lógica de encriptación/desencriptación

Manejo de Secretos

Nunca versionar variables sensibles en el código fuente
Usar archivos de propiedades seguras o variables de entorno
Documentar claramente qué secretos requiere cada API
Implementar pruebas para validar flujos de enmascaramiento

Estructura del Proyecto

text

experience-xapi-services/
  ├── pom.xml                  # Configuración Maven y dependencias
  ├── mule-artifact.json       # Metadatos Mule (versión mínima, propiedades seguras)
  ├── src/
  │    ├── main/
  │    │    ├── mule/          # Flujos principales (*.xml)
  │    │    ├── resources/     # log4j2.xml, properties, YAML, JSON, etc.
  │    └── test/               # Pruebas MUnit
  └── target/                  # Artefactos .jar/.zip

📚 Recursos Adicionales

Repositorio y Código Fuente

Azure DevOps Repository: MULESOFT - APIS/experience-xapi-services
Branch Principal: main

Glosario

API Gateway: Punto de entrada centralizado para múltiples servicios
Orchestrator: Componente que coordina llamadas a servicios externos
Scatter-Gather: Patrón para ejecutar consultas en paralelo
DataWeave: Lenguaje de transformación de datos en MuleSoft
MUnit: Framework de pruebas unitarias para MuleSoft
CloudHub: Plataforma de despliegue en la nube de MuleSoft
IV (Vector de Inicialización): Componente crítico para encriptación/desencriptación

📚 Soporte

Para soporte técnico o consultas sobre esta API:

Equipo de Desarrollo: [desarrollo@etb.com.co]

Nota Importante

Esta documentación se actualiza regularmente. Para la versión más reciente, consulta el repositorio oficial o contacta al equipo de desarrollo.

Experience XAPI Services ​

Descripción General ​

Propósito Principal ​

Arquitectura del Sistema ​

Diagrama de Arquitectura General ​

Capas del Sistema ​

Sistemas Integrados ​

Flujos de Datos ​

Flujo General de Comunicación entre Capas ​

Patrones de Comunicación ​

Scatter-Gather Pattern ​

Error Handling Pattern ​

Dependencias del Sistema ​

🚀 Endpoints Principales ​

Operaciones de Cliente ​

Gestión de Privacidad ​

Gestión de Contacto ​

Autenticación y Validación ​

Operaciones de Servicio ​

Gestión de Órdenes ​

Gestión de Incidentes ​

Inventario y Disponibilidad ​

Facturación ​

Cuentas y Ciclos ​

Negociaciones ​

Soporte Técnico ​

🔧 Configuración Técnica ​

Requisitos del Sistema ​

Dependencias Principales ​

Configuración de Despliegue ​

mule-artifact.json ​

Variables de Entorno Requeridas ​

📊 Ejemplo de Flujo Completo ​

Consulta de Privacidad del Cliente ​

🔐 Enmascaramiento y Seguridad de Datos ​

Flujo de Encriptación/Desencriptación ​

Manejo de Payloads y Variables ​

Configuración Dinámica de Endpoints ​

Variables Secretas Críticas ​

📝 Logging y Monitoreo ​

Estructura de Logs ​

Categorías de Log ​

🧪 Testing ​

Pruebas MUnit ​

Casos de Prueba Principales ​

🚀 Despliegue ​

Obtención del Código Fuente ​

Despliegue Local ​

Despliegue en CloudHub ​

Pipeline de CI/CD ​

Configuración del Pipeline ​

Configuración de CloudHub ​

📚 Buenas Prácticas ​

Convenciones de Código ​

Manejo de Secretos ​

Estructura del Proyecto ​

📚 Recursos Adicionales ​

Repositorio y Código Fuente ​

Glosario ​

📚 Soporte ​

Experience XAPI Services

Descripción General

Propósito Principal

Arquitectura del Sistema

Diagrama de Arquitectura General

Capas del Sistema

Sistemas Integrados

Flujos de Datos

Flujo General de Comunicación entre Capas

Patrones de Comunicación

Scatter-Gather Pattern

Error Handling Pattern

Dependencias del Sistema

🚀 Endpoints Principales

Operaciones de Cliente

Gestión de Privacidad

Gestión de Contacto

Autenticación y Validación

Operaciones de Servicio

Gestión de Órdenes

Gestión de Incidentes

Inventario y Disponibilidad

Facturación

Cuentas y Ciclos

Negociaciones

Soporte Técnico

🔧 Configuración Técnica

Requisitos del Sistema

Dependencias Principales

Configuración de Despliegue

mule-artifact.json

Variables de Entorno Requeridas

📊 Ejemplo de Flujo Completo

Consulta de Privacidad del Cliente

🔐 Enmascaramiento y Seguridad de Datos

Flujo de Encriptación/Desencriptación

Manejo de Payloads y Variables

Configuración Dinámica de Endpoints

Variables Secretas Críticas

📝 Logging y Monitoreo

Estructura de Logs

Categorías de Log

🧪 Testing

Pruebas MUnit

Casos de Prueba Principales

🚀 Despliegue

Obtención del Código Fuente

Despliegue Local

Despliegue en CloudHub

Pipeline de CI/CD

Configuración del Pipeline

Configuración de CloudHub

📚 Buenas Prácticas

Convenciones de Código

Manejo de Secretos

Estructura del Proyecto

📚 Recursos Adicionales

Repositorio y Código Fuente

Glosario

📚 Soporte