US-026 — Notificación proactiva de estatus

Detalle de la historia¶

Historia¶

Como cliente de FleteChat con un embarque en curso, quiero recibir por WhatsApp una notificación cada vez que cambia el estatus, para enterarme del avance sin tener que preguntar.

Persona de usuario¶

Aplica a dos destinatarios por cada embarque con cambio de estatus:

• El contacto que aprobó el embarque (titular o colaborador, según quién hizo el click de aprobación formal), porque es quien ejecuta y coordina la operación.
• El titular de la cuenta, aun cuando no haya aprobado personalmente ese embarque, porque tiene visibilidad total sobre la actividad de su cuenta (ver historia de titular y colaboradores).

Si el que aprobó es el propio titular, se envía una sola notificación (no se duplica).

Contexto de negocio¶

La notificación proactiva cierra el bucle entre el operador (que actualiza el estatus) y el cliente (que necesita enterarse sin preguntar). Es una diferencia visible entre FleteChat y los operadores tradicionales, que típicamente no avisan hasta que hay un problema.

Operativamente, cada actualización de estatus (ver historia de actualización manual) dispara una plantilla Meta aprobada a dos destinatarios: el contacto que aprobó y el titular de la cuenta (si son distintos). El colaborador necesita la notificación para coordinar; el titular necesita tener la foto completa de la cuenta aunque no haya sido él quien aprobó. El contenido es breve y reconocible: código corto del embarque + estatus nuevo + referencia para consultar más si el cliente lo desea. Si el envío a alguno de los dos destinatarios falla por problemas transitorios del canal, FleteChat reintenta; el cambio de estatus nunca se revierte por un fallo de notificación.

Diálogo de referencia¶

Agente (plantilla Meta, notificación proactiva): E42 — Su embarque pasó a En tránsito marítimo (17/04 09:40). Para ver el detalle o el historial completo, respóndame por aquí.

Criterios de aceptación¶

Disparo y envío¶

1. Cada actualización de estatus de un embarque (ver historia de actualización manual de estatus) dispara automáticamente una notificación por WhatsApp a dos destinatarios: (a) el contacto que aprobó el embarque (titular o colaborador, según la historia de aprobación por WhatsApp) y (b) el titular de la cuenta. Si ambos destinatarios son la misma persona, se envía una sola notificación (no se duplica).
2. Cada notificación se envía mediante una plantilla proactiva aprobada por Meta, porque la conversación puede estar fuera de la ventana de 24 h del canal. Los dos envíos son independientes: el éxito o fallo de uno no afecta al otro.
3. La notificación incluye: código corto ENNN, estatus nuevo y fecha/hora del cambio. El formato es reconocible y consistente en todas las notificaciones proactivas de FleteChat.

Robustez del envío¶

1. Ante fallos transitorios (rate limit, timeout, caída puntual del canal), FleteChat aplica reintentos automáticos con política de reintentos (ver PR-114).
2. Un fallo definitivo en cualquiera de los destinatarios no revierte ni afecta el cambio de estatus: el estatus queda actualizado; los fallos quedan registrados en audit log (por destinatario) y el operador puede reenviar manualmente desde el backoffice.
3. Las notificaciones se envían al teléfono activo del destinatario en el momento del envío (modelo "teléfono activo único + históricos" definido en US-003, PR-232). Cuando el destinatario cambia su teléfono activo entre la generación del evento y el envío:
4. Las notificaciones futuras se dirigen automáticamente al nuevo número activo.
5. Las notificaciones que ya estaban en cola y aún no enviadas se redirigen al nuevo número activo (no se envían al histórico).
6. Las notificaciones ya entregadas al histórico antes del cambio quedan en audit log como entregadas, sin reenvío automático al nuevo número.
7. Si el destinatario nunca tuvo un número activo verificado (caso atípico: titular con email verificado pero sin WhatsApp), su notificación no se envía por WhatsApp: se registra un warning para el operador y la información queda disponible al consultar entrando al portal o vía colaboradores con número activo verificado.

Notificaciones críticas¶

1. Las notificaciones clasificadas como críticas (llegada en importación, salida en exportación; ver PR-238) se entregan siempre, ignorando el opt-out granular del cliente (US-064) y el horario razonable de mensajes proactivos (US-057). El resto de notificaciones de cambio de estatus respeta ambos.

Notificación al titular por aprobación de cotización del colaborador¶

1. Cuando un colaborador aprueba formalmente una cotización (clic en el enlace de aprobación formal, ver US-012), el titular recibe una notificación de resumen por WhatsApp con el código CNNN aprobado, el código ENNN emitido, el monto total y el nombre del colaborador que aprobó. Esta notificación es separada de las notificaciones de cambio de estatus y respeta opt-out y horario razonable (no es crítica por defecto).

Cumplimiento del canal¶

1. FleteChat respeta la ventana de 24 h de WhatsApp: las notificaciones se envían siempre por plantilla aprobada, cumpliendo las políticas de Meta para mensajes proactivos.

Edge cases¶

