External Integrations

1. Feature Descripción General

The integration Arquitectura connects Algesta with external systems for electronic signatures (DocuSign), project management (Asana), client data synchronization (Qsystems), Documento storage (Azure Blob), operational messaging (Jelou WhatsApp), and AI services (OCR for serial recognition). These integrations enable seamless workflows spanning signature collection, asset identification, client communication, and internal task management while maintaining data consistency and operational efficiency across platforms.

2. Integration Resumen

System	Purpose	Status	Sprints	Integration Método
Jelou WhatsApp	Order capture, notifications, Estado updates	✅ Completo	S2-S8	Webhook + REST API
DocuSign	Electronic signature for contracts, policies	✅ Completo	S5-S6	REST API (via Logic Apps or SDK)
Azure Blob Storage	Documento and photo storage	✅ Completo	S2-S8	Azure Storage SDK
OCR Service	Serial recognition from photos	🟡 En Progreso	S6-S8	REST API (Azure Computer Vision or custom)
Asana	Internal workflow and task management	🟡 Partial	S5	REST API via Logic Apps
Qsystems	Enterprise client data sync	🟡 Partial	S1-S2	API Management Gateway

3. Jelou WhatsApp Integration

Propósito

Primary channel for client interaction: order creation, tracking, notifications, execution confirmation

Arquitectura

Type: Webhook-based, bidirectional communication
Flow: Client → WhatsApp → Jelou Bot → Algesta Gateway → Microservicios → Notifications → Jelou → WhatsApp → Client
Data Exchange: JSON payloads with order data, photos, client info

Jelou Bot Structure

Configuration: algesta-agent/jelou/bot.json

Skills:

Registration: Capture client info (name, email, phone, location)
Order Creation: Parse service request, extract details, create order
Photo Upload: Handle asset/serial photos, upload to Azure Blob
Order Tracking: Query order Estado by order number
PDF Generation: Generate order Resumen PDFs
Estado Updates: Notify client of state changes
Execution Confirmation: Confirm work start/completion dates

Implementación: algesta-agent/jelou/skills/skill_*.json

User Stories

US-S2-001: WhatsApp Order Creation

Descripción: Client sends message to WhatsApp and order is created automatically
Estado: ✅ Completo
Pruebas: Sprint 2 - WhatsApp flows validated

US-S8-035: Execution Date Confirmation via WhatsApp

Descripción: Client confirms execution date via WhatsApp
Estado: ✅ Completo
Pruebas: Integration validated - bugs resolved after QA review

API Integration

Inbound (Jelou → Algesta):

POST /api/jelou/webhook - Receive messages from Jelou

Outbound (Algesta → Jelou):

Jelou REST API for sending messages

Implementación: algesta-api-gateway-nestjs/src/infrastructure/controllers/jelou.controller.ts

Pruebas Evidence

Sprint 2: WhatsApp integration validated with order creation, photo upload, notifications
Sprint 8: Execution date confirmation tested (partial validation due to API issues)

4. DocuSign Integration

Propósito

Electronic signature for contracts, policies, agreements after quotation approval

Arquitectura

Type: REST API integration via Logic Apps or direct SDK
Flow: Agent triggers → Documentos sent to DocuSign → Parties receive email → Sign → Estado tracked → Documentos downloaded

Signature Workflow

sequenceDiagram
    participant Agent
    participant Gateway
    participant OrdersMS
    participant DocuSign
    participant Client
    participant Provider

    Agent->>Gateway: POST /api/orders/:id/send-to-signature
    Gateway->>OrdersMS: SendToSignatureCommand
    OrdersMS->>OrdersMS: Generate contract documents
    OrdersMS->>DocuSign: POST /envelopes (with documents)
    DocuSign->>DocuSign: Create envelope with 3 signers
    DocuSign->>Client: Email: "Please sign contract"
    DocuSign->>Provider: Email: "Please sign contract"
    DocuSign->>Agent: Email: "Please sign contract"

    Note over Client,Provider: All parties sign

    DocuSign->>OrdersMS: Webhook: Envelope status changed
    OrdersMS->>OrdersMS: Update order state based on status
    alt All signed
        OrdersMS->>OrdersMS: State → PolizaAsignada
        OrdersMS->>DocuSign: GET /envelopes/:id/documents
        DocuSign-->>OrdersMS: Signed documents
        OrdersMS->>AzureBlob: Store signed documents
    else Rejected
        OrdersMS->>OrdersMS: State → DocumentosRechazados
    end

