Skip to content

Documentação de Mapeamento

Visão Geral

O Mapeamento de Notificação é o cérebro do módulo de comunicações, responsável por definir a lógica de "O que enviar", "Como enviar" e "Através de quem enviar". 🧠

É nesta camada que se estabelece o vínculo entre um Evento Transacional (ex: Pedido Criado), um Layout de Loja (o template visual) e uma Credencial (o canal de saída).

Sem um mapeamento ativo para um determinado evento e canal de venda, a plataforma não realiza o enfileiramento do disparo. 🚀

Entidades Envolvidas

  • Identificador (Identifier): O gatilho sistêmico único para cada evento da plataforma. 🔔

  • Layout: O template de mensagem vinculado ao evento, que pode variar por canal de venda. ✨

  • Credencial: O provedor técnico que será utilizado para realizar o envio deste mapeamento específico. 🔒

Notas e Considerações

O sistema permite uma gestão granular, onde um mesmo evento pode possuir múltiplos mapeamentos (ex: um envio por E-mail e outro por WhatsApp), desde que utilizem credenciais de tipos distintos. 🛠️

A visualização de dados requer a permissão NOTIFICATION_MAP_READ, enquanto modificações exigem NOTIFICATION_MAP_WRITE. 🔐

Listagem de mapeamento de notificação

GET /notifications/maps

Listagem dos vínculos de notificação da loja (evento, credencial e layout por canal).

Descrição

Este endpoint atua como o auditório central da comunicação transacional da loja, permitindo visualizar a matriz completa de vínculos entre os gatilhos de sistema e suas respectivas configurações de entrega. 📧

O mapeamento de notificação é a ponte fundamental que conecta três pilares essenciais:

O evento da plataforma (ex: pedido faturado), a identidade visual (layout personalizado) e o canal de comunicação (credencial de e-mail ou WhatsApp).

Através desta consulta, é possível verificar quais comunicações estão ativas para cada canal de venda, garantindo que a estratégia de contato com o cliente esteja corretamente orquestrada. 🚀

A resposta detalha cada associação, incluindo os objetos completos de credencial e layout, o que facilita a validação técnica do setup sem a necessidade de consultas adicionais.

O uso de filtros de condição permite segmentar a busca por eventos específicos ou canais de venda determinados, otimizando a gestão de grandes volumes de notificações. 📶

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

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer {userToken}Token de autenticação

Campos de Condição Disponíveis

CampoTipoDescrição
salesChannelIdintegerFiltra por identificador do canal de venda
notificationIdentifierstringFiltra por identificador do evento (ex.: change-order-status-3, customer-registration)
notificationCredentialIdintegerFiltra por identificador da credencial de notificação
notificationLayoutStoreIdintegerFiltra por identificador do layout personalizado na loja
notificationLayoutStoreActivebooleanFiltra por layout ativo ou inativo
activebooleanFiltra por mapeamento ativo ou inativo

Exemplo de Requisição

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

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": [
4    {
5      "salesChannelId": 10,
6      "notificationIdentifier": "change-order-status-3",
7      "notificationCredentialId": 42,
8      "notificationLayoutStoreId": 6,
9      "notificationCredential": {
10        "id": 42,
11        "name": "Credencial de e-mail demo",
12        "type": "email",
13        "settings": {
14          "host": "smtp.sendgrid.net",
15          "protocol": "SSL",
16          "port": 2525,
17          "user": "apikey",
18          "pass": "SG.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
19          "originEmail": "nao-responda@lojademo.com.br",
20          "originName": "Loja Demo",
21          "receivingContacts": [
22            "contato.exemplo@lojademo.com.br"
23          ]
24        },
25        "createdAt": "2025-09-09 19:17:36",
26        "updatedAt": "2026-05-21 13:55:18"
27      },
28      "notificationLayoutStore": {
29        "id": 6,
30        "salesChannelId": 10,
31        "notificationLayoutGroupId": 2,
32        "code": "order_invoiced",
33        "subject": "Remessa Faturada",
34        "message": "<center><table width=\"360\">{{component_header}}<tr><td><strong>REMESSA FATURADA</strong><p>Prezado(a) <strong>{{order.customer.customerNameCorporateName}}</strong>, a remessa do pedido N° <strong>{{order.orderGroup.code}}</strong> foi faturada.</p></td></tr>{{component_footer}}</table></center>",
35        "active": true,
36        "type": "email",
37        "createdAt": "2025-09-09 19:13:14",
38        "updatedAt": "2025-09-09 19:13:14"
39      },
40      "active": true,
41      "createdAt": "2025-09-09 19:13:14"
42    }
43  ]
44}