• Varios cambios de estatus consecutivos cortos. Cada cambio dispara sus notificaciones; FleteChat no consolida ni agrupa por defecto (el cliente prefiere enterarse de cada paso).
• El aprobante es el propio titular. Se envía una sola notificación (no se duplica); el audit log refleja que el único destinatario absorbió los dos roles.
• El colaborador que aprobó ya no está activo en la cuenta (desvinculado por el titular entre la aprobación y el cambio de estatus). La notificación al colaborador no se envía; la notificación al titular sí se envía (cubre la continuidad operativa).
• El titular tiene muchos embarques activos y recibe múltiples notificaciones diarias. No se consolidan por defecto; si el volumen genera ruido, el admin puede configurar preferencias en versiones posteriores.
• Cliente desactivó notificaciones proactivas. El cliente final dispone del opt-out granular (ver historia de opt-out de comunicaciones proactivas, US-064). Si la notificación de cambio de estatus está clasificada como no crítica (ver PR-238 y US-057) y el cliente tiene opt-out activo sobre esa categoría, FleteChat no envía la notificación al destinatario que optó por no recibirla; el cambio de estatus queda registrado igual y sigue visible en la consulta conversacional. Si la notificación está clasificada como crítica (PR-238), se envía con independencia del opt-out y del horario (AC 7).
• El destinatario cambia su teléfono activo justo antes de un evento crítico. La notificación se redirige al nuevo activo conforme a AC 6; el histórico no recibe la notificación.
• El cliente ya está conversando con un operador vía handoff. Las notificaciones automáticas se envían igual; el operador puede coordinar con el cliente si prefieren silenciarlas temporalmente mientras dure el handoff.
• Reenvío manual por el operador. Desde el backoffice, el operador puede reenviar la notificación de un cambio específico a cualquiera de los dos destinatarios (o ambos); cada reenvío queda auditado.

Tamaño, prioridad y tipo¶

• Tamaño: M
• Prioridad: P0 — es el mecanismo por el que el cliente se entera del avance sin preguntar.
• Tipo: feature

Premisas¶

La historia está redactada bajo las siguientes premisas. Si alguna cambia, la historia debe revisarse y ajustarse en consecuencia. Todas deben ser confirmadas por el cliente antes de cerrar la historia.

• PR-114 — Política de reintentos por canal. Ante fallo transitorio, FleteChat aplica reintentos automáticos con hasta 3 reintentos con backoff exponencial (por ejemplo, 1, 5 y 30 minutos). Parámetros configurables por FleteChat.
• PR-115 — Destinatarios de la notificación. La notificación va a dos destinatarios: (a) el contacto que aprobó el embarque (titular o colaborador que hizo click en el enlace de aprobación formal) y (b) el titular de la cuenta, aun cuando no haya aprobado personalmente ese embarque. Si ambos son la misma persona, se envía una sola notificación. Esto alinea la operatividad del aprobante con la visibilidad total del titular sobre su cuenta.
• PR-116 — Independencia del estatus y las notificaciones. El éxito del cambio de estatus no depende del éxito de las notificaciones. Un fallo en cualquiera de los dos envíos nunca revierte ni bloquea un cambio de estatus; los envíos son independientes entre sí.
• PR-117 — Plantilla Meta aprobada. Las notificaciones se envían mediante plantillas proactivas registradas y aprobadas por Meta. Cualquier cambio de copy o campo de plantilla pasa por el ciclo de aprobación de Meta antes de usarse.
• PR-232 — Teléfono activo único + históricos por contacto. Definida en US-003. En esta historia gobierna AC 6: el envío se dirige al activo del momento; cola pendiente se redirige al activo nuevo.
• PR-237 — Notificaciones críticas ignoran opt-out y horario razonable. Las notificaciones clasificadas como críticas (PR-238) se entregan siempre, independientemente del opt-out granular del cliente (US-064) y del horario razonable de mensajes proactivos (US-057). El resto respeta ambos.
• PR-238 — Lista de eventos críticos. Los eventos clasificados como críticos en v1.0 son: (a) llegada de un embarque de importación al destino acordado y (b) salida de un embarque de exportación desde el origen acordado. La lista es parametrizable por FleteChat y puede ampliarse en versiones posteriores. Cambios al alcance pasan por aprobación del cliente para evitar dilución del concepto "crítico".

Refinamiento y Definition of Ready¶

Notas¶

Checklist¶

• ✅ Historia escrita en formato Como / Quiero / Para
• ✅ Persona de usuario identificada
• ✅ Contexto de negocio documentado
• ✅ Criterios de aceptación observables y pass/fail
• ✅ Edge cases relevantes listados
• ✅ Tamaño y prioridad asignados
• ⬜ Premisas PR-114 a PR-117, PR-232 (referenciada), PR-237 y PR-238 confirmadas por el cliente
• ⬜ Reglas de negocio aplicables aprobadas
• ⬜ Requerimientos funcionales aplicables aprobados
• ⬜ Historia aprobada formalmente por el cliente