User Stories

US-S5-015: Send Documentos to Electronic Signature

Descripción: Agent sends contracts for electronic signature after quotation approval
Estado: ✅ Completo
Pruebas: Sprint 5 - signature sending validated

US-S6-018: View Signature Estado

Descripción: Agent views signature status (En Progreso, signed, rejected)
Estado: ✅ Completo
Pruebas: Sprint 6 - signature Status tracking validated

Signature States

State	Color	Description
En Proceso	🔵 Blue	Waiting for signatures
Firmado	🟢 Green	All parties signed
Rechazado	🔴 Red	Signature rejected by one party

API Integration

DocuSign REST API v2
Implementación: algesta-ms-orders-nestjs/src/shared/services/docusign.service.ts (if exists)
Endpoints:
- POST /api/orders/:id/send-to-signature - Send Documentos to DocuSign
- GET /api/orders/:id/signature-Estado - Get signature status

Pruebas Evidence

Sprint 5-6: Electronic signature integration tested with Documento sending, Status tracking, signed Documento retrieval

5. Azure Blob Storage Integration

Propósito

Secure storage for photos, Documentos, reports, contracts

Arquitectura

Type: Azure Storage SDK, container-based organization
Flow: Upload → Generate SAS URL → Store URL in MongoDB → Retrieve for display/download

Container Organization

Container	Content	Access Level
orders	Order photos, attachments	Private (SAS token required)
providers	Provider Documentos (ARL, EPS, RUT, etc.)	Private
assets	Asset photos, serial plates	Private
contracts	Signed contracts from DocuSign	Private
reports	Execution reports, HV PDFs	Private

Security

SAS Tokens: Time-limited access tokens with expiration
RBAC: Role-based access control at container level
HTTPS Only: All transfers over HTTPS
Access Logging: All access logged for audit

Implementación

algesta-ms-provider-nestjs/src/shared/services/azure-storage.service.ts
algesta-ms-orders-nestjs/src/shared/services/azure-storage.service.ts

API

Azure Blob Storage REST API

6. OCR Service Integration

Propósito

Automatic serial number recognition from asset photos

Arquitectura

Type: REST API to OCR service (Azure Computer Vision, Google Vision, or custom)
Flow: Photo upload → OCR processing → Extract serial → Retry logic (2-3 attempts) → Manual confirmation if fails → Generate unique ID if illegible

OCR Workflow

sequenceDiagram
    participant Technician
    participant Gateway
    participant OrdersMS
    participant OCRService
    participant AzureBlob

    Technician->>Gateway: Upload serial plate photo
    Gateway->>OrdersMS: RecognizeSerialCommand
    OrdersMS->>AzureBlob: Upload photo
    AzureBlob-->>OrdersMS: Photo URL
    OrdersMS->>OCRService: POST /analyze (photo URL)
    OCRService->>OCRService: Process image (OCR)
    alt Serial recognized
        OCRService-->>OrdersMS: Extracted text with confidence
        OrdersMS->>OrdersMS: Parse serial from text
        OrdersMS-->>Gateway: Serial: ABC123456 (95% confidence)
    else Serial not recognized (retry)
        OCRService-->>OrdersMS: No serial found or low confidence
        OrdersMS-->>Gateway: Please retake photo (attempt 1/3)
    end

User Stories

US-S6-022: Serial Recognition via Photo

Descripción: Technician photographs asset serial plate, system recognizes it automatically
Estado: 🟡 En Progreso
Pruebas: Sprint 6-7 - serial recognition tested with sample photos

US-S7-027: Automated HV Creation with Serial

Descripción: System automatically creates asset HV using OCR-recognized serial
Estado: 🟡 En Progreso
Pruebas: Sprint 7 - Historia 16016 validated

