Notificaciones transaccionales: pedidos, reservas y alertas útiles

Una notificación transaccional avisa al usuario de algo que él mismo puso en marcha, como un pedido, una reserva, un pago o un cambio en su cuenta, justo cuando le sirve. Funciona cuando va dirigida a una persona concreta, llega a tiempo y dice qué ha pasado y qué hacer a continuación. Fracasa cuando llega tarde, llega dos veces o se convierte en publicidad.

En resumen:

• Es transaccional si responde a una acción o a un cambio de estado del propio usuario; si nadie la echaría de menos, no lo es.
• Vincula cada suscripción a tu id de usuario y envía a ese usuario, no a un segmento.
• Título con el hecho, texto con el siguiente paso y una URL que lleve al detalle.
• Ajusta caducidad y urgencia al tipo de aviso, y usa una clave de idempotencia por evento de negocio.
• Los recordatorios se programan en tu backend, comprobando el estado justo antes de enviar.

Qué cuenta como notificación transaccional

La línea entre un aviso útil y uno promocional no depende del canal ni del tono, sino de quién lo provoca:

Una prueba rápida: ¿se quejaría el usuario si este aviso no llegara? Si la respuesta es sí, es transaccional. La distinción también tiene consecuencias legales, porque los mensajes promocionales necesitan un consentimiento específico.

Vincula cada suscripción con tu usuario

Un aviso de pedido va a una persona, así que la suscripción debe saber a qué cuenta pertenece. Con el SDK de castly lo haces al suscribir o al iniciar sesión:

// Al suscribirse desde un clic
await Castly.subscribe({ userId: 'u_1842' });

// Al iniciar sesión, si este navegador ya estaba suscrito
await Castly.identify('u_1842', { idioma: 'es' });

Desde el servidor envías a ese usuario, y la notificación llega a todos los dispositivos donde se suscribió, por ejemplo su portátil del trabajo y su móvil:

await fetch('https://castly.sh/v1/notifications', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PUSH_SECRET_KEY}`, // sk_live_…
    'Content-Type': 'application/json',
    'Idempotency-Key': 'pedido-8841-enviado',
  },
  body: JSON.stringify({
    to: { type: 'users', userIds: ['u_1842'] },
    title: 'Tu pedido ha salido',
    body: 'Llega el jueves. Sigue el envío en tiempo real.',
    url: 'https://tienda.example/pedidos/8841',
    ttl: 86400,
  }),
});

Usa tu id interno, nunca el email, para no hacer viajar un dato personal innecesario. Y en ordenadores compartidos, da de baja el navegador al cerrar sesión: si no, el siguiente usuario podría ver avisos de la cuenta anterior.

Cómo redactar un aviso transaccional

• Título = el hecho: «Tu pedido ha salido», «Pago rechazado», «Tu mesa está lista».
• Texto = el detalle útil y el siguiente paso: «Llega el jueves. Sigue el envío en tiempo real».
• URL = la página exacta: el pedido 8841, no la portada ni el listado de pedidos.
• Contexto sin datos sensibles: «Tu cita es mañana a las 10:00» basta; el motivo de la cita sobra en una pantalla de bloqueo.

El payload cifrado no puede pasar de unos 4 KB, pero el límite real lo pone la pantalla: como regla práctica, que el título se entienda solo y el texto quepa en dos líneas. En algunos navegadores, como Safari, varias actualizaciones del mismo pedido no se reemplazan entre sí, así que envía solo los cambios de estado que importan.

Caducidad y urgencia según el tipo de aviso

Una push que llega tarde puede ser peor que ninguna: «Tu repartidor llega en 5 minutos» leído una hora después solo confunde. El TTL indica al servicio push cuánto tiempo guardar el mensaje si el dispositivo está desconectado, y la urgencia, si debe entregarlo ya o puede esperar a un momento de menos consumo de batería; ambos están definidos en el RFC 8030. Estos valores son reglas prácticas, no estándares:

Para un recordatorio, calcula el TTL al enviar: los segundos que faltan hasta la cita. Así, si el móvil está apagado, el aviso no aparecerá cuando la cita ya haya pasado. Profundizamos en TTL y urgencia en web push.

const ttl = Math.max(60, Math.floor((cita.inicio.getTime() - Date.now()) / 1000));

Sin duplicados y con recordatorios fiables

Una clave de idempotencia por evento de negocio

Los sistemas de pedidos reintentan: el webhook de tu pasarela de pago llega dos veces o un worker se reinicia a mitad de tarea. Si cada intento llama a la API de envío, el usuario recibe dos «Tu pedido ha salido». La solución es derivar la cabecera Idempotency-Key del evento, no del intento: pedido-8841-enviado es siempre la misma clave, y repetir la petición con ella durante 24 horas no crea otra notificación. Lo explicamos en idempotencia al enviar notificaciones.

Los recordatorios los programas tú

castly envía en el momento en que llamas a la API; no programa envíos. Para avisar dos horas antes de una cita, guarda las citas con su hora y ejecuta un proceso periódico, como un cron cada 5 minutos o una cola con retraso, que busque las que empiezan pronto y envíe el aviso. Antes de enviar, vuelve a leer el estado: si la cita se canceló o cambió de hora, no mandes el recordatorio antiguo. Usa también una clave como cita-552-recordatorio-2h para que dos ejecuciones solapadas del cron no dupliquen el aviso.

Mide la entrega y ten un plan B

Para los avisos críticos necesitas saber si llegaron. castly registra cada dispositivo como enviado, entregado y clicado, lo que consultas con GET /v1/notifications/:id, y puede avisar a tu servidor con webhooks como notification.delivered y notification.clicked. Con eso montas un respaldo:

1. Envías la push de «Pago rechazado».
2. Si pasados 30 minutos (una regla práctica) no consta ninguna entrega para ese usuario, envías un email desde tu propio sistema.
3. Si recibes subscriber.expired, anotas que ese dispositivo ya no recibe push y priorizas el email para ese usuario.

Los webhooks son de mejor esfuerzo, así que antes de decidir, confirma con la consulta a la API. Para elegir el canal de cada aviso desde el principio, mira push o email.

Preguntas frecuentes

¿Qué diferencia hay entre una notificación transaccional y una de marketing?

La transaccional responde a algo que el usuario hizo o configuró y le afecta solo a él; la de marketing busca provocar una acción nueva y suele ir a un grupo. Cambian también la base legal y la tolerancia: un aviso de envío se agradece, una oferta diaria acaba bloqueada.

¿Puedo enviar avisos transaccionales a quien no aceptó notificaciones?

No por push: sin el permiso del navegador no hay suscripción ni forma de entregar el mensaje. Para esos usuarios, usa email o avisos dentro de tu web.

¿Qué pasa si el usuario tiene varios dispositivos?

Si envías por id de usuario, el aviso llega a todos los dispositivos donde se suscribió. Para pedidos y reservas es lo deseable: lo verá esté donde esté.

¿Cuándo conviene pedir permiso para avisos transaccionales?

Cuando el valor es evidente: al confirmar un pedido o una reserva, con un texto como «¿Te avisamos cuando salga?». Pedirlo nada más entrar en la web, sin contexto, suele acabar en rechazo.

¿Cuántos avisos por pedido son demasiados?

Como regla práctica, envía los cambios de estado que el usuario consultaría por su cuenta: confirmado, enviado, en reparto y entregado, más cualquier incidencia. Los estados internos, como «en preparación», suelen sobrar.