Canal WhatsApp & Webhooks

WhatsApp es el canal de comunicación por excelencia para la atención al cliente, reservas hoteleras y coordinación operativa. Orbis integra la API oficial de WhatsApp Business (Cloud API / Zernio) bajo un esquema de seguridad fail-closed, gobernanza de plantillas y canal bidireccional de control para el dueño.

┌─────────────────────────────────────────────────────────────┐
│                 ARQUITECTURA DE WHATSAPP                    │
├─────────────────────────────────────────────────────────────┤
│ 1. INGESTA VERIFICADA          Firma criptográfica HMAC-256 │
│ 2. CANAL DEL CLIENTE           Atención 24/7 y cotizaciones │
│ 3. CANAL DEL DUEÑO             Aprobaciones y comandos      │
│ 4. WATCHDOG DE SALUD           Detección de billing y drops │
└─────────────────────────────────────────────────────────────┘

---

1. Ingesta Criptográfica de Webhooks

Toda petición entrante desde los servidores de Meta o Zernio se valida antes de despertar al motor de ejecución:

• Verificación de Firma: Cada webhook debe incluir su cabecera de autenticación (X-Hub-Signature-256 o X-Zernio-Signature). Si la firma no coincide con el secreto configurado en el vault, el servidor rechaza el paquete con código 503 Service Unavailable.
• Allowlist Fail-Closed: Para entornos de prueba o pilotos cerrados, Orbis restringe la recepción a números autorizados (WHATSAPP_ALLOWED_USERS), descartando cualquier tráfico no reconocido antes de consumir capacidad.
• Deduplicación de Envíos: La red móvil puede reintentar mensajes idénticos. Cada mensaje entrante se registra con su ID de mensaje único (wamid), previniendo respuestas duplicadas.

---

2. Plantillas Oficiales (Templates) & Apertura en Frío

Cuando la empresa necesita contactar a un cliente fuera de la ventana de 24 horas (por ejemplo, para enviar una confirmación de reserva 3 días antes de la llegada o una notificación de vuelo retrasado):

• Gestión de Plantillas: Orbis valida que la plantilla esté aprobada por Meta antes de intentar el envío.
• Pre-Gate Local: Si una plantilla fue pausada o rechazada en el Business Manager de Meta (PAUSED, REJECTED), el gate local frena la emisión, evitando penalizaciones de calidad y cobros innecesarios.
• Egress DLP en Parámetros: Las variables dinámicas de la plantilla (nombre, fecha, monto) son escaneadas por el motor de prevención de pérdida de datos antes de viajar a Meta.

---

3. El Canal del Dueño (Owner Channel)

El dueño o gerente de la empresa no necesita estar frente a una computadora para autorizar gastos o conocer el estado de su operación. Orbis vincula su número personal de WhatsApp como canal de comando seguro:

ORBIS ──► "🚨 Solicitud de Aprobación [APR-842]:
           El huésped Carlos Pérez solicita cancelación con reembolso del 100%
           (Monto: $120.000). Política estándar: no reembolsable.
           Respondé 'sí' para autorizar o 'no' para rechazar."

DUEÑO ──► "sí"

ORBIS ──► "✅ Aprobado. El reembolso se procesó y se notificó al huésped."

Comandos Interactivos del Dueño

Además de autorizar transacciones, el canal del dueño es interactivo y responde a comandos directos en lenguaje natural:

Comando	Acción de Orbis
estado	Reporte resumido del día: reservas atendidas, ocupación actual y UT consumidas.
incidentes	Lista de alertas operativas o de sistemas que requieran atención inmediata.
pendientes	Lista de solicitudes 4-Eyes aguardando respuesta del dueño.
pausar [rol]	Pausa temporal de las rutinas de un empleado específico.
ayuda	Despliega el menú de comandos autorizados para el número del dueño.

---

4. Vigilancia de Salud del Canal (Watchdog)

La caída inadvertida de una línea de WhatsApp Business puede costar miles de dólares en reservas perdidas. Orbis incluye un supervisor de canal (_Channel Watchdog_):

• Incidentes de Facturación (waba_billing): Si la tarjeta asociada a la cuenta de Meta expira o rechaza un pago, el sistema detecta el error y deriva un incidente crítico de inmediato al dueño.
• Suspensiones de Meta (waba_suspended): Notifica en tiempo real si la cuenta de WhatsApp Business experimentó un bloqueo temporal por políticas.
• Estado de Envío (wa_send_status): Monitorea eventos delivered y read para verificar que los mensajes alcancen efectivamente el teléfono de los clientes.