Templates de notificação — o que identifica um template, ciclo de vida, variáveis Handlebars, criação na consola e pela API, e como o envio escolhe a versão.
Um template guarda o texto de uma notificação fora do código da aplicação. A aplicação envia o código do template e os valores das variáveis; o serviço escolhe a versão publicada e renderiza o conteúdo.
O que identifica um template
Um template é um canal e um locale. A combinação aplicação + código + canal + locale identifica-o:
| Campo | Exemplo | Notas |
|---|---|---|
applicationCode | REGISTOS | Aplicação do Access Management dona do template |
code | pedido-confirmacao | O que a aplicação envia em template.code |
channel | EMAIL | Um template por canal: para IN_APP cria outro com o mesmo código |
locale | pt-CV | Um template por locale |
subject | Pedido {{numeroPedido}} recebido | |
title | Pedido recebido | PUSH e IN_APP |
body | HTML (EMAIL, IN_APP) ou texto | Handlebars |
variables | [{ name, type, required, example }] | Declaração opcional das variáveis |
O locale tem de coincidir
O envio procura o template publicado com o locale exato do pedido. Não há fallback de pt-CV para pt nem para um locale por omissão: sem correspondência, o envio falha com 422 TEMPLATE_ERROR (No PUBLISHED template…). Publica o template em cada locale que usas, ou envia sempre o mesmo locale.
Ciclo de vida
| Estado | Significado |
|---|---|
DRAFT | Em edição. Não é usado nos envios. |
PUBLISHED | Usado nos envios. |
ARCHIVED | Retirado. Não é usado nos envios. |
Editar um template publicado cria uma nova versão em DRAFT (v2, v3, …). Ao publicá-la, a consola arquiva a versão anterior, para ficar só uma publicada por código, canal e locale.
Variáveis
As variáveis usam Handlebars: {{nome}}. Os valores vêm do campo variables do envio:
{
"template": { "code": "pedido-confirmacao", "locale": "pt-CV" },
"variables": { "nome": "Maria Silva", "numeroPedido": "PED-2026-0456" }
}- Uma variável sem valor fica vazia no texto. Declara-a com
required: truepara o envio falhar (TEMPLATE_ERROR) em vez de sair incompleto. - Em EMAIL e IN_APP os valores são escapados e o HTML final é sanitizado (sem
<script>, por exemplo).subjectetitlesão texto simples.
Criar na consola
A Notifications UI cria templates com um assistente de dois passos e um editor visual.
1. Metadados. Aplicação, código, canal, idioma, assunto (EMAIL) e título (PUSH / IN_APP):
2. Ponto de partida. Canvas em branco ou um dos exemplos do editor:
3. Editor. Criar e abrir editor grava o DRAFT e abre o editor visual. Adiciona linhas e blocos (texto, título, botão, imagem…) e escreve as variáveis no texto. Guardar grava a versão; Publicar torna-a ativa:
Depois de publicado, o template aparece na lista com o estado Publicado:
Criar pela API
POST /api/v1/templates
Authorization: Bearer <token com igrp.notification.admin>
Content-Type: application/json
{
"applicationCode": "REGISTOS",
"code": "pedido-confirmacao",
"channel": "EMAIL",
"locale": "pt-CV",
"subject": "Pedido {{numeroPedido}} recebido",
"body": "<p>Olá {{nome}},</p><p>Recebemos o seu pedido <b>{{numeroPedido}}</b>.</p>",
"variables": [
{ "name": "nome", "type": "STRING", "required": true, "example": "Maria Silva" },
{ "name": "numeroPedido", "type": "STRING", "required": true, "example": "PED-2026-0456" }
]
}A resposta traz o id do rascunho. Para o ativar:
POST /api/v1/templates/{id}/publishPara ver o resultado antes de publicar, POST /api/v1/templates/{id}/preview com { "variables": { … } } devolve subject, title e body renderizados.
Todos os endpoints de templates exigem igrp.notification.admin — ver API REST › Templates.
Encontrar um template pelo código
Não há endpoint "obter por código". Lista com filtros:
const { data } = await client.templates.list(
{ code: 'pedido-confirmacao', status: TemplateStatus.PUBLISHED, locale: 'pt-CV', channel: Channel.EMAIL },
{ page: 0, size: 5 },
'REGISTOS',
);PageResponseTemplateResponse page = new TemplatesApi(client).list(
"pedido-confirmacao", Channel.EMAIL, TemplateStatus.PUBLISHED, "pt-CV", new Pageable(0, 5));Templates da plataforma
O serviço publica no arranque os templates de convite usados pelo Access Management (aplicação APP_IGRP_CENTER), em pt e en: user-invitation, user-invitation-cancelled, user-invitation-responded e user-invitation-otp. Quando estes ficheiros mudam numa versão nova do serviço, é publicada uma versão nova do template, que passa a ser a usada; as versões editadas à mão continuam guardadas. Desliga com notification.templates.seed-defaults=false.
Última atualização: