Bot XAPI Services

Información General

Bot XAPI Services es el API Gateway especializado para servicios de bot y automatización en ETB, proporcionando una interfaz unificada para sistemas de chat, omnicanalidad y gestión de casos automatizados.

Descripción General

Bot XAPI Services actúa como API Gateway especializado que orquesta y gestiona las comunicaciones entre sistemas de bot, aplicaciones de omnicanalidad y múltiples servicios backend de ETB. Esta API proporciona una capa de abstracción que simplifica la integración de chatbots, sistemas de atención automatizada y gestión de casos.

Propósito Principal

Bot Integration: Centraliza la integración con sistemas de chatbot y automatización
Omnicanalidad: Gestiona interacciones multicanal (chat, web, móvil)
Case Management: Administra casos y tickets de soporte automatizado
Sales Order: Procesa órdenes de venta y catálogos de productos
Customer Data: Gestiona información de clientes y contactos
Digital Records: Maneja registros digitales y documentación

Arquitectura del Sistema

Diagrama de Arquitectura General

mermaid

graph TD
    A[Bot/Chatbot] --> B[Bot XAPI Services]
    C[Omnicanal App] --> B
    D[Sales System] --> B
    
    B --> E[HTTP Listener]
    E --> F[APIKit Router]
    F --> G[Initial Logging]
    
    G --> H{Endpoint Router}
    
    H -->|/v1/contacts| I[Contacts Handler]
    H -->|/v1/cases| J[Cases Handler]
    H -->|/v1/omnicanalidad| K[Omnicanalidad Handler]
    H -->|/v1/customers| L[Customers Handler]
    H -->|/v1/salesOrder| M[Sales Order Handler]
    H -->|/v1/parameters| N[Parameters Handler]
    H -->|/v1/digitalRecord| O[Digital Record Handler]
    
    I --> P[Contacts Orchestrator]
    J --> Q[Cases Orchestrator]
    K --> R[Omnicanalidad Orchestrator]
    L --> S[Customers Orchestrator]
    M --> T[Sales Order Orchestrator]
    N --> U[Parameters Orchestrator]
    O --> V[Digital Record Orchestrator]
    
    P --> W[CRM Client]
    Q --> X[Case Management Client]
    R --> Y[Omnicanal Client]
    S --> Z[Customer Client]
    T --> AA[Sales Client]
    U --> BB[Parameters Client]
    V --> CC[Document Client]
    
    W --> DD[CRM System]
    X --> EE[Case Management System]
    Y --> FF[Omnicanal Platform]
    Z --> GG[Customer Database]
    AA --> HH[Sales System]
    BB --> II[Parameters Service]
    CC --> JJ[Document Management]
    
    DD --> KK[(CRM DB)]
    EE --> LL[(Case DB)]
    FF --> MM[(Omnicanal DB)]
    GG --> NN[(Customer DB)]
    HH --> OO[(Sales DB)]
    II --> PP[(Parameters DB)]
    JJ --> QQ[(Document Store)]
    
    B --> RR[ETB Common Library]
    B --> SS[Error Handler]
    B --> TT[Logging System]
    
    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,C,D client
    class B,E,F,G,H api
    class I,J,K,L,M,N,O handler
    class P,Q,R,S,T,U,V orchestrator
    class W,X,Y,Z,AA,BB,CC service
    class DD,EE,FF,GG,HH,II,JJ service
    class KK,LL,MM,NN,OO,PP,QQ database
    class RR,SS,TT 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	CRM, Case Management, Sales	Servicios backend especializados

Sistemas Integrados

Sistema	Propósito	Tipo	Descripción
CRM System	Gestión de relaciones con clientes	Negocio	Sistema de gestión de clientes y contactos
Case Management	Gestión de casos y tickets	Soporte	Sistema de tickets y seguimiento de casos
Omnicanal Platform	Atención multicanal	Experiencia	Plataforma de atención omnicanal
Sales System	Gestión de ventas y órdenes	Negocio	Sistema de procesamiento de ventas
Parameters Service	Configuraciones dinámicas	Configuración	Servicio de parámetros y catálogos
Document Management	Gestión de documentos	Archivo	Sistema de almacenamiento de documentos
Customer Database	Base de datos de clientes	Datos	Información centralizada de clientes

Flujos de Datos

Dependencias del Sistema

mermaid

graph LR
    A[Bot XAPI Services] --> B[ETB Common Library]
    A --> C[Error Handler]
    A --> D[Logging System]
    
    A --> E[CRM System]
    A --> F[Case Management System]
    A --> G[Omnicanal Platform]
    A --> H[Sales System]
    A --> I[Parameters Service]
    A --> J[Document Management]
    A --> K[Customer Database]
    
    E --> L[(CRM Database)]
    F --> M[(Case Database)]
    G --> N[(Omnicanal Database)]
    H --> O[(Sales Database)]
    I --> P[(Parameters Database)]
    J --> Q[(Document Store)]
    K --> R[(Customer Database)]
    
    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 dependency
    class L,M,N,O,P,Q,R database

