Commerce XAPI Services

Información General

Commerce XAPI Services es el API Gateway especializado para servicios de comercio en ETB, proporcionando una interfaz unificada para sistemas de catálogo, órdenes, pagos y gestión de clientes.

Descripción General

Commerce XAPI Services actúa como API Gateway especializado que orquesta y gestiona las comunicaciones entre sistemas de comercio, aplicaciones de venta y múltiples servicios backend de ETB. Esta API proporciona una capa de abstracción que simplifica la integración de catálogos de productos, procesamiento de órdenes, pagos y gestión de clientes.

Propósito Principal

Catálogo de Productos: Centraliza la consulta y gestión de productos
Órdenes de Compra: Procesa y administra órdenes de clientes
Pagos: Gestiona el ciclo de pagos y validaciones
Gestión de Clientes: Administra información y autenticación de clientes
Integración Omnicanal: Permite la integración con diferentes canales de venta

Arquitectura del Sistema

Diagrama de Arquitectura General

mermaid

graph TD
    A[Canales de Venta] --> B[Commerce XAPI Services]
    B --> C[HTTP Listener]
    C --> D[APIKit Router]
    D --> E[Initial Logging]
    E --> F{Endpoint Router}
    F -->|/v1/catalog| G[Catálogo Handler]
    F -->|/v1/orders| H[Órdenes Handler]
    F -->|/v1/payments| I[Pagos Handler]
    F -->|/v1/customers| J[Clientes Handler]
    G --> K[Catálogo Orchestrator]
    H --> L[Órdenes Orchestrator]
    I --> M[Pagos Orchestrator]
    J --> N[Clientes Orchestrator]
    K --> O[Catálogo Service]
    L --> P[Órdenes Service]
    M --> Q[Pagos Service]
    N --> R[Clientes Service]
    O --> S[Catálogo DB]
    P --> T[Órdenes DB]
    Q --> U[Pagos DB]
    R --> V[Clientes DB]
    B --> W[ETB Common Library]
    B --> X[Error Handler]
    B --> Y[Logging System]
    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
    class G,H,I,J handler
    class K,L,M,N orchestrator
    class O,P,Q,R service
    class S,T,U,V database

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	Business Orchestrators	Lógica de negocio y orquestación
Service Layer	Service Clients	Comunicación con servicios externos
Database	Catálogo, Órdenes, Pagos, Clientes	Persistencia de datos

Endpoints Principales

Catálogo de Productos

http

GET /v1/catalog
GET /v1/catalog/{productId}
POST /v1/catalog
PATCH /v1/catalog/{productId}
DELETE /v1/catalog/{productId}

Órdenes de Compra

http

GET /v1/orders
GET /v1/orders/{orderId}
POST /v1/orders
PATCH /v1/orders/{orderId}
DELETE /v1/orders/{orderId}

Pagos

http

GET /v1/payments
GET /v1/payments/{paymentId}
POST /v1/payments
PATCH /v1/payments/{paymentId}

Gestión de Clientes

http

GET /v1/customers
GET /v1/customers/{customerId}
POST /v1/customers
PATCH /v1/customers/{customerId}

Flujos de Datos

mermaid

graph LR
    A[Commerce XAPI Services] --> B[ETB Common Library]
    A --> C[Error Handler]
    A --> D[Logging System]
    A --> E[Catálogo Service]
    A --> F[Órdenes Service]
    A --> G[Pagos Service]
    A --> H[Clientes Service]
    E --> I[(Catálogo DB)]
    F --> J[(Órdenes DB)]
    G --> K[(Pagos DB)]
    H --> L[(Clientes DB)]
    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 dependency
    class I,J,K,L database

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>
        <classifier>mule-plugin</classifier>
    </dependency>
    <!-- Otros conectores Mule según necesidades de negocio -->
    <!-- ETB Common Library -->
    <dependency>
        <groupId>com.etb</groupId>
        <artifactId>etb-common-lib</artifactId>
        <version>1.0.0-SNAPSHOT</version>
        <classifier>mule-plugin</classifier>
    </dependency>
    <!-- APIKit Module -->
    <dependency>
        <groupId>org.mule.modules</groupId>
        <artifactId>mule-apikit-module</artifactId>
        <version>1.9.0</version>
        <classifier>mule-plugin</classifier>
    </dependency>
    <!-- Validation Module -->
    <dependency>
        <groupId>org.mule.modules</groupId>
        <artifactId>mule-validation-module</artifactId>
        <version>2.0.1</version>
        <classifier>mule-plugin</classifier>
    </dependency>
</dependencies>

Configuración de Despliegue

mule-artifact.json

json

{
    "minMuleVersion": "4.4.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`

Seguridad

Autenticación

OAuth 2.0: Implementado para autenticación de clientes
Client Credentials: Para comunicación entre servicios
TLS/SSL: Todas las comunicaciones son cifradas

Propiedades Seguras

Las siguientes propiedades están marcadas como seguras y no deben versionarse:

autodiscovery
anypoint.platform.client_id
anypoint.platform.client_secret
env

Headers Requeridos

http

X-CORRELATION-ID: <correlation-id>
source: <application-source>
name: <application-name>
client_secret: <client-secret>
client_id: <client-id>
systemId: <system-id>
processName: <process-name>

Logging y Monitoreo

Estructura de Logs

json

{
    "timestamp": "2024-01-15T10:30:00Z",
    "level": "INFO",
    "category": "commerce-xapi-services",
    "correlationId": "12345-67890",
    "message": "Order created successfully",
    "endpoint": "/v1/orders",
    "duration": 150,
    "status": 201,
    "customerId": "customer-123",
    "channel": "web"
}

Categorías de Log

initial-loggin: Logging inicial de requests
loggin-client-call: Logging de llamadas a clientes
error_loggin: Logging de errores
commerce-xapi-services: Logs generales de la aplicació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/commerce-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/commerce-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>commerce-xapi-services</applicationName>
    <environment>${environment}</environment>
    <region>${region}</region>
    <workers>${workers}</workers>
    <workerType>${workerType}</workerType>
</cloudHubDeployment>

Recursos Adicionales

Repositorio y Código Fuente

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

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.

Commerce XAPI Services ​

Descripción General ​

Propósito Principal ​

Arquitectura del Sistema ​

Diagrama de Arquitectura General ​

Capas del Sistema ​

Endpoints Principales ​

Catálogo de Productos ​

Órdenes de Compra ​

Pagos ​

Gestión de Clientes ​

Flujos de Datos ​

Configuración Técnica ​

Requisitos del Sistema ​

Dependencias Principales ​

Configuración de Despliegue ​

mule-artifact.json ​

Variables de Entorno Requeridas ​

Seguridad ​

Autenticación ​

Propiedades Seguras ​

Headers Requeridos ​

Logging y Monitoreo ​

Estructura de Logs ​

Categorías de Log ​

Despliegue ​

Obtención del Código Fuente ​

Despliegue Local ​

Despliegue en CloudHub ​

Pipeline de CI/CD ​

Configuración del Pipeline ​

Configuración de CloudHub ​

Recursos Adicionales ​

Repositorio y Código Fuente ​

Commerce XAPI Services

Descripción General

Propósito Principal

Arquitectura del Sistema

Diagrama de Arquitectura General

Capas del Sistema

Endpoints Principales

Catálogo de Productos

Órdenes de Compra

Pagos

Gestión de Clientes

Flujos de Datos

Configuración Técnica

Requisitos del Sistema

Dependencias Principales

Configuración de Despliegue

mule-artifact.json

Variables de Entorno Requeridas

Seguridad

Autenticación

Propiedades Seguras

Headers Requeridos

Logging y Monitoreo

Estructura de Logs

Categorías de Log

Despliegue

Obtención del Código Fuente

Despliegue Local

Despliegue en CloudHub

Pipeline de CI/CD

Configuración del Pipeline

Configuración de CloudHub

Recursos Adicionales

Repositorio y Código Fuente