📧 Newsletter

📋 Visão Geral

O módulo de Newsletter permite que um visitante ou cliente da loja cadastre seu e-mail e nome na lista de newsletters, e que o cliente autenticado cancele sua inscrição a qualquer momento.

O cadastro não exige que o e-mail esteja vinculado a um cliente existente — qualquer pessoa pode se inscrever informando apenas e-mail e nome válidos. Ao cadastrar um e-mail que já está associado a um cliente na base de dados, o sistema ativa automaticamente as flags de envio de e-mail e SMS promocional desse cliente.

A remoção, realizada pelo próprio cliente autenticado, é definitiva — o registro é excluído permanentemente da lista de newsletter. Além disso, as flags de envio promocional do cliente vinculado ao e-mail são desativadas automaticamente.

🔄 Entidades Envolvidas

Newsletter

Representa uma inscrição na lista de comunicações da loja. Cada registro está vinculado a um canal de venda e contém os dados de identificação do assinante.

• id — identificador único da inscrição.
• salesChannelId — ID do canal de venda ao qual a inscrição pertence.
• email — e-mail do assinante.
• name — nome do assinante.
• masked — indica se o e-mail está mascarado (ex.: clientes com privacidade configurada).
• createdAt — data e hora de criação da inscrição.

📌 Notas e Considerações

• Cadastro idempotente — ao tentar inscrever um e-mail já presente na lista, o endpoint retorna o registro existente sem criar duplicata.
• Ativação automática de flags — se o e-mail cadastrado pertencer a um cliente existente na base, as flags send_promotional_email e send_promotional_sms desse cliente são ativadas automaticamente.
• Desativação automática de flags — ao remover a inscrição, as mesmas flags promocionais do cliente vinculado são desativadas automaticamente.
• Remoção definitiva — a exclusão é permanente. O cadastro do cliente em si não é afetado pela remoção da newsletter.

➕ Cadastro de Newsletter

📋 Descrição

Endpoint responsável por cadastrar um e-mail na lista de newsletter da loja.

Qualquer visitante pode se inscrever fornecendo apenas e-mail e nome. Não é necessário nenhum tipo de autenticação — o endpoint é completamente público.

Caso o e-mail informado já esteja cadastrado na newsletter, o endpoint retorna o registro existente sem criar duplicata.

Se o e-mail pertencer a um cliente já cadastrado na base de dados, o sistema ativa automaticamente as flags de e-mail e SMS promocional desse cliente (send_promotional_email e send_promotional_sms).

📝 Parâmetros

🏷️ Headers Obrigatórios

📦 Parâmetros do Corpo

💡 Exemplo de Requisição

1curl --request POST \
2  --url '{{MAIN_URL}}/customer/newsletter' \
3  --header 'Content-Type: application/json' \
4  --data '{
5    "email": "cliente@exemplo.com",
6    "name": "Maria Silva"
7  }'

✅ Resposta de Sucesso

HTTP Status: 201 Created

1{
2  "status": true,
3  "data": {
4    "id": 456,
5    "salesChannelId": 1,
6    "email": "cliente@exemplo.com",
7    "name": "Maria Silva",
8    "masked": false,
9    "createdAt": "2026-05-13 10:00:00"
10  }
11}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

🗑️ Remover Newsletter do Cliente

📋 Descrição

Endpoint responsável por remover o cadastro de newsletter do cliente autenticado na loja.

A exclusão é definitiva — o registro é removido permanentemente da lista de newsletter da loja. Adicionalmente, as flags de envio promocional do cliente são desativadas automaticamente (send_promotional_email e send_promotional_sms passam a false).

A remoção opera sobre o e-mail do cliente autenticado: o sistema localiza o registro de newsletter correspondente a esse e-mail no canal de venda e o exclui. O cadastro do cliente em si não é afetado.

🔐 Permissão

• CustomerAuth — autenticação do cliente via token JWT

📝 Parâmetros

🏷️ Headers Obrigatórios

💡 Exemplo de Requisição

1curl --request DELETE \
2  --url '{{MAIN_URL}}/customer/newsletter' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json'

✅ Resposta de Sucesso

HTTP Status: 200 OK

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

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.