Documentação de Layouts

Visão Geral

Os Layouts de Notificação representam a identidade visual e o conteúdo das mensagens enviadas pela plataforma aos clientes. ✨

Através desta funcionalidade, é possível criar e gerenciar templates personalizados para diferentes canais (E-mail ou WhatsApp), garantindo que cada ponto de contato transacional reflita a marca da loja.

O sistema utiliza um poderoso motor de renderização que permite a injeção de dados dinâmicos em tempo real, transformando templates estáticos em mensagens ricas e contextuais. 🚀

Funcionalidades Principais

• Personalização Dinâmica: Uso de variáveis sistêmicas (ex: dados do pedido, nome do cliente) para preencher o conteúdo do layout. 🧬
• Multi-Canal: Suporte à criação de conteúdos específicos para E-mail (HTML) e mensagens de texto para WhatsApp/SMS. 📱
• Gestão de Grupos: Organização dos layouts por grupos lógicos, facilitando a manutenção de grandes ecossistemas de comunicação. 🛠️
• Renderização em Tempo Real: Ferramenta de validação que permite visualizar como o layout será entregue ao destinatário final. 👁️

Notas e Considerações

Um layout só é efetivo quando está corretamente vinculado a um evento através do Mapeamento de Notificação.

Além disso, o sistema permite a criação de layouts padrão via Setup, acelerando o provisionamento inicial de novos canais de venda. ⚡

A visualização de dados requer a permissão NOTIFICATION_LAYOUT_READ, enquanto operações de criação, edição ou remoção exigem NOTIFICATION_LAYOUT_WRITE. 🔐

Listagem de layouts

Descrição

Endpoint administrativo responsável por listar, de forma paginada, os layouts de notificação configurados na loja, com suporte a filtros por campos estratégicos e ordenação flexível.

Permite ao lojista visualizar e gerenciar todos os layouts de notificação cadastrados em seu ambiente.

O acesso ao endpoint requer o escopo NOTIFICATION_LAYOUT_READ.

A listagem é sempre limitada ao contexto da loja autenticada, garantindo que layouts pertencentes a outras lojas nunca sejam retornados — mesmo quando seus identificadores forem conhecidos.

Parâmetros

Headers Obrigatórios

Campos de Condição Disponíveis

Campos de Ordenação Disponíveis

Exemplo de Requisição

1curl --request GET \
2  --url "{{MAIN_URL}}/notifications/layouts" \
3  --header "Content-Type: application/json" \
4  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "registers": [
5      {
6        "id": 2,
7        "salesChannelId": 1,
8        "notificationLayoutGroupId": 1,
9        "code": "user_password_changed",
10        "subject": "Sua senha foi alterada",
11        "message": "<div>...</div>\n<center>...</center>",
12        "active": true,
13        "type": "email",
14        "createdAt": "2025-09-09 19:13:14",
15        "updatedAt": "2025-11-17 09:44:16"
16      }
17    ],
18    "pagination": {
19      "limit": 10,
20      "offset": 0,
21      "pages": 1,
22      "registers": 1
23    }
24  }
25}

⚠️ Possíveis erros:

Este endpoint não possui erros de negócio específicos do módulo de layouts. Falhas de autenticação ou ausência do escopo requerido são tratadas de forma genérica pela camada de autorização da API.

Listagem de grupos de layout

Descrição

Endpoint administrativo responsável por retornar o catálogo completo dos grupos de classificação de layouts de notificação disponíveis na plataforma, sem paginação e sem parâmetros de filtro.

O acesso requer o escopo NOTIFICATION_LAYOUT_READ.

O catálogo é composto apenas pelos grupos marcados como visíveis na plataforma (viewable = 1).

São representados como um objeto em que cada chave é o identificador numérico do grupo (notificationLayoutGroupId) e cada valor é o rótulo do contexto de negócio — por exemplo, User, Order, Product.

Esse mapa é utilizado tipicamente no preenchimento de seletores no painel administrativo para categorizar layouts durante a criação ou edição.

