Documentação de Notificações

Visão Geral

O módulo de Notificações é a espinha dorsal da comunicação transacional da plataforma, permitindo que lojistas e integradores mantenham os clientes informados sobre cada etapa crucial da sua jornada. 🔔

Através de um ecossistema robusto e flexível, a plataforma permite a configuração de disparos automáticos baseados em eventos nativos (como criação de pedido, aprovação de pagamento ou recuperação de carrinho).

A solução foi desenhada para ser agnóstica em termos de canal, suportando atualmente integrações via E-mail, WhatsApp e SMS. 🚀

A arquitetura do módulo é dividida em quatro pilares fundamentais:

* Credenciais: Configuração técnica dos provedores de envio (SMTP, Gateways de Mensageria). 🔒

* Layouts: Criação da identidade visual e conteúdo das mensagens, com suporte a variáveis dinâmicas. ✨

* Mapeamento: A inteligência que vincula um evento específico a um layout e uma credencial de saída. 🛠️

* Fila (Queue): O motor assíncrono que garante a entrega resiliente das mensagens sem impactar a performance da loja. 📶

Entidades Envolvidas

• Evento (Identifier): Representa o gatilho sistêmico que dispara a notificação (ex: order-group-creation). 📦
• Variável: Atributos dinâmicos do sistema que podem ser injetados nos templates para personalização (ex: customerName). 🧬
• Canal de Venda: Escopo de validade das configurações, permitindo estratégias de comunicação distintas por canal. 🏢

Notas e Considerações

O módulo opera estritamente em contexto administrativo, exigindo autenticação segura via UserAuth. 🔒

Para garantir a melhor experiência, a plataforma oferece uma ferramenta de Setup Inicial, que provisiona automaticamente os layouts e mapeamentos básicos para novos canais de venda, acelerando o tempo de implementação. ⚡

Listagem de notificações da plataforma

Descrição

Este endpoint é essencial para a orquestração da comunicação transacional da loja, permitindo que você visualize todos os identificadores de eventos nativos que a plataforma suporta. 🔔

A finalidade desta listagem é fornecer as chaves técnicas necessárias para o mapeamento e setup de notificações, garantindo que as mensagens certas cheguem aos clientes nos momentos cruciais da sua jornada de compra.

Com esses identificadores, é possível configurar desde avisos de alteração de status de pedido até fluxos de recuperação de carrinho e interações de segurança. 🚀

Cada identificador retornado representa um "gatilho" de sistema que pode ser vinculado a:

* Layouts personalizados: Definição do conteúdo visual e textual da mensagem para cada evento.

* Mapeamento de canais: Escolha de qual credencial (E-mail, WhatsApp, SMS) será utilizada para disparar cada tipo de notificação.

* Setup de disparos: Configuração e ativação de notificações específicas por canal de venda.

A resposta retorna um array de strings com os nomes técnicos dos eventos (ex: order-group-creation, payment-approved, cart-recovery), que devem ser utilizados como referência única em outras operações da API de Notificações.

O acesso a este recurso é restrito ao ambiente administrativo e exige obrigatoriamente autenticação (UserAuth). 🔒

Parâmetros

Headers Obrigatórios

Exemplo de Requisição

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

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": [
4    "order-group-creation",
5    "payment-approved",
6    "change-order-status-3",
7    "change-order-status-4",
8    "change-order-status-5",
9    "change-order-status-6",
10    "change-order-status-7",
11    "notify-me",
12    "store-review",
13    "product-review",
14    "customer-password-recovery",
15    "customer-password-changed",
16    "customer-registration",
17    "customer-mfa",
18    "minimum-stock",
19    "product-comment",
20    "order-invoiced",
21    "order-tracked",
22    "report-ready",
23    "user-password-recovery",
24    "user-password-changed",
25    "user-first-access-invite",
26    "contact-center",
27    "service-purchased",
28    "cart-recovery",
29    "cart-inside-sales"
30  ]
31}

Variáveis de notificação

Descrição

Este endpoint fornece o dicionário de dados dinâmicos para a construção de mensagens, permitindo que layouts de notificação sejam personalizados com informações em tempo real da plataforma. 🔔

A finalidade deste recurso é expor quais variáveis de template podem ser utilizadas para um evento específico (ex: abandono de carrinho) e um canal de envio determinado (ex: e-mail ou WhatsApp).

Ao consultar estas variáveis, o lojista ou desenvolvedor obtém os caminhos técnicos (path) exatos que devem ser inseridos nos layouts para renderizar dados como nome do cliente, detalhes do pedido ou links de recuperação. 🚀

A resposta retorna um mapeamento detalhado que inclui:

* Descrição: O propósito funcional da variável no contexto do negócio.

* Path: O identificador técnico para uso no motor de renderização.

* Type: O tipo de dado ou a classe DTO/DMC que estrutura a informação.

* Nullable: Indicativo de segurança sobre a presença obrigatória do dado. ✨

O acesso a este recurso é restrito ao ambiente administrativo e exige obrigatoriamente autenticação (UserAuth). 🔒

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Exemplo de Requisição

1curl --request GET \
2  --url "{{MAIN_URL}}/notifications/minimum-stock/variables/email" \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": [
4    {
5      "description": "Domínio do canal de venda atual",
6      "path": "salesChannelDomain",
7      "type": "string",
8      "nullable": false
9    },
10    {
11      "description": "Dados do produto",
12      "path": "product",
13      "type": "Uappi\\Clients\\Product\\Product\\CompleteProductDMC",
14      "nullable": false
15    }
16  ]
17}

Setup das notificações no canal de venda

Descrição

Este endpoint é o responsável pelo provisionamento de infraestrutura das notificações, permitindo inicializar ou restaurar rapidamente o ecossistema de comunicação transacional de um canal de venda. 🔔

Ao executar este setup, o sistema realiza uma varredura automática para identificar a ausência de recursos essenciais.

O processo abrange:

* Criação de Layouts Padrão: Caso o canal ainda não possua os templates nativos (ex: Boas-vindas, Recuperação de Senha), o sistema os cria utilizando os modelos globais da plataforma. ✨

* Vínculos de Mapeamento: Garante que os identificadores de eventos estejam corretamente associados aos layouts provisionados, preparando o terreno para o enfileiramento de disparos. 🛠️

A finalidade deste recurso é reduzir o tempo de configuração manual em novos canais de venda ou garantir que canais existentes possuam todos os disparos transacionais atualizados.

A resposta detalha em data se houve alterações reais (true) ou se o canal já estava em conformidade (false). 🚀

O acesso a este recurso é restrito ao ambiente administrativo e exige obrigatoriamente autenticação (UserAuth). 🔒

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Exemplo de Requisição

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

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "layout": false,
5    "mapping": false
6  }
7}