VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa

Notificações e newsletter

Como o cliente recebe avisos da loja dentro da vitrine, escolhe por onde quer ser avisado e assina a newsletter.

A loja avisa o cliente por vários caminhos: um sino de avisos dentro da conta, e-mails de pedido e, se ele quiser, uma newsletter de novidades. Esta seção reúne as rotas que o front-end da conta usa para ler esses avisos, escolher os canais e assinar ou cancelar a newsletter.

Quem gera os avisos não é o cliente: são eventos da plataforma (uma resposta do seller, uma mudança de status, uma campanha). Aqui o cliente só consulta e marca como lido.

Pontos principais
  • Existem duas listas de avisos. A caixa de entrada (/notifications/inbox) é o sino da conta e a lista que você deve usar. O histórico de e-mails (/notifications) é uma lista antiga, que guarda os e-mails enviados à conta.
  • Todas as rotas de aviso e de preferências exigem o token de um cliente. A newsletter é pública, mas depende do módulo newsletter; módulo desligado devolve 403 module_disabled.
  • Preferências funcionam por exceção: sem registro, o canal está ligado. Só grave o que o cliente desligou.
  • Os dois jeitos de marcar como lido usam métodos diferentes: POST na caixa de entrada, PUT no histórico.
  • Datas são RFC 3339 em UTC.

Como funciona

  1. A plataforma gera o aviso
    Um evento (por exemplo, uma mensagem nova de um seller, ou uma campanha de incentivo) grava uma linha na caixa de entrada do cliente e, quando for o caso, envia também o e-mail.
  2. O front-end lê o sino
    Consulta o contador de não lidas a cada 30 segundos e carrega a lista quando o cliente abre o sino.
  3. O cliente interage
    Clica no aviso (o link leva à tela certa) e o front-end marca como lido. "Marcar tudo" zera o contador.
  4. O cliente ajusta os canais
    Em Preferências liga ou desliga e-mail, SMS, push e WhatsApp por tipo de evento.

Conceitos principais

Caixa de entrada x histórico de e-mails

Caixa de entradaHistórico de e-mails
Rotas/notifications/inbox.../notifications e /notifications/{id}/read
OrigemEventos da plataforma (mensagens, campanhas, pedidos)Cada e-mail que a plataforma enviou à conta
Lidoread_at (data ou ausente)is_read (verdadeiro ou falso)
Use paraO sino e a tela de avisosMostrar o que foi enviado por e-mail

Canais e tipos de evento

Uma preferência liga ou desliga um par canal e tipo de evento. Os canais são email, sms, push e whatsapp. Os tipos de evento são order_status, promotions, newsletter, vendor_updates e security_alerts.

Newsletter e confirmação dupla

A newsletter é por loja. Se a loja liga a confirmação dupla (double opt-in), quem se inscreve fica P (pendente) até clicar no link do e-mail; só A (ativo) recebe campanhas.

Endpoints

MétodoRotaPara quêAutenticação
GET/api/v1/storefront/notifications/inboxLista os avisos do sino.Cliente
GET/api/v1/storefront/notifications/inbox/unread-countConta os avisos não lidos.Cliente
POST/api/v1/storefront/notifications/inbox/{id}/readMarca um aviso como lido.Cliente
POST/api/v1/storefront/notifications/inbox/read-allMarca todos como lidos.Cliente
GET/api/v1/storefront/notificationsLista o histórico de e-mails.Cliente
PUT/api/v1/storefront/notifications/{id}/readMarca um item do histórico como lido.Cliente
GET/api/v1/storefront/notifications/preferencesLê as preferências.Cliente
PUT/api/v1/storefront/notifications/preferencesGrava várias preferências.Cliente
PUT/api/v1/storefront/notifications/preferences/{channel}Grava uma preferência.Cliente
POST/api/v1/storefront/newsletter/subscribeInscreve um e-mail.Pública
GET/api/v1/storefront/newsletter/confirmConfirma a inscrição pelo link.Pública
POST/api/v1/storefront/newsletter/unsubscribeCancela pelo e-mail.Pública
GET/api/v1/storefront/newsletter/unsubscribeCancela pelo link do e-mail.Pública

Erros comuns

  • Usar /notifications para o sino. Ele devolve o histórico de e-mails. O sino é /notifications/inbox.
  • Marcar como lido com o método errado. Na caixa de entrada é POST .../inbox/{id}/read; no histórico é PUT .../{id}/read.
  • Mandar o canal só no caminho. Em PUT /notifications/preferences/{channel} o canal é lido do corpo, não do caminho (veja Preferências).
  • Achar que read-all devolve o total. Ele só responde {"ok": true}; consulte o contador depois.
  • Pedir unread_only com outro valor. Só o texto exato true filtra; qualquer outro valor lista tudo.
  • Esperar 404 ao cancelar a newsletter de um e-mail desconhecido. O cancelamento responde sempre 200, por privacidade.

Próximos passos

Caixa de entrada
O sino de avisos da conta.
Preferências
Canais e tipos de evento.
Newsletter
Inscrever, confirmar e cancelar.
Mensagens do cliente
Conversas com a loja e com sellers.
Anterior
Digitando e presença
Próxima
Caixa de entrada de avisos
Nesta página
  • Como funciona
  • Conceitos principais
  • Caixa de entrada x histórico de e-mails
  • Canais e tipos de evento
  • Newsletter e confirmação dupla
  • Endpoints
  • Erros comuns
  • Próximos passos