Diagramas de Secuencia y Casos de Uso Críticos

sequenceDiagram autonumber actor Admin as Administrador Empresa participant UI as Dashboard Innovia participant API as Backend Core Innovia participant DB as PostgreSQL Innovia participant Adapter as KapsoAdapter participant Kapso as Kapso Platform participant Meta as Meta Embedded Signup Admin->>UI: Solicita conectar número WhatsApp UI->>API: POST /api/tenants/:id/phone-numbers/connect API->>DB: Verifica provider_customer_id alt Si no existe Customer en Kapso API->>Adapter: createCustomer(tenant.name, tenant.id) Adapter->>Kapso: POST /v1/customers Kapso-->>Adapter: { id: "kps_cus_9981" } Adapter-->>API: providerCustomerId API->>DB: UPDATE tenants SET provider_customer_id = 'kps_cus_9981' end API->>Adapter: createSetupLink(providerCustomerId) Adapter->>Kapso: POST /v1/customers/kps_cus_9981/setup_links Kapso-->>Adapter: { url: "https://onboard.kapso.io/..." } Adapter-->>API: setupLinkUrl API-->>UI: 200 OK { setup_url } UI->>Admin: Abre modal con flujo Embedded Signup de Meta Admin->>Meta: Inicia sesión, vincula número y autoriza WABA Meta-->>Kapso: Registra línea y provee token Kapso->>API: Webhook POST /webhooks/providers/kapso (phone_number.connected) API->>Adapter: normalizeWebhook(payload) Adapter-->>API: PhoneConnected Event (e164, waba_id, provider_phone_id) API->>DB: INSERT INTO phone_numbers (tenant_id, e164, status='ACTIVE', provider_phone_id) API->>Adapter: syncTemplates(provider_waba_id) Adapter->>Kapso: GET /v1/templates Kapso-->>Adapter: Lista de plantillas aprobadas por Meta Adapter-->>API: Templates normalizados API->>DB: INSERT INTO templates (...) API-->>UI: Notificación en tiempo real: Línea activa y plantillas listas

sequenceDiagram autonumber actor Marketer as Usuario Innovia participant UI as Dashboard Innovia participant API as Backend Core Innovia participant Queue as Redis / BullMQ participant DB as PostgreSQL Innovia participant Adapter as KapsoAdapter participant Kapso as Kapso Platform Marketer->>UI: Carga CSV, valida columnas y teléfonos E.164 Marketer->>UI: Selecciona Template y mapea variables {{1}}, {{2}} Marketer->>UI: Define fecha/hora de envío UI->>API: POST /api/campaigns (name, phone_id, template_id, recipients[]) API->>DB: Guarda campaña (status='SCHEDULED', total_recipients=5000) API->>DB: Registra mensajes en estado PENDING API-->>UI: 201 Created { campaign_id: "cmp_456" } alt Envío Programado API->>Queue: Encola Job diferido con BullMQ Queue-->>API: Activa worker al cumplirse la hora end API->>DB: UPDATE campaigns SET status='IN_FLIGHT' API->>Adapter: createAndExecuteBroadcast({ name, providerPhoneId, template, recipients }) Adapter->>Kapso: POST /v1/broadcasts (Batch masivo) Kapso-->>Adapter: { broadcast_id: "kps_bc_7712", status: "processing" } Adapter-->>API: providerBroadcastId API->>DB: UPDATE campaigns SET provider_broadcast_id='kps_bc_7712' API-->>UI: Progreso en tiempo real de la campaña

sequenceDiagram autonumber participant Ext as Sistema Externo (CRM / ERP) participant Gateway as API Gateway Innovia participant API as Backend Core Innovia participant DB as PostgreSQL Innovia participant Adapter as KapsoAdapter participant Kapso as Kapso Platform Ext->>Gateway: POST /v1/messages (Bearer inn_live_...) Gateway->>Gateway: Valida firma de API Key y extrae tenant_id Gateway->>API: Valida saldo y cuota disponible del tenant alt Saldo insuficiente API-->>Ext: 402 Payment Required { error: "insufficient_quota" } end API->>DB: Inserta Message (status='PENDING', id='msg_uuid') API->>Adapter: sendTemplateMessage(phone.provider_phone_id, payload) Adapter->>Kapso: POST /v1/messages Kapso-->>Adapter: 200 OK { id: "kps_msg_10293", status: "accepted" } Adapter-->>API: { providerMessageId: "kps_msg_10293", status: "sent" } API->>DB: UPDATE messages SET provider_message_id='kps_msg_10293', status='SENT' API-->>Ext: 202 Accepted { id: "msg_uuid", status: "sent" }

sequenceDiagram autonumber participant Kapso as Kapso Webhook Engine participant Receiver as Webhook Receiver (/webhooks/providers/kapso) participant Normalizer as Event Normalizer participant DB as PostgreSQL Innovia participant Rollup as Metrics Rollup participant OutboundHook as Client Webhook Dispatcher participant Ext as Webhook del Cliente Kapso->>Receiver: POST (message.delivered) con firma criptográfica Receiver->>Receiver: Valida firma HMAC Receiver-->>Kapso: 200 OK Inmediato Receiver->>Normalizer: Procesa payload crudo Normalizer->>Normalizer: Normaliza a MESSAGE_DELIVERED Normalizer->>DB: Busca mensaje por provider_message_id DB-->>Normalizer: Mensaje encontrado (id, campaign_id) Normalizer->>DB: INSERT INTO message_events (...) Normalizer->>DB: UPDATE messages SET status='DELIVERED', delivered_at=NOW() Normalizer->>Rollup: Incrementa contador delivered de la campaña Rollup->>DB: UPDATE campaigns SET delivered_count = delivered_count + 1 opt Si el cliente configuró Webhook URL saliente Normalizer->>OutboundHook: Encola evento para el cliente OutboundHook->>Ext: POST https://cliente.com/webhook { event: "message.delivered" } end