Skip to content

Documentação de Credenciais

Visão Geral

As Credenciais de Notificação são os conectores técnicos que permitem à plataforma realizar o envio efetivo das mensagens. 🔒

Cada credencial encapsula as configurações de um provedor externo (como servidores SMTP para e-mail ou gateways de API para WhatsApp/SMS).

A plataforma permite o cadastro de múltiplas credenciais, possibilitando que diferentes canais de venda ou tipos de mensagem utilizem provedores distintos conforme a necessidade estratégica do negócio. 🚀

Entidades Envolvidas

  • Tipo (Type): Define o protocolo de comunicação da credencial (ex: email, whatsapp). 📱

  • Configurações (Settings): Conjunto dinâmico de chaves e valores (Host, Porta, API Key, Token) exigidos pelo provedor selecionado. ⚙️

  • Origem (Origin): Define os dados de quem envia (E-mail de origem ou Número de remetente). 📧

Notas e Considerações

Para garantir que o setup técnico está correto antes da entrada em produção, o módulo oferece uma funcionalidade de Teste de Credencial, que realiza um disparo real de validação. 🛠️

A visualização de dados requer a permissão NOTIFICATION_CREDENTIAL_READ, enquanto operações de modificação exigem NOTIFICATION_CREDENTIAL_WRITE. 🔐

Listagem de credenciais

GET /notifications/credentials

Listagem paginada das credenciais de notificação configuradas na loja.

Descrição

Endpoint administrativo responsável por listar as credenciais de notificação cadastradas na loja, com suporte a filtros e paginação.

O acesso requer o escopo NOTIFICATION_CREDENTIAL_READ.

Cada credencial retornada inclui seu identificador, nome, canal (type), configurações de conexão (settings) e os campos de auditoria createdAt e updatedAt.

A listagem é sempre restrita ao contexto da loja autenticada — credenciais de outras lojas nunca aparecem no resultado.

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
idintegerFiltra por identificador da credencial
namestringFiltra por nome
typestringFiltra por canal (email, sms, whatsapp)

Campos de Ordenação Disponíveis

CampoDescrição
idOrdena por identificador
nameOrdena por nome
createdAtOrdena por data de criação

Exemplo de Requisição

1curl --request GET \
2  --url "{{MAIN_URL}}/notifications/credentials" \
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": 1,
7        "name": "Credencial de e-mail demo",
8        "type": "email",
9        "settings": {
10          "host": "smtp.sendgrid.net",
11          "protocol": "SSL",
12          "port": 2525,
13          "user": "apikey",
14          "pass": "SG.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
15          "originEmail": "nao-responda@lojademo.com.br",
16          "originName": "Loja Demo",
17          "receivingContacts": [
18            "contato.exemplo@lojademo.com.br"
19          ]
20        },
21        "createdAt": "2025-09-09 19:17:36",
22        "updatedAt": "2026-05-21 13:55:18"
23      }
24    ],
25    "pagination": {
26      "limit": 10,
27      "offset": 0,
28      "pages": 1,
29      "registers": 1
30    }
31  }
32}

Detalhe de credencial

GET /notifications/credentials/{notificationCredentialId}

Detalhes de uma credencial de notificação da loja.

Descrição

Endpoint administrativo responsável por retornar os dados completos de uma credencial de notificação da loja, identificada por notificationCredentialId na URL.

O acesso requer o escopo NOTIFICATION_CREDENTIAL_READ.

A resposta inclui o nome da credencial, o canal (type), o objeto settings completo com todas as configurações de conexão — incluindo dados sensíveis como senhas e tokens de API, conforme gravados na loja — além dos campos de auditoria createdAt e updatedAt.

O endpoint realiza a busca com escopo restrito à loja autenticada: credenciais de outras lojas nunca são retornadas, mesmo que o notificationCredentialId exista em outro contexto.

Se o identificador não pertencer à loja autenticada ou não existir, o serviço retorna um erro 404.

O uso típico deste endpoint é o carregamento do formulário de edição no painel administrativo.

Parâmetros

Headers Obrigatórios

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

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
notificationCredentialIdintegerSimIdentificador da credencial de notificação na loja

Exemplo de Requisição

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

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "id": 42,
5    "name": "Credencial de e-mail demo",
6    "type": "email",
7    "settings": {
8      "host": "smtp.sendgrid.net",
9      "protocol": "SSL",
10      "port": "2525",
11      "user": "apikey",
12      "pass": "SG.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
13      "originEmail": "nao-responda@lojademo.com.br",
14      "originName": "Loja Demo",
15      "receivingContacts": [
16        "contato.exemplo@lojademo.com.br"
17      ]
18    },
19    "createdAt": "2025-09-09 19:17:36",
20    "updatedAt": "2025-09-09 19:17:36"
21  }
22}

⚠️ Possíveis erros:

Código InternoCódigo HttpDescrição
UAPPI_TOOLS_NOTIFICATION_CREDENTIAL_NOT_FOUND404A credencial de notificação informada não foi encontrada para a loja autenticada.

Cadastro de credencial

POST /notifications/credentials

Cadastra uma credencial de notificação na loja.

Descrição

Endpoint administrativo responsável por cadastrar uma nova credencial de notificação na loja.

Uma credencial representa a configuração de conexão com um provedor externo de envio — servidor SMTP para e-mail, provedor Twilio ou Zenvia para SMS, ou a API do WhatsApp Business — e é o elo entre a loja e o canal de disparo de notificações.

O acesso a este endpoint requer o escopo NOTIFICATION_CREDENTIAL_WRITE.

O campo type define o canal da credencial (email, sms ou whatsapp) e determina quais campos do objeto settings são obrigatórios; credenciais com settings incompletos ou incompatíveis com o type informado são rejeitadas com erro de validação.

Após a persistência bem-sucedida do registro, o sistema executa automaticamente um processo interno de associação: mapeamentos de notificação da loja que ainda não possuem uma credencial do mesmo canal são vinculados à credencial recém-criada.

Esse comportamento garante que notificações já configuradas passem a operar imediatamente com a nova credencial, sem intervenção manual.

O identificador da credencial não deve ser enviado na criação; em caso de sucesso, a API retorna data: true.

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
namestringSimNome da credencial (máx. 255 caracteres)
typestringSimCanal da credencial: email, sms ou whatsapp
settingsobjectSimConfigurações de conexão; os campos obrigatórios dentro de settings dependem de type (tabelas abaixo)

settings quando type é email

CampoTipoObrigatórioDescrição
settings.*.hoststringSimHost SMTP (máx. 255 caracteres)
settings.*.portstringSimPorta SMTP (máx. 6 caracteres)
settings.*.protocolstringSimProtocolo de criptografia: SSL ou TLS
settings.*.userstringSimUsuário de autenticação SMTP (máx. 255 caracteres)
settings.*.passstringSimSenha ou chave de API SMTP (máx. 255 caracteres)
settings.*.originEmailstringSimE-mail remetente (formato válido, máx. 255 caracteres)
settings.*.originNamestringSimNome exibido do remetente (máx. 255 caracteres)
settings.*.receivingContactsstring[]SimLista de e-mails para contato/recebimento; cada item deve ser um e-mail válido (máx. 255 caracteres)

settings quando type é sms

CampoTipoObrigatórioDescrição
settings.*.driverstringSimProvedor: twilio ou zenvia
settings.*.authTokenstringSimToken de autenticação do provedor (máx. 255 caracteres)
settings.*.fromNumberstringSimNúmero de origem do envio (máx. 255 caracteres)
settings.*.backupToNumberstringSimNúmero de contingência (máx. 255 caracteres)
settings.*.accountIdstringCondicionalObrigatório quando driver é twilio (máx. 255 caracteres)
settings.*.messageServerIdstringCondicionalObrigatório quando driver é twilio (máx. 255 caracteres)

settings quando type é whatsapp

CampoTipoObrigatórioDescrição
settings.*.tokenstringSimToken de acesso à API (máx. 255 caracteres)
settings.*.whatsappBusinessIdstringSimIdentificador da conta WhatsApp Business (máx. 255 caracteres)
settings.*.fromNumberstringSimNúmero de origem (máx. 255 caracteres)
settings.*.backupToNumberstringSimNúmero de contingência (máx. 255 caracteres)
settings.*.languageCodestringSimCódigo de idioma dos templates (máx. 255 caracteres)

Exemplo de Requisição

1curl --request POST \
2  --url "{{MAIN_URL}}/notifications/credentials" \
3  --header "Content-Type: application/json" \
4  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
5  --data '{
6    "name": "Credencial de e-mail demo",
7    "type": "email",
8    "settings": {
9      "host": "smtp.sendgrid.net",
10      "protocol": "TLS",
11      "port": "587",
12      "user": "apikey",
13      "pass": "SG.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
14      "originEmail": "nao-responda@lojademo.com.br",
15      "originName": "Loja Demo",
16      "receivingContacts": [
17        "contato.exemplo@lojademo.com.br"
18      ]
19    }
20  }'

✅ Resposta de Sucesso

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

⚠️ Possíveis erros:

Código InternoCódigo HttpDescrição
UAPPI_TOOLS_INVALID_NOTIFICATION_CREDENTIAL400As configurações enviadas no objeto settings são inválidas ou incompletas para o type informado.

Atualização de credenciais

PUT /notifications/credentials/{notificationCredentialId}

Atualiza uma credencial de notificação da loja pelo identificador na URL.

Descrição

Endpoint administrativo responsável por atualizar o nome e as configurações de conexão de uma credencial de notificação já cadastrada na loja, identificada por notificationCredentialId na URL.

O acesso requer o escopo NOTIFICATION_CREDENTIAL_WRITE.

O canal da credencial (type) é imutável após o cadastro: o serviço recupera o type armazenado no banco de dados e utiliza esse valor para determinar quais campos do objeto settings são obrigatórios.

Por isso, o campo type não deve ser enviado no corpo da requisição.

A tentativa de atualizar uma credencial cujo identificador não existe ou não pertence à loja autenticada resulta em erro 404 (o sistema não encontra o type correspondente e interrompe a operação).

O objeto settings deve ser enviado completo, com todos os campos exigidos para o canal da credencial — as configurações anteriores são substituídas integralmente.

Configurações incompletas ou com valores inválidos para o canal registrado são rejeitadas.

Parâmetros

Headers Obrigatórios

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

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
notificationCredentialIdintegerSimIdentificador da credencial de notificação a atualizar

Parâmetros do Corpo

CampoTipoObrigatórioDescrição
namestringSimNome da credencial (máx. 255 caracteres)
settingsobjectSimConfigurações de conexão; os campos obrigatórios dentro de settings dependem do type já salvo na credencial (tabelas abaixo)
O campo type é proibido no corpo da atualização.

settings quando a credencial é email

CampoTipoObrigatórioDescrição
hoststringSimHost SMTP (máx. 255 caracteres)
portstringSimPorta SMTP (máx. 6 caracteres)
protocolstringSimProtocolo de criptografia: SSL ou TLS
userstringSimUsuário de autenticação SMTP (máx. 255 caracteres)
passstringSimSenha ou chave de API SMTP (máx. 255 caracteres)
originEmailstringSimE-mail remetente (formato válido, máx. 255 caracteres)
originNamestringSimNome exibido do remetente (máx. 255 caracteres)
receivingContactsstring[]SimLista de e-mails para contato/recebimento; cada item deve ser um e-mail válido (máx. 255 caracteres)

settings quando a credencial é sms

CampoTipoObrigatórioDescrição
driverstringSimProvedor: twilio ou zenvia
authTokenstringSimToken de autenticação do provedor (máx. 255 caracteres)
fromNumberstringSimNúmero de origem do envio (máx. 255 caracteres)
backupToNumberstringSimNúmero de contingência (máx. 255 caracteres)
accountIdstringCondicionalObrigatório quando driver é twilio (máx. 255 caracteres)
messageServerIdstringCondicionalObrigatório quando driver é twilio (máx. 255 caracteres)

settings quando a credencial é whatsapp

CampoTipoObrigatórioDescrição
tokenstringSimToken de acesso à API (máx. 255 caracteres)
whatsappBusinessIdstringSimIdentificador da conta WhatsApp Business (máx. 255 caracteres)
fromNumberstringSimNúmero de origem (máx. 255 caracteres)
backupToNumberstringSimNúmero de contingência (máx. 255 caracteres)
languageCodestringSimCódigo de idioma dos templates (máx. 255 caracteres)

Exemplo de Requisição

Exemplo para credencial email (notificationCredentialId 42):

1curl --request PUT \
2  --url "{{MAIN_URL}}/notifications/credentials/42" \
3  --header "Content-Type: application/json" \
4  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
5  --data '{
6    "name": "Credencial de e-mail demo",
7    "settings": {
8      "host": "smtp.sendgrid.net",
9      "protocol": "SSL",
10      "port": "2525",
11      "user": "apikey",
12      "pass": "SG.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
13      "originEmail": "nao-responda@lojademo.com.br",
14      "originName": "Loja Demo",
15      "receivingContacts": [
16        "contato.exemplo@lojademo.com.br"
17      ]
18    }
19  }'

✅ Resposta de Sucesso

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

⚠️ Possíveis erros:

Código InternoCódigo HttpDescrição
UAPPI_TOOLS_NOTIFICATION_CREDENTIAL_NOT_FOUND404A credencial de notificação informada não foi encontrada para a loja autenticada.
UAPPI_TOOLS_INVALID_NOTIFICATION_CREDENTIAL400As configurações enviadas no objeto settings são inválidas ou incompletas para o canal da credencial.

Remoção de uma credencial

DELETE /notifications/credentials/{notificationCredentialId}

Remove uma credencial de notificação da loja.

Descrição

Endpoint administrativo responsável por remover permanentemente uma credencial de notificação da loja, identificada por notificationCredentialId na URL.

O acesso requer o escopo NOTIFICATION_CREDENTIAL_WRITE.

A operação executa a exclusão com escopo restrito à loja autenticada: somente credenciais pertencentes à loja do token de autenticação são elegíveis para remoção, garantindo isolamento entre lojas.

A exclusão é permanente e irreversível; mapeamentos de notificação que referenciavam a credencial removida passarão a operar sem credencial associada até que uma nova seja criada ou vinculada manualmente.

Em caso de sucesso, a API retorna data: true. A operação não lança erro quando a credencial não existe — a remoção é silenciosa caso o registro já tenha sido excluído anteriormente.

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {userToken}Token de autenticação

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
notificationCredentialIdintegerSimIdentificador da credencial de notificação a remover

Exemplo de Requisição

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

✅ Resposta de Sucesso

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

Testar envio de credencial

POST /notifications/credentials/{notificationCredentialId}/test

Envia uma notificação de teste pela credencial indicada na URL.

Descrição

Endpoint administrativo responsável por disparar um envio de teste real usando uma credencial de notificação já cadastrada, identificada por notificationCredentialId na URL.

O acesso requer o escopo NOTIFICATION_CREDENTIAL_WRITE.

O disparo é efetuado pelo canal configurado na credencial (e-mail, SMS ou WhatsApp), utilizando as credenciais de conexão reais armazenadas.

O serviço valida a existência da credencial na loja autenticada antes de prosseguir; caso o identificador não seja encontrado, o envio é abortado.

O campo salesChannelId é obrigatório pois define o domínio de contexto utilizado na renderização de variáveis do layout.

Ao menos um destino deve ser informado — destinationEmail ou destinationPhoneNumber — conforme o canal da credencial.

O conteúdo do envio pode ser fornecido de duas formas mutuamente exclusivas:

por meio de um layout de notificação da loja (notificationLayoutStoreId), onde o template é carregado e seus placeholders são preenchidos com o objeto payload fornecido; ou por meio de uma mensagem livre (message), enviada diretamente sem aplicação de template.

Quando ambos são enviados, o layout tem precedência e o campo message do corpo é ignorado.

Em caso de sucesso no disparo, a API retorna data: true; falhas no provedor externo de envio resultam em erro 502.

Parâmetros

Headers Obrigatórios

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

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
notificationCredentialIdintegerSimIdentificador da credencial de notificação usada no teste

Parâmetros do Corpo

CampoTipoObrigatórioDescrição
salesChannelIdintegerSimIdentificador do canal de venda
notificationLayoutStoreIdintegerCondicionalObrigatório quando message não é enviado; layout da loja cujo template será enviado
destinationEmailstringCondicionalObrigatório quando destinationPhoneNumber não é enviado; e-mail de destino (máx. 255 caracteres)
destinationPhoneNumberstringCondicionalObrigatório quando destinationEmail não é enviado; telefone em formato internacional válido
messagestringCondicionalObrigatório quando notificationLayoutStoreId não é enviado; corpo da mensagem sem layout (máx. 65535 caracteres)
payloadobjectNãoDados de exemplo para variáveis do template do layout; estrutura livre conforme os placeholders em message do layout

Exemplo com layout de notificação

1curl --request POST \
2  --url "{{MAIN_URL}}/notifications/credentials/42/test" \
3  --header "Content-Type: application/json" \
4  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
5  --data '{
6    "salesChannelId": 10,
7    "notificationLayoutStoreId": 1001,
8    "destinationEmail": "cliente.exemplo@lojademo.com.br",
9    "payload": {
10      "user": {
11        "name": "Maria Exemplo"
12      },
13      "product": {
14        "name": "Camiseta básica algodão",
15        "sku": "SKU-DEMO-001"
16      }
17    }
18  }'

Exemplo com mensagem livre

1curl --request POST \
2  --url "{{MAIN_URL}}/notifications/credentials/42/test" \
3  --header "Content-Type: application/json" \
4  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
5  --data '{
6    "salesChannelId": 10,
7    "destinationEmail": "cliente.exemplo@lojademo.com.br",
8    "message": "<p>Olá! Este é um <strong>envio de teste</strong> da credencial de notificação da loja.</p>"
9  }'

✅ Resposta de Sucesso

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

⚠️ Possíveis erros:

Código InternoCódigo HttpDescrição
UAPPI_TOOLS_NOTIFICATION_CREDENTIAL_NOT_FOUND404A credencial de notificação informada não foi encontrada para a loja autenticada.
UAPPI_TOOLS_NOTIFICATION_LAYOUT_NOT_FOUND404O layout de notificação informado em notificationLayoutStoreId não foi encontrado.
UAPPI_TOOLS_NOTIFICATION_SEND_NOTIFICATION_FAILED502O envio da notificação falhou no provedor externo (SMTP, SMS ou WhatsApp).

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

Institucional

;