Known Issues

Accuracy: Depends on photo quality, lighting, serial visibility
WhatsApp Business Impediment: Photo capture from WhatsApp unreliable in S7-S8 ✅ Resolved

Future Enhancements

AI Model Retraining: Collect more samples to improve accuracy
Multi-Language Support: Recognize serials in different languages/scripts

Implementación

algesta-ms-orders-nestjs/src/shared/services/ocr.service.ts
algesta-ms-orders-nestjs/src/shared/services/ocr-label-extractor.service.ts

API

OCR Service REST API (Azure Computer Vision or custom)
Endpoints:
- POST /api/assets/recognize-serial - OCR serial from photo

7. Asana Integration

Propósito

Internal task management and workflow coordination

Arquitectura

Type: Logic Apps or REST API integration
Flow: Order creation → Create Asana task → Update task on state changes → Close task on order closure

Workflow

Order Created: Create Asana task in “Incoming Requests” project
Order Assigned: Assign task to agent in Asana
State Changes: Update task Estado based on order state
Order Closed: Mark task Completo

Estado

🟡 Partial - Documentoed in Sprint 5 but not fully implemented

Future Implementación

Completo Asana API integration
Bidirectional sync (Asana task updates → Order updates)
Asana project templates per service type

API

Asana REST API v1

8. Qsystems Integration

Propósito

Sync client data from enterprise system (for large clients with existing ERP)

Arquitectura

Type: API Management gateway, REST API integration
Flow: Client lookup by NIT → Fetch client data → Create/update client in Algesta

Use Cases

Client Validation: Verify client exists in Qsystems before order creation
Client Data Sync: Update client info (address, contacts) from Qsystems
Contract Data: Fetch contract details for invoicing

User Stories

US-S2-005: NIT Validation and Client Lookup

Descripción: Validate client NIT against Qsystems during registration
Estado: 🟡 Partial - Documentoed but not fully implemented

Estado

🟡 Partial - Documentoed in context.md but not fully implemented

Future Implementación

Completo Qsystems API integration via Azure API Management
Scheduled sync jobs for client data updates
Invoice integration for accounting

API

Qsystems REST API (protected by API Management)
Implementación: algesta-ms-orders-nestjs/src/shared/services/qsystems.service.ts (if exists)

9. Integration Arquitectura Diagram

graph TD
    Client[Client via WhatsApp] -->|Messages| Jelou[Jelou Bot]
    Jelou -->|Webhook| Gateway[API Gateway]
    Gateway --> OrdersMS[Orders Microservice]
    Gateway --> ProviderMS[Provider Microservice]
    Gateway --> NotificationsMS[Notifications Microservice]

    OrdersMS -->|Store photos| AzureBlob[Azure Blob Storage]
    ProviderMS -->|Store documents| AzureBlob

    OrdersMS -->|Recognize serial| OCR[OCR Service]

    OrdersMS -->|Send contracts| DocuSign[DocuSign]
    DocuSign -->|Status webhooks| OrdersMS

    OrdersMS -->|Create tasks| Asana[Asana]

    OrdersMS -->|Lookup client| Qsystems[Qsystems via API Management]

    NotificationsMS -->|Send messages| Jelou
    NotificationsMS -->|Send emails| SendGrid[SendGrid]

10. API Endpoints Resumen

Endpoint	Método	Description	External System	Sprint
`/api/jelou/webhook`	POST	Receive WhatsApp messages	Jelou	S2
`/api/orders/:id/send-to-signature`	POST	Send Documentos to DocuSign	DocuSign	S5
`/api/orders/:id/signature-Estado`	GET	Get signature status	DocuSign	S6
`/api/assets/:id/recognize-serial`	POST	OCR serial recognition	OCR Service	S6
`/api/clients/lookup-by-nit`	GET	Lookup client in Qsystems	Qsystems	S2
`/api/orders/:id/create-asana-task`	POST	Create Asana task	Asana	S5

11. Integration Patterns

Webhook Pattern