Endpoints Principales

Gestión de Contactos

http

GET /v1/contacts
POST /v1/contacts

Gestión de Casos

http

GET /v1/cases
POST /v1/cases
PATCH /v1/cases

Omnicanalidad

http

GET /v1/omnicanalidad/interaction
PATCH /v1/omnicanalidad/interaction

Gestión de Clientes

http

GET /v1/customers
GET /v1/account

Órdenes de Venta

http

GET /v1/salesOrder/catalog
GET /v2/salesOrder/catalog
POST /v1/salesOrder/catalog/validate
POST /v1/salesOrder/order/{operation}
GET /v1/salesOrder/customer
POST /v1/salesOrder/simcards
POST /v1/salesOrder/payments
POST /v1/salesOrder/portabilities/{operation}

Parámetros y Configuración

http

GET /v1/parameters/cities
GET /v1/parameters/departments
GET /v1/parameters/operators
GET /v1/parameters/businessdays
GET /v1/parameters/servicestypeportability

Registros Digitales

http

GET /v1/digitalRecord
POST /v1/digitalRecord

Recursos y Activos

http

GET /v1/asset
GET /v1/businessHours
POST /v1/logs

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>
    
    <!-- JMS Connector -->
    <dependency>
        <groupId>org.mule.connectors</groupId>
        <artifactId>mule-jms-connector</artifactId>
        <version>1.8.4</version>
        <classifier>mule-plugin</classifier>
    </dependency>
    
    <!-- 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`

Ejemplo de Flujo Completo

Flujo General de Operaciones - Bot XAPI Services

mermaid

sequenceDiagram
    participant Client as Cliente/Bot
    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
    
    Client->>Gateway: HTTP Request
    Note over Client,Gateway: GET/POST/PATCH /v1/{resource}
    
    Gateway->>Gateway: Initial Logging
    Gateway->>Gateway: APIKit Router
    Gateway->>Handler: Route to Specific Handler
    
    Handler->>Handler: Validate Request
    Handler->>Handler: Parse Parameters
    Handler->>Orchestrator: Execute Business Logic
    
    Orchestrator->>Orchestrator: Data Transformation
    Orchestrator->>Orchestrator: Business Rules
    Orchestrator->>Client: Call External Service
    
    Client->>External: HTTP/API Call
    External->>DB: Database Operation
    DB-->>External: Data Response
    External-->>Client: Service Response
    
    Client-->>Orchestrator: Processed Data
    Orchestrator->>Orchestrator: Response Formatting
    Orchestrator->>Orchestrator: Error Handling
    Orchestrator-->>Handler: Formatted Response
    
    Handler->>Handler: Response Validation
    Handler-->>Gateway: Final Response
    Gateway->>Gateway: Async Logging
    Gateway-->>Client: HTTP Response

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": "bot-xapi-services",
    "correlationId": "12345-67890",
    "message": "Case created successfully",
    "endpoint": "/v1/cases",
    "duration": 150,
    "status": 201,
    "botSession": "session-123",
    "channel": "webchat"
}

Categorías de Log

initial-loggin: Logging inicial de requests
loggin-client-call: Logging de llamadas a clientes
error_loggin: Logging de errores
bot-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/bot-xapi-services

# O navegar directamente a la carpeta de la API
cd APIS/bot-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/bot-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>bot-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/bot-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.

Bot XAPI Services ​

Descripción General ​

Propósito Principal ​

Arquitectura del Sistema ​

Diagrama de Arquitectura General ​

Capas del Sistema ​

Sistemas Integrados ​

Flujos de Datos ​

Dependencias del Sistema ​

Endpoints Principales ​

Gestión de Contactos ​

Gestión de Casos ​

Omnicanalidad ​

Gestión de Clientes ​

Órdenes de Venta ​

Parámetros y Configuración ​

Registros Digitales ​

Recursos y Activos ​

Configuración Técnica ​

Requisitos del Sistema ​

Dependencias Principales ​

Configuración de Despliegue ​

mule-artifact.json ​

Variables de Entorno Requeridas ​

Ejemplo de Flujo Completo ​

Flujo General de Operaciones - Bot XAPI Services ​

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 ​

Bot XAPI Services

Descripción General

Propósito Principal

Arquitectura del Sistema

Diagrama de Arquitectura General

Capas del Sistema

Sistemas Integrados

Flujos de Datos

Dependencias del Sistema

Endpoints Principales

Gestión de Contactos

Gestión de Casos

Omnicanalidad

Gestión de Clientes

Órdenes de Venta

Parámetros y Configuración

Registros Digitales

Recursos y Activos

Configuración Técnica

Requisitos del Sistema

Dependencias Principales

Configuración de Despliegue

mule-artifact.json

Variables de Entorno Requeridas

Ejemplo de Flujo Completo

Flujo General de Operaciones - Bot XAPI Services

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