Proveedores de Notificaciones

Los proveedores de notificaciones son integraciones configuradas en tiempo de ejecución que usa el módulo de notificaciones. El primer tipo de proveedor soportado es SMTP, que alimenta el envío de correos para clientes y administradores.

Esta página documenta el modelo operativo introducido por el trabajo de proveedores en tiempo de ejecución: la configuración SMTP y sus credenciales ya no se esperan desde configuración estática de la aplicación ni desde inyección de secretos en despliegue. Un entorno nuevo no envía correos hasta que un administrador autorizado crea un proveedor de notificaciones SMTP.

Modelo Actual

• Los registros de proveedor se crean y actualizan desde la ruta /notification-providers del Panel de Administración o desde la API GraphQL de administración.
• El código actualmente conoce un solo tipo de proveedor, SMTP.
• Solo puede existir un registro por tipo de proveedor. Un segundo proveedor SMTP devuelve DUPLICATE_PROVIDER.
• Los trabajos de correo resuelven el proveedor SMTP al momento de enviar.
• No hay ruta de arranque ni siembra para el primer proveedor en esta rama.

Las operaciones relevantes de Admin GraphQL son:

• notificationProviderCreate
• notificationProviderConfigUpdate
• notificationProviders
• notificationProvider

El enum GraphQL del proveedor es SMTP.

Permisos

El acceso a proveedores de notificaciones está controlado por los conjuntos de permisos de notificaciones:

• NotificationProviderViewer: puede leer y listar proveedores de notificaciones.
• NotificationProviderWriter: puede crear y actualizar proveedores de notificaciones.

La autorización de creación se verifica contra todos los proveedores de notificaciones. La autorización de actualización se verifica contra el id del proveedor específico que se está cambiando.

Crear El Proveedor SMTP

Usa el Panel de Administración cuando sea posible:

1. Abre /notification-providers.
2. Crea un proveedor SMTP.
3. Ingresa relay, puerto, modo TLS, URL del panel de administración, detalles del remitente, usuario y contraseña.
4. Guarda el proveedor antes de depender del correo de notificaciones en ese entorno.

La misma configuración puede hacerse desde Admin GraphQL:

mutation CreateSmtpNotificationProvider(
  $input: NotificationProviderCreateInput!
) {
  notificationProviderCreate(input: $input) {
    ... on NotificationProviderCreatePayloadSuccess {
      notificationProvider {
        notificationProviderId
        name
        provider
      }
    }
    ... on NotificationProviderCreatePayloadError {
      code
    }
  }
}

Variables de ejemplo:

{
  "input": {
    "smtp": {
      "name": "Primary SMTP",
      "relay": "smtp.example.com",
      "port": 587,
      "insecure": false,
      "adminPanelUrl": "https://admin.example.com",
      "fromEmail": "no-reply@example.com",
      "fromName": "Lana Bank",
      "username": "<smtp-username>",
      "password": "<smtp-password>"
    }
  }
}

No pongas secretos reales en documentación, capturas de pantalla, tickets de soporte ni historial de shell compartido.

Rotar Credenciales SMTP

Rota las credenciales SMTP actualizando la configuración del proveedor existente:

mutation UpdateSmtpNotificationProviderConfig(
  $input: NotificationProviderConfigUpdateInput!
) {
  notificationProviderConfigUpdate(input: $input) {
    ... on NotificationProviderConfigUpdatePayloadSuccess {
      notificationProvider {
        notificationProviderId
        name
        provider
      }
    }
    ... on NotificationProviderConfigUpdatePayloadError {
      code
    }
  }
}

El input de actualización usa los mismos campos de configuración SMTP que la creación, sin name. El tipo de proveedor debe coincidir con el proveedor existente. Actualizar un proveedor SMTP con un tipo de configuración diferente devuelve PROVIDER_TYPE_MISMATCH.

El proceso que crea o actualiza el proveedor invalida su caché local del sender SMTP. Otras réplicas de la aplicación que ya tenían un sender en caché refrescan desde almacenamiento después del TTL de caché, actualmente 30 segundos. Los proveedores ausentes no se cachean negativamente, así que una réplica sin sender en caché revisa almacenamiento en el siguiente envío de correo.

Manejo De Secretos

username y password de SMTP son inputs GraphQL Secret. Son de solo escritura en el borde de la API y nunca se devuelven en consultas de proveedores.

Dentro del módulo de notificaciones, la configuración del proveedor se almacena en payloads de eventos cifrados. La salida debug de SmtpConfig redacta username y password, y los spans de envío de correo no registran payloads completos de correo, destinatarios, asuntos, cuerpos ni secretos.

La rotación de llave de proveedores de notificaciones participa en el arranque de la aplicación. Cuando se configura una llave de cifrado obsoleta, las configuraciones de proveedores se descifran con la llave obsoleta, se vuelven a cifrar con la llave activa y se escriben de vuelta. La ruta de arranque registra una entrada de auditoría de sistema para la actualización del proveedor de notificaciones.

Comportamiento Cuando Falta El Proveedor

Si no hay proveedor SMTP configurado, el envío del correo de notificación se omite y el trabajo igualmente se completa. Esto preserva el comportamiento actual para entornos que todavía no han configurado SMTP.

La omisión es observable:

• span: notification.send_rendered_email
• email_type: tipo de correo estable y de baja cardinalidad, como under_margin_call, overdue_payment o deposit_account_created
• provider_configured=false
• delivery_outcome=skipped
• skip_reason=no_smtp_provider

Los fallos al resolver el proveedor, renderizar plantillas o enviar por SMTP todavía fallan el trabajo y mantienen el comportamiento de reintento existente. Los envíos fallidos registran delivery_outcome=failed y failure_stage como uno de:

• resolve_provider
• render_template
• smtp_send

Visibilidad En Arranque Y Ejecución

En el arranque, notification.init verifica si existe el proveedor SMTP después de la rotación de llave de notificaciones. El span de init registra:

• smtp_provider_configured
• smtp_provider_id, cuando está configurado

El servicio también emite un log de arranque con el mensaje SMTP notification provider status at startup.

La resolución del proveedor SMTP usa el span notification.smtp_sender. Registra:

• provider_configured
• provider_id, cuando está configurado
• cache_hit

Usa estos campos para responder preguntas operativas como:

• ¿Este entorno tenía SMTP configurado cuando arrancó?
• ¿Este correo se omitió porque faltaba el proveedor?
• ¿El sender vino de caché o de almacenamiento?
• ¿Qué tipo de correo se omitió o falló?

Registro De Decisión

Los proveedores de notificaciones en tiempo de ejecución reemplazan el modelo anterior de configuración SMTP en tiempo de compilación para el envío de correo de notificaciones.

Las ventajas prácticas son:

• Las credenciales SMTP pueden crearse y rotarse sin redesplegar.
• Los inputs secretos pasan por el scalar Secret de Admin GraphQL en lugar de archivos de configuración estática.
• Las lecturas y escrituras de proveedores usan las rutas existentes de autorización y auditoría.
• La configuración cifrada del proveedor puede participar en la rotación de llaves de la aplicación.

Los tradeoffs aceptados son:

• Un entorno recién creado no tiene proveedor SMTP hasta que un administrador autorizado crea uno.
• La ausencia de proveedor SMTP no es un fallo de arranque.
• La ausencia de proveedor SMTP omite el correo de notificación y completa el trabajo.
• No hay ruta automatizada de siembra del primer proveedor en esta rama.

Este modelo es intencionalmente "instancias configuradas en tiempo de ejecución de tipos de proveedor conocidos por el código". Agregar un nuevo tipo de proveedor todavía requiere cambios de código para su forma de configuración, validación, comportamiento de entrega, input GraphQL e interfaz de usuario.