Newsletter | Venddor API

API atual/Referência completa/Notificações e newsletter

Inscreve um e-mail na newsletter da loja, confirma a inscrição pelo link e cancela, pelo e-mail ou pelo link da campanha.

A newsletter é a lista de e-mails que recebe as campanhas da loja. Qualquer pessoa pode se inscrever, com ou sem conta: o rodapé do site, um bloco de captura e a página de cadastro usam estas rotas. Elas são públicas, sem token.

Pendente (P)→Ativa (A)→Cancelada (U)

`status`	Significado
`P`	Pendente: aguarda o clique no link de confirmação (só com confirmação dupla).
`A`	Ativa: recebe campanhas.
`U`	Cancelada: não recebe campanhas.

POST/api/v1/storefront/newsletter/subscribePública

Inscrever um e-mail

Corpo da requisição

emailstringobrigatório

E-mail da pessoa. Precisa ser um endereço válido.

namestring

Nome da pessoa, para personalizar campanhas. Opcional. Um nome vazio não apaga o que já estava gravado.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/newsletter/subscribe" \
  -H "Content-Type: application/json" \
  -d '{"email":"maria.souza@example.com","name":"Maria Souza"}'

Resposta

200Inscrição registrada

json

{
  "message": "subscribed successfully",
  "status": "P",
  "subscriber": {
    "id": "4c3b2a19-0f8e-4d7c-b6a5-948372615049",
    "email": "maria.souza@example.com",
    "name": "Maria Souza",
    "status": "P",
    "source": "storefront_block",
    "ip_address": "203.0.113.10",
    "subscribed_at": "2026-10-11T20:00:00Z",
    "created_at": "2026-10-11T20:00:00Z"
  }
}

Campos da resposta

messagestring

Texto fixo subscribed successfully (em inglês, como o servidor devolve).

statusstring

PA

P quando falta confirmar pelo e-mail, A quando a inscrição já está ativa. É o que decide a mensagem da sua tela.

subscriber.iduuid

Id do inscrito.

subscriber.emailstring

E-mail em minúsculas.

subscriber.namestring

Nome gravado. Pode ser vazio.

subscriber.statusstring

PA

Mesmo valor do status de cima.

subscriber.sourcestring

Origem da inscrição. Por esta rota, sempre storefront_block.

subscriber.ip_addressstring

IP de quem se inscreveu, quando disponível.

subscriber.subscribed_atstring

Quando se inscreveu (RFC 3339). É renovado a cada nova inscrição.

subscriber.unsubscribed_atstring

Quando cancelou. Ausente quem acabou de se inscrever.

subscriber.created_atstring

Quando o registro foi criado (RFC 3339).

Erros

Status	Quando	Corpo
400	JSON inválido.	`{"error":"invalid request body","detail":"..."}`
400	`email` vazio.	`{"error":"email is required"}`
400	`email` com formato inválido.	`{"error":"invalid email format"}`
403	Módulo `newsletter` desligado.	`{"error":"module_disabled","module":"newsletter"}`
500	Falha ao gravar.	`{"error":"failed to subscribe","detail":"..."}`

GET/api/v1/storefront/newsletter/confirmPública

Confirmar a inscrição pelo link

O link de confirmação enviado por e-mail aponta para uma página da loja, que chama esta rota com o token.

Parâmetros de consulta

tokenstringobrigatório

Token do link de confirmação (um UUID). Vale uma vez.

bash

curl "$BASE_URL/api/v1/storefront/newsletter/confirm?token=$CONFIRM_TOKEN"

200Inscrição confirmada

json

{ "message": "confirmed" }

Erros

Status	Quando	Corpo
400	Sem `token`.	`{"error":"invalid or expired confirmation token"}`
400	Token desconhecido, já usado, mal formado ou de quem não está pendente.	`{"error":"invalid or expired confirmation token","detail":"..."}`
403	Módulo `newsletter` desligado.	`{"error":"module_disabled","module":"newsletter"}`

POST/api/v1/storefront/newsletter/unsubscribePública

Cancelar a inscrição pelo e-mail

Corpo da requisição

emailstringobrigatório

E-mail a cancelar. Precisa ter formato válido.

bash

curl -X POST "$BASE_URL/api/v1/storefront/newsletter/unsubscribe" \
  -H "Content-Type: application/json" \
  -d '{"email":"maria.souza@example.com"}'

200Cancelamento processado

json

{ "message": "unsubscribed successfully" }

Erros

Status	Quando	Corpo
400	JSON inválido.	`{"error":"invalid request body","detail":"..."}`
400	`email` vazio.	`{"error":"email is required"}`
400	`email` com formato inválido.	`{"error":"invalid email format"}`
403	Módulo `newsletter` desligado.	`{"error":"module_disabled","module":"newsletter"}`

GET/api/v1/storefront/newsletter/unsubscribePública

Cancelar pelo link da campanha

É o link de cancelamento que vai no rodapé de cada campanha. Ele leva um token único por inscrito, de modo que a pessoa cancela com um clique, sem digitar o e-mail.

Parâmetros de consulta

tokenstringobrigatório

Token de cancelamento do inscrito, vindo do link do e-mail.

bash

curl "$BASE_URL/api/v1/storefront/newsletter/unsubscribe?token=$UNSUBSCRIBE_TOKEN"

200Cancelamento processado

json

{ "message": "unsubscribed successfully" }

Erros

Status	Quando	Corpo
403	Módulo `newsletter` desligado.	`{"error":"module_disabled","module":"newsletter"}`