A resposta não traz templates de mensagem, assunto, código ou canal — apenas o mapeamento identificador → rótulo do grupo, que deve ser referenciado ao enviar notificationLayoutGroupId nos endpoints de criação e atualização de layouts.

Parâmetros

Headers Obrigatórios

Exemplo de Requisição

1curl --request GET \
2  --url "{{MAIN_URL}}/notifications/layouts/groups" \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "1": "User",
5    "2": "Order",
6    "3": "Customer",
7    "4": "Product",
8    "5": "Store",
9    "6": "Payment",
10    "7": "Cart",
11    "8": "General"
12  }
13}

Detalhes de layout

Descrição

Endpoint administrativo responsável por retornar os dados completos de um layout personalizado de notificação configurado na loja.

Permite ao lojista visualizar e gerenciar detalhadamente um layout específico, possibilitando consultas, validações e futuras edições conforme necessário.

O acesso ao endpoint requer o escopo NOTIFICATION_LAYOUT_READ.

A busca é executada com escopo restrito à loja autenticada, garantindo que layouts pertencentes a outras lojas nunca sejam retornados — mesmo que o identificador informado exista em outro contexto.

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Exemplo de Requisição

1curl --request GET \
2  --url "{{MAIN_URL}}/notifications/layouts/1001" \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "id": 1001,
5    "salesChannelId": 10,
6    "notificationLayoutGroupId": 4,
7    "code": "notify_me",
8    "subject": "Seu produto está de volta!",
9    "message": "<center><table width=\"360\"><tr><td><h1>Olá, {{user.name}}!</h1><p>Seu produto voltou ao estoque.</p></td></tr></table></center>",
10    "active": true,
11    "type": "email",
12    "createdAt": "2026-05-21 12:29:32",
13    "updatedAt": "2026-05-21 12:29:43"
14  }
15}

⚠️ Possíveis erros:

Criação de layout

Descrição

Endpoint administrativo responsável por cadastrar um layout personalizado de notificação na loja, vinculando um modelo de mensagem a um canal de venda, a um grupo de classificação e a um canal de envio (email, sms ou whatsapp).

O acesso requer os escopos NOTIFICATION_LAYOUT_READ e NOTIFICATION_LAYOUT_WRITE.

O processo valida o canal de venda informado em salesChannelId e confirma que o notificationLayoutGroupId corresponde a um grupo existente e visível na plataforma antes de persistir o registro — caso contrário, a requisição é rejeitada com erro específico.

O campo code identifica o layout de forma única dentro do mesmo canal de venda:

A API rejeita a criação caso já exista um layout com o mesmo código naquele canal, impedindo duplicidades que comprometeriam a resolução automática de templates durante o disparo de notificações.

Para layouts de e-mail, o campo message normalmente contém HTML com placeholders no formato {{variável}} (ex.: {{user.name}}).

Para SMS e WhatsApp, o conteúdo pode ser texto simples ou o nome de um template registrado no provedor, conforme o canal.

O campo id não deve ser enviado na criação; a API gera o identificador e retorna o registro completo na resposta.

Parâmetros

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

1curl --request POST \
2  --url "{{MAIN_URL}}/notifications/layouts" \
3  --header "Content-Type: application/json" \
4  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
5  --data '{
6    "salesChannelId": 10,
7    "notificationLayoutGroupId": 4,
8    "code": "notify_me_sms",
9    "active": true,
10    "subject": "Seu produto está de volta!",
11    "type": "sms",
12    "message": "notify-me"
13  }'

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "id": 1002,
5    "salesChannelId": 10,
6    "notificationLayoutGroupId": 4,
7    "code": "notify_me_sms",
8    "subject": "Seu produto está de volta!",
9    "message": "notify-me",
10    "active": true,
11    "type": "sms",
12    "createdAt": "2026-05-21 11:50:44",
13    "updatedAt": "2026-05-21 11:50:44"
14  }
15}

⚠️ Possíveis erros:

Atualização de layout

Descrição

Endpoint administrativo responsável por atualizar um layout personalizado de notificação já cadastrado na loja.

O acesso requer os escopos NOTIFICATION_LAYOUT_READ e NOTIFICATION_LAYOUT_WRITE.

