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

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

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

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

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

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

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

Gestión de Contacto

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

Autenticación y Validación

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

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

Gestión de Incidentes

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

Inventario y Disponibilidad

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

Facturación

Cuentas y Ciclos

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

Negociaciones

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

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

<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

{
    "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

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

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

// 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

{
    "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:

# 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

# 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

# Compilar
mvn clean package

# Ejecutar localmente
mvn mule:run

Despliegue en CloudHub

# 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

# 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

<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

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.