Esta rota não devolve outros erros: token ausente, desconhecido ou já usado também respondem 200.

Veja também

Newsletter

Inscreve um e-mail na newsletter da loja, confirma a inscrição pelo link e cancela, pelo e-mail ou pelo link da campanha.

Pendente (P)→Ativa (A)→Cancelada (U)

`status`	Significado
`P`	Pendente: aguarda o clique no link de confirmação (só com confirmação dupla).
`A`	Ativa: recebe campanhas.
`U`	Cancelada: não recebe campanhas.

POST/api/v1/storefront/newsletter/subscribePública

Inscrever um e-mail

Corpo da requisição

emailstringobrigatório

E-mail da pessoa. Precisa ser um endereço válido.

namestring

Nome da pessoa, para personalizar campanhas. Opcional. Um nome vazio não apaga o que já estava gravado.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/newsletter/subscribe" \
  -H "Content-Type: application/json" \
  -d '{"email":"maria.souza@example.com","name":"Maria Souza"}'

Resposta

200Inscrição registrada

json

{
  "message": "subscribed successfully",
  "status": "P",
  "subscriber": {
    "id": "4c3b2a19-0f8e-4d7c-b6a5-948372615049",
    "email": "maria.souza@example.com",
    "name": "Maria Souza",
    "status": "P",
    "source": "storefront_block",
    "ip_address": "203.0.113.10",
    "subscribed_at": "2026-10-11T20:00:00Z",
    "created_at": "2026-10-11T20:00:00Z"
  }
}

Campos da resposta

messagestring

Texto fixo subscribed successfully (em inglês, como o servidor devolve).

statusstring

PA

P quando falta confirmar pelo e-mail, A quando a inscrição já está ativa. É o que decide a mensagem da sua tela.

subscriber.iduuid

Id do inscrito.

subscriber.emailstring

E-mail em minúsculas.

subscriber.namestring

Nome gravado. Pode ser vazio.

subscriber.statusstring

PA

Mesmo valor do status de cima.

subscriber.sourcestring

Origem da inscrição. Por esta rota, sempre storefront_block.

subscriber.ip_addressstring

IP de quem se inscreveu, quando disponível.

subscriber.subscribed_atstring

Quando se inscreveu (RFC 3339). É renovado a cada nova inscrição.

subscriber.unsubscribed_atstring

Quando cancelou. Ausente quem acabou de se inscrever.

subscriber.created_atstring

Quando o registro foi criado (RFC 3339).

Erros

Status	Quando	Corpo
400	JSON inválido.	`{"error":"invalid request body","detail":"..."}`
400	`email` vazio.	`{"error":"email is required"}`
400	`email` com formato inválido.	`{"error":"invalid email format"}`
403	Módulo `newsletter` desligado.	`{"error":"module_disabled","module":"newsletter"}`
500	Falha ao gravar.	`{"error":"failed to subscribe","detail":"..."}`

GET/api/v1/storefront/newsletter/confirmPública

Confirmar a inscrição pelo link

O link de confirmação enviado por e-mail aponta para uma página da loja, que chama esta rota com o token.

Parâmetros de consulta

tokenstringobrigatório

Token do link de confirmação (um UUID). Vale uma vez.

bash

curl "$BASE_URL/api/v1/storefront/newsletter/confirm?token=$CONFIRM_TOKEN"

200Inscrição confirmada

json

{ "message": "confirmed" }

Erros

Status	Quando	Corpo
400	Sem `token`.	`{"error":"invalid or expired confirmation token"}`
400	Token desconhecido, já usado, mal formado ou de quem não está pendente.	`{"error":"invalid or expired confirmation token","detail":"..."}`
403	Módulo `newsletter` desligado.	`{"error":"module_disabled","module":"newsletter"}`

POST/api/v1/storefront/newsletter/unsubscribePública

Cancelar a inscrição pelo e-mail

Corpo da requisição

emailstringobrigatório

E-mail a cancelar. Precisa ter formato válido.

bash

curl -X POST "$BASE_URL/api/v1/storefront/newsletter/unsubscribe" \
  -H "Content-Type: application/json" \
  -d '{"email":"maria.souza@example.com"}'

200Cancelamento processado

json

{ "message": "unsubscribed successfully" }

Erros

Status	Quando	Corpo
400	JSON inválido.	`{"error":"invalid request body","detail":"..."}`
400	`email` vazio.	`{"error":"email is required"}`
400	`email` com formato inválido.	`{"error":"invalid email format"}`
403	Módulo `newsletter` desligado.	`{"error":"module_disabled","module":"newsletter"}`

GET/api/v1/storefront/newsletter/unsubscribePública

Cancelar pelo link da campanha

É o link de cancelamento que vai no rodapé de cada campanha. Ele leva um token único por inscrito, de modo que a pessoa cancela com um clique, sem digitar o e-mail.

Parâmetros de consulta

tokenstringobrigatório

Token de cancelamento do inscrito, vindo do link do e-mail.

bash

curl "$BASE_URL/api/v1/storefront/newsletter/unsubscribe?token=$UNSUBSCRIBE_TOKEN"

200Cancelamento processado

json

{ "message": "unsubscribed successfully" }

Erros

Status	Quando	Corpo
403	Módulo `newsletter` desligado.	`{"error":"module_disabled","module":"newsletter"}`

Esta rota não devolve outros erros: token ausente, desconhecido ou já usado também respondem 200.