O processo verifica inicialmente se o layout existe e pertence à loja autenticada; em seguida valida o canal de venda e confirma que o notificationLayoutGroupId corresponde a um grupo existente e visível na plataforma antes de aplicar as alterações.

A unicidade do campo code é reavaliada na atualização: caso o novo código já esteja em uso por outro layout no mesmo canal de venda, a operação é rejeitada com erro específico.

O próprio layout sendo editado é excluído da verificação, permitindo salvar sem alteração de código.

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Parâmetros do Corpo

Exemplo de Requisição

1curl --request PUT \
2  --url "{{MAIN_URL}}/notifications/layouts/1002" \
3  --header "Content-Type: application/json" \
4  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
5  --data '{
6    "salesChannelId": 10,
7    "notificationLayoutGroupId": 4,
8    "code": "notify_me",
9    "active": true,
10    "subject": "Seu produto está de volta!",
11    "type": "email",
12    "message": "notify-me"
13  }'

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "id": 1002,
5    "salesChannelId": 10,
6    "notificationLayoutGroupId": 4,
7    "code": "notify_me",
8    "subject": "Seu produto está de volta!",
9    "message": "notify-me",
10    "active": true,
11    "type": "email",
12    "createdAt": "2026-05-21 11:50:44",
13    "updatedAt": "2026-05-21 11:58:44"
14  }
15}

⚠️ Possíveis erros:

Remoção de layout

Descrição

Endpoint administrativo responsável por remover permanentemente um layout personalizado de notificação da loja.

O acesso requer os escopos NOTIFICATION_LAYOUT_READ e NOTIFICATION_LAYOUT_WRITE.

Antes de executar a exclusão, o processo verifica se o layout existe e pertence à loja autenticada — caso contrário, um erro 404 é retornado e nenhuma alteração é realizada no banco de dados.

A operação é permanente e irreversível: o registro é excluído com escopo restrito à loja autenticada, garantindo isolamento entre lojas.

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Exemplo de Requisição

1curl --request DELETE \
2  --url "{{MAIN_URL}}/notifications/layouts/1002" \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": true
4}

⚠️ Possíveis erros:

Renderizar mensagem

Descrição

Endpoint administrativo responsável por pré-visualizar a renderização de um template de mensagem, aplicando variáveis, filtros e blocos de layout sem persistir dados nem disparar notificações.

O acesso requer o escopo NOTIFICATION_LAYOUT_READ.

O processo recebe o tipo de canal (email, sms ou whatsapp), o texto do template em message e um payload opcional com dados de exemplo, em seguida resolve blocos de layout reutilizáveis referenciados no template antes de aplicar o motor de renderização.

Para type email e sms, o motor substitui placeholders no formato {{variável}} pelos valores fornecidos no payload e avalia filtros como {{"now"|date("d/m/Y")}} sem depender de dados externos.

Para type whatsapp, o processo monta um payload estruturado com templateName e parameters, retornando um JSON serializado em vez de texto renderizado — comportamento adequado aos provedores de templates do WhatsApp Business.

As chaves do payload devem corresponder aos placeholders em message: uma variável simples {{name}} usa "name" no payload; uma variável aninhada {{user.name}} exige "user": { "name": "..." }.

A API não persiste layout, não envia notificação e não exige identificador na URL; em caso de sucesso, data é a string já processada pelo motor de templates.

Parâmetros

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

1curl --request POST \
2  --url "{{MAIN_URL}}/notifications/layouts/render" \
3  --header "Content-Type: application/json" \
4  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
5  --data '{
6    "type": "email",
7    "message": "Olá, {{user.name}}! produto {{product.name}} (SKU {{product.sku}}) voltou ao estoque.",
8    "payload": {
9      "user": {
10        "name": "Maria Exemplo"
11      },
12      "product": {
13        "name": "Camiseta básica algodão",
14        "sku": "SKU-DEMO-001"
15      }
16    }
17  }'

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": "Olá, Maria Exemplo! produto Camiseta básica algodão (SKU SKU-DEMO-001) voltou ao estoque."
4}