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

Histórico de e-mails da conta

Lista os registros de e-mails enviados à conta do cliente e marca um deles como lido.

Cada vez que a plataforma envia um e-mail a um cliente que tem conta, ela guarda um registro: o assunto vira o title e o corpo vira o body. Estas rotas devolvem esses registros. Elas servem para telas do tipo "e-mails que recebi", e não para o sino de avisos, que usa a caixa de entrada.

GET/api/v1/storefront/notificationsCliente

Listar o histórico de e-mails

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Fora da faixa, vale 20.

typestring

Filtra por notification_type (por exemplo email).

statusstring

readunreadpending

read devolve só os lidos; unread e pending devolvem só os não lidos. Outro valor é ignorado.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/notifications?status=unread&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Registros

json

{
  "notifications": [
    {
      "id": "1b9f6c0e-3d4a-4e7b-9a52-7c6d5e4f3a21",
      "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
      "title": "Seu pedido foi enviado",
      "body": "<p>Olá, Maria. O pedido PEDIDO-20261010-0004 saiu para entrega.</p>",
      "notification_type": "email",
      "reference_type": "email",
      "is_read": false,
      "created_at": "2026-10-11T18:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

notificationsarray

Registros da página. Pode vir null quando não há nenhum; trate null como lista vazia.

notifications[].iduuid

Id do registro.

notifications[].user_iduuid

Cliente dono.

notifications[].titlestring

Assunto do e-mail.

notifications[].bodystring

Corpo do e-mail como foi enviado. Normalmente é HTML: sanitize antes de exibir.

notifications[].notification_typestring

Tipo do registro. Hoje, email.

notifications[].reference_typestring

Origem do registro. Ausente quando vazio.

notifications[].reference_idstring

Id do objeto de origem. Ausente quando vazio.

notifications[].is_readboolean

Se o cliente já marcou como lido.

notifications[].created_atstring

Quando o e-mail foi registrado (RFC 3339).

totalinteger

Total de registros que combinam com os filtros.

pageinteger

Página devolvida.

per_pageinteger

Itens por página aplicados.

total_pagesinteger

Total de páginas.

Erros

Status	Quando	Corpo
401	Sem token.	`{"error":"missing authorization header"}`
403	Token de chave de API sem o escopo `customer:read`.	`{"error":"missing_scope","required":"customer:read"}`
500	Falha ao consultar.	`{"error":"failed to get notifications","detail":"..."}`

PUT/api/v1/storefront/notifications/{id}/readCliente

Marcar um registro como lido

Parâmetros de caminho

iduuidobrigatório

notifications[].id do registro.

bash

curl -X PUT "$BASE_URL/api/v1/storefront/notifications/$NOTIFICATION_ID/read" \
  -H "Authorization: Bearer $TOKEN"

200Marcado

json

{ "message": "notification marked as read" }

Erros

Status	Quando	Corpo
401	Sem token.	`{"error":"missing authorization header"}`
404	O registro não existe ou não é do cliente.	`{"error":"notification not found","detail":"..."}`

Veja também

Histórico de e-mails da conta

Lista os registros de e-mails enviados à conta do cliente e marca um deles como lido.

GET/api/v1/storefront/notificationsCliente

Listar o histórico de e-mails

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Fora da faixa, vale 20.

typestring

Filtra por notification_type (por exemplo email).

statusstring

readunreadpending

read devolve só os lidos; unread e pending devolvem só os não lidos. Outro valor é ignorado.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/notifications?status=unread&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Registros

json

{
  "notifications": [
    {
      "id": "1b9f6c0e-3d4a-4e7b-9a52-7c6d5e4f3a21",
      "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
      "title": "Seu pedido foi enviado",
      "body": "<p>Olá, Maria. O pedido PEDIDO-20261010-0004 saiu para entrega.</p>",
      "notification_type": "email",
      "reference_type": "email",
      "is_read": false,
      "created_at": "2026-10-11T18:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

notificationsarray

Registros da página. Pode vir null quando não há nenhum; trate null como lista vazia.

notifications[].iduuid

Id do registro.

notifications[].user_iduuid

Cliente dono.

notifications[].titlestring

Assunto do e-mail.

notifications[].bodystring

Corpo do e-mail como foi enviado. Normalmente é HTML: sanitize antes de exibir.

notifications[].notification_typestring

Tipo do registro. Hoje, email.

notifications[].reference_typestring

Origem do registro. Ausente quando vazio.

notifications[].reference_idstring

Id do objeto de origem. Ausente quando vazio.

notifications[].is_readboolean

Se o cliente já marcou como lido.

notifications[].created_atstring

Quando o e-mail foi registrado (RFC 3339).

totalinteger

Total de registros que combinam com os filtros.

pageinteger

Página devolvida.

per_pageinteger

Itens por página aplicados.

total_pagesinteger

Total de páginas.

Erros

Status	Quando	Corpo
401	Sem token.	`{"error":"missing authorization header"}`
403	Token de chave de API sem o escopo `customer:read`.	`{"error":"missing_scope","required":"customer:read"}`
500	Falha ao consultar.	`{"error":"failed to get notifications","detail":"..."}`

PUT/api/v1/storefront/notifications/{id}/readCliente

Marcar um registro como lido

Parâmetros de caminho

iduuidobrigatório

notifications[].id do registro.

bash

curl -X PUT "$BASE_URL/api/v1/storefront/notifications/$NOTIFICATION_ID/read" \
  -H "Authorization: Bearer $TOKEN"

200Marcado

json

{ "message": "notification marked as read" }

Erros

Status	Quando	Corpo
401	Sem token.	`{"error":"missing authorization header"}`
404	O registro não existe ou não é do cliente.	`{"error":"notification not found","detail":"..."}`