Atualização de mapas de notificação

PUT /notifications/maps

Gerencia mapeamentos de notificação da loja (adicionar ou remover vínculos).

Descrição

Este endpoint é o motor de configuração em lote para a estratégia de comunicação da loja, permitindo adicionar ou remover vínculos entre gatilhos de sistema e seus respectivos canais de entrega de forma massiva. 🛠️

Através desta funcionalidade, o lojista ou integrador pode orquestrar como cada evento da plataforma deve ser notificado, associando identificadores de eventos a layouts personalizados e credenciais de envio específicas.

O processamento em lote suporta até 100 itens por requisição, garantindo agilidade em setups complexos ou migrações de canais de venda. 🚀

A operação é atômica por item: cada entrada no array items é processada individualmente, e o sistema retorna o status de sucesso ou erro para cada mapeamento solicitado.

Isso permite uma gestão granular e resiliente, onde falhas em um único vínculo não interrompem o processamento dos demais. ✨

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

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer {userToken}Token de autenticação

Parâmetros do Corpo

CampoTipoObrigatórioDescrição
itemsarraySimLista de mapeamentos a processar (máximo 100 itens)
items.*.notificationIdentifierstringSimIdentificador do evento de notificação (ex.: notify-me, customer-registration). Deve ser um valor válido do catálogo de notificações
items.*.notificationLayoutStoreIdintegerSimIdentificador do layout personalizado na loja
items.*.notificationCredentialIdintegerSimIdentificador da credencial de notificação
items.*.activebooleanSimIndica se o mapeamento deve permanecer ativo após a operação
items.*.actionstringSimAção a executar: add (vincular) ou remove (desvincular)

Exemplo de Requisição

1curl --request PUT \
2  --url "{{MAIN_URL}}/notifications/maps" \
3  --header "Content-Type: application/json" \
4  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
5  --data '{
6    "items": [
7      {
8        "notificationIdentifier": "notify-me",
9        "notificationLayoutStoreId": 180,
10        "notificationCredentialId": 42,
11        "active": true,
12        "action": "add"
13      },
14      {
15        "notificationIdentifier": "notify-me",
16        "notificationLayoutStoreId": 183,
17        "notificationCredentialId": 43,
18        "active": true,
19        "action": "remove"
20      }
21    ]
22  }'

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": [
4    {
5      "notificationIdentifier": "notify-me",
6      "notificationLayoutStoreId": 180,
7      "notificationCredentialId": 42,
8      "active": true,
9      "action": "add",
10      "error": null
11    },
12    {
13      "notificationIdentifier": "notify-me",
14      "notificationLayoutStoreId": 183,
15      "notificationCredentialId": 43,
16      "active": true,
17      "action": "remove",
18      "error": null
19    }
20  ]
21}

⚠️ Possíveis erros

Código HTTPCódigoMensagem
400UAPPI_TOOLS_INVALID_NOTIFICATION_CREDENTIALA credencial enviada não é válida.
404UAPPI_TOOLS_NOTIFICATION_LAYOUT_NOT_FOUNDO layout de notificação não foi encontrado.
404UAPPI_TOOLS_NOTIFICATION_CREDENTIAL_NOT_FOUNDA credencial de notificação não foi encontrada.
400UAPPI_TOOLS_NOTIFICATION_MAP_INVALID_TYPEO tipo da credencial e da notificação solicitada não coincidem.

Uappi é a melhor opção para o crescimento da sua loja!

Institucional

;