Notificaciones

La cola notificacion acumula los correos que salen del sistema; un worker los envía en lotes.

Estados

encolado ──worker──▶ enviado ──proveedor rebota──▶ rebotado
   ▲                    │
   └──reintentar────────┼──▶ fallido (hasta 5 intentos)

Estado	Significado
encolado	Esperando al worker
enviado	El proveedor aceptó el mensaje
fallido	Error de envío; vuelve a la cola hasta 5 intentos
rebotado	El proveedor reportó rebote (mailbox llena, etc.)

Tipos: qr_emitido (se encola solo al confirmar reserva), recordatorio y verificacion_email.

Proveedor de correo

• CORREO_PROVEEDOR=consola (dev): imprime el correo en la consola con un id sintético — es el usado en tests.
• CORREO_PROVEEDOR=smtp + SMTP_* (prod).

Encolar manualmente

curl -X POST http://localhost:5000/notificaciones/ \
  -H 'content-type: application/json' -H "authorization: Bearer $TOKEN" \
  -d '{"participanteId":"<uuid>","reservaId":"<uuid>","tipo":"recordatorio","destinatario":"persona@empresa.mx"}'

Nace encolado con 0 intentos; si omites destinatario se usa el email del participante. 404 si el participante no existe.

Worker (envío por lotes)

curl -X POST http://localhost:5000/notificaciones/procesar \
  -H 'content-type: application/json' \
  -H "x-cron-secret: $CRON_SECRET" \
  -d '{"limite":50}'

{ "procesadas": 12, "enviadas": 11, "fallidas": 1 }

• Reclama encolado/fallidos (< 5 intentos) con salto de bloqueo (FOR UPDATE SKIP LOCKED): varios workers no se pisan.
• Renderiza la plantilla con el contexto de la reserva; una fila mala marca fallido sin tumbar el lote.
• Corre solo cada 2 minutos (ver Jobs).

Precaución

CRON_SECRET define el header x-cron-secret. Si la variable no está configurada, el endpoint queda abierto (con advertencia en consola): en producción llénalo.

Recordatorios

curl -X POST http://localhost:5000/notificaciones/recordatorios \
  -H 'content-type: application/json' \
  -H "x-cron-secret: $CRON_SECRET" \
  -d '{"horasAnticipacion":24,"limite":500}'

Encola recordatorio a reservas confirmadas cuyo evento empieza dentro de la ventana, sin recordatorio previo → { "encoladas": N }. Es idempotente por corrida: repetirlo no duplica.

Corregir y reintentar

# Cambiar destino mientras no se haya enviado (encolado/fallido)
PATCH /notificaciones/{id}  -d '{"destinatario":"otro@empresa.mx"}'
# → 409 si ya está enviada o rebotada

# Devolver fallido/rebotado a la cola (conserva el contador de intentos)
POST /notificaciones/{id}/reintentar
# → 409 si está enviada; sobre encolado es idempotente

GET /notificaciones/?estado=fallido&tipo=recordatorio lista la cola (filtros: participanteId, reservaId, estado, tipo, con cursor). Los fallido con 5 intentos son “carta muerta”: se recuperan con reintentar.

Webhook de rebotes

El proveedor avisa con el id que devolvió al enviar:

curl -X POST http://localhost:5000/notificaciones/webhook \
  -H 'content-type: application/json' \
  -H "x-webhook-secret: $NOTIFICACION_WEBHOOK_SECRET" \
  -d '{"proveedorMensajeId":"consola-abc-123"}'

• Marca la notificación rebotado (conserva enviado_at).
• Idempotente: repetir el mismo webhook responde igual, sin error.
• Id desconocido → 404.
• Header x-webhook-secret; sin NOTIFICACION_WEBHOOK_SECRET el endpoint queda abierto (advertencia en consola).

Siguiente paso

→ Auditoría