Documentação de Fila

Visão Geral

A Fila de Notificações é o componente responsável pela entrega resiliente e assíncrona de todas as mensagens geradas pela plataforma. 📶

Ao desacoplar o registro da notificação do seu envio real, a fila garante que flutuações de performance em provedores externos (como SMTPs lentos ou APIs de mensageria temporariamente instáveis) não impactem a experiência do usuário final no site ou painel administrativo. 🚀

Estados do Processamento

• Pending: O item foi registrado com sucesso e aguarda na fila para ser processado pelo backend. ⏳
• Sent: A notificação foi enviada com sucesso para o provedor externo. ✅
• Error: Ocorreu uma falha no processamento ou envio (detalhes disponíveis no campo de erro para auditoria). ⚠️

Notas e Considerações

Através da fila, é possível realizar a auditoria completa dos disparos, visualizando o destinatário, o assunto e o conteúdo final que foi enviado, sendo uma ferramenta vital para o suporte ao cliente. 🛠️

A visualização de dados requer a permissão NOTIFICATION_QUEUE_READ, enquanto o enfileiramento manual de mensagens (via API) exige NOTIFICATION_QUEUE_WRITE. 🔐

Listagem de notificações na fila

Descrição

Este endpoint atua como o monitor de saúde da comunicação transacional, permitindo acompanhar em tempo real o fluxo de processamento das notificações enfileiradas na loja. 📧

A finalidade desta listagem é oferecer total transparência sobre o ciclo de vida do disparo, desde o momento em que entra na fila como pending até a conclusão do envio ou a ocorrência de um eventual erro técnico.

É uma ferramenta indispensável para auditoria e suporte, pois permite visualizar o conteúdo final renderizado (assunto e mensagem em HTML) e a credencial utilizada em cada operação. 🚀

Através dos filtros de condição, é possível isolar envios por status, facilitando a identificação rápida de gargalos ou falhas de comunicação.

A resposta inclui suporte nativo a paginação, suportando a gestão de grandes volumes de registros históricos de envios. 📶

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

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/queue" \
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": 255,
7        "notificationCredentialId": 42,
8        "destinationName": "Maria Exemplo",
9        "destinationEmail": "cliente.exemplo@lojademo.com.br",
10        "destinationPhoneNumber": "+5511999990000",
11        "subject": "Recebemos seu pedido de N° 1001",
12        "message": "<center><table width=\"360\"><tr><td><strong>RECEBEMOS SEU PEDIDO!</strong><p>Prezado(a) <strong>Maria Exemplo</strong>, recebemos seu pedido N° <strong>1001</strong>.</p></td></tr></table></center>",
13        "status": "pending",
14        "error": null,
15        "createdAt": "2026-05-22 01:42:37",
16        "updatedAt": "2026-05-22 01:42:37"
17      }
18    ],
19    "pagination": {
20      "limit": 10,
21      "offset": 0,
22      "pages": 16,
23      "registers": 157
24    }
25  }
26}

Adicionar notificações na fila

Descrição

Este endpoint é o ponto de entrada para a comunicação transacional assíncrona da plataforma, permitindo o enfileiramento em lote de mensagens destinadas aos clientes. 📧

Ao adicionar uma notificação na fila, o sistema registra o evento de origem (identificador da notificação) e associa os dados dinâmicos enviados no payload ao destinatário informado.

A grande vantagem deste modelo é a resiliência e performance:

O backend persiste o item com status pending e processa o envio real em segundo plano, garantindo que o fluxo principal da aplicação não seja interrompido pelo tempo de resposta de serviços externos de e-mail ou mensageria. 🚀

A API aceita até 100 notificações por requisição, processando cada item conforme o mapeamento ativo para o canal de venda.

É ideal para situações de altas cargas de disparos ou integrações que precisam notificar múltiplos clientes simultaneamente de forma eficiente. ✨

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

Parâmetros

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

1curl --request POST \
2  --url "{{MAIN_URL}}/notifications/queue" \
3  --header "Content-Type: application/json" \
4  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
5  --data '{
6    "items": [
7      {
8        "notificationIdentifier": "order-group-creation",
9        "destinationName": "Maria Exemplo",
10        "destinationEmail": "cliente.exemplo@lojademo.com.br",
11        "destinationPhoneNumber": "+5511999990000",
12        "payload": {
13          "name": "Maria Exemplo"
14        }
15      }
16    ]
17  }'

✅ Resposta de Sucesso

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