Use: Jelou → Gateway (inbound messages), DocuSign → OrdersMS (signature status)
Benefits: Real-time, event-driven
Challenges: Webhook signature verification, retry logic

REST API Pattern

Use: Gateway → DocuSign, OCR, Qsystems, Asana (outbound requests)
Benefits: Synchronous, predictable
Challenges: Error handling, timeouts, rate limiting

Event-Driven Pattern

Use: Order state changes → Notifications → External systems
Benefits: Decoupled, scalable
Challenges: Eventual consistency, message ordering

Storage Pattern

Use: Upload → Azure Blob → Store URL → Retrieve
Benefits: Centralized, secure, scalable
Challenges: SAS token expiration, access control

12. Error Handling and Resilience

Retry Logic

OCR: Up to 3 attempts with user prompts
DocuSign: Retry on transient failures (network, timeouts)
Jelou: Retry message sending with exponential backoff

Fallback Mechanisms

Email if WhatsApp fails: Use email for critical notifications
Manual serial entry if OCR fails: User can manually enter serial after 3 OCR failures
Manual signature if DocuSign fails: Download PDF and collect physical signatures

Circuit Breakers

External API Calls: Circuit breaker pattern to prevent cascading failures
Timeout Configuration: Configurable timeouts per external system

Logging and Monitoring

Integration Logs: All external API calls logged with request/response
Alerting: Alerts for integration failures (email to ops team)
Dashboards: Integration health dashboard showing success/failure rates

Reference: /02-architecture/api-gateway-resilience/ (if exists)

13. Security Considerations

API Keys and Secrets

Storage: Azure Key Vault
Rotation: Quarterly rotation of API keys
Access: RBAC for Key Vault access

HTTPS for All Communications

Requisito: All external API calls over HTTPS
Certificate Validation: Strict certificate validation

SAS Tokens for Azure Blob Storage

Expiration: Time-limited tokens (1 hour for read, 15 minutes for write)
Permissions: Least privilege (read-only for display, write-only for upload)

OAuth 2.0 for DocuSign

Flow: Authorization code flow with PKCE
Token Storage: Encrypted in Base de datos
Refresh Tokens: Automatic token refresh before expiration

Webhook Signature Verification

Jelou: HMAC signature verification for inbound webhooks
DocuSign: DocuSign Connect signature verification

API Management for Qsystems

Authentication: OAuth 2.0 or API key
Rate Limiting: 100 requests per minute
IP Whitelisting: Only Algesta IPs can access

14. Pruebas Evidence

From unified_Pruebas_notes.md:

Sprint 2: WhatsApp integration tested (message reception, order creation, notifications)
Sprint 5: DocuSign integration tested (Documento sending, Status tracking)
Sprint 6: Signature Estado visualization tested
Sprint 7-8: OCR serial recognition tested with sample photos

15. Known Issues and Future Enhancements

🟧 Critical Issues

WhatsApp Business Integration Stability: API changes in S7-S8 caused impediments ✅ Resolved
Execution Date Confirmation Notification: Automation Pendiente via WhatsApp ✅ Resolved

🟨 Essential Improvements

Completo Asana Integration: Full bidirectional sync for internal workflow
Completo Qsystems Integration: Enterprise client data sync
OCR Accuracy Improvement: Collect more training data

🟩 Post-MVP Operaciones

Push Notifications: Replace some WhatsApp flows with push notifications
AI Model Retraining: Improve serial recognition accuracy
Real-time Webhooks for KPIs: Replace API refresh with event-driven KPI updates

🟦 Future Backlog

Completo SystemQ Integration: Full ERP integration for in-house orders
Mobile App to Replace WhatsApp: Native mobile app for clients
Advanced Analytics Integration: Connect to BI tools (Power BI, Tableau)

16. Referencias Cruzadas

Arquitectura Documentoation

Sprint Documentoation

Sprint 2, 5-8 Documentoation - see docs/Sprint_2.md, Sprint_5.md through Sprint_8.md in project Repositorio

Pruebas

Unified Pruebas Notes - see test/unified_Pruebas_notes.md in project Repositorio

Last Updated: 2025-12-03 | Next Review: End of Guarantee Phase