Añadir una plantilla nueva
Cuando un producto quiere mandar un aviso que no existía, lo que hace falta no es código en el productor: es una plantilla registrada. Este suele ser el cuello de botella real de una feature de notificación — el handler que la dispara son veinte líneas; esto es lo que lleva el tiempo.
Qué es una plantilla aquí
Una fila en Template, única por la terna (tenantId, code, channel). El code es el
identificador que el productor manda ("password-changed", "appointment-reminder"), y esa terna
significa que el mismo código puede tener una versión de email y otra de push sin pisarse.
Los pasos
1 · Elige canal y código
El canal no es libre: hay una convención en el ecosistema. Email para cambios de estado de la
cuenta, push para lo operativo, ambos solo para seguridad crítica. El code en minúsculas con
guiones, describiendo el hecho, no el texto.
2 · Crea el contenido en el sitio que le toque
Y aquí las dos mitades divergen del todo:
| Canal | Qué necesita la fila | Dónde vive el cuerpo |
|---|---|---|
EMAIL |
templateId |
En Resend. Hay que montarla allí primero y traerse el id |
PUSH |
content |
En la propia fila: un JSON con title, body y data |
Es lo que valida assertChannelPayload, y falla al crear la plantilla, no al enviar:
PUSHsincontent→ 400, “PUSH templates require content”.EMAILsintemplateId→ 400, “EMAIL templates require templateId”.
El paso lento es montar la plantilla en Resend, no crear la fila.
3 · Registra la fila
Por la API de plantillas, o desde el panel de superadmin que ya la consume. Si ya existe una con esa
terna, responde 409 con el tenant, el código y el canal en el mensaje — está traducido a
propósito desde el P2002 de Prisma, que si no subiría como un 500 opaco.
Las variables
El productor manda variables y cada canal las aplica distinto: en email viajan a Resend, que
rellena su plantilla alojada; en push las interpola el worker sobre title y body.
Una que no viaja en variables es el data del push, que se mezcla por clave con el de la
plantilla ganando el de la petición — es el hueco para un dato de un solo uso, como un código de
verificación, que no puede vivir en una fila estática.
Comprobar que quedó bien
Sin esperar a que la reciba un cliente: mándate la plantilla a una dirección tuya desde el panel, como cuenta Probar una plantilla antes de que la reciba alguien.
Si la terna no existe, la petición falla con 404 de plantilla en la llamada del productor, no dentro del worker — la validación es al encolar justamente para eso.
Un fallo típico y confuso: mandar un code correcto pero con el tenantId equivocado también
da 404 de plantilla, porque las plantillas cuelgan del tenant de entrega. Ver
tenantId contra sourceTenantId.