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

Caixa de entrada de avisos

Lista os avisos do sino da conta do cliente, conta os não lidos e marca um ou todos como lidos.

A caixa de entrada é o sino de avisos dentro da conta: "Maria respondeu sua mensagem", "Sua campanha de incentivo chegou", e assim por diante. Cada aviso tem um título, um texto curto e um link para a tela que ele abre. O aviso nasce de um evento da plataforma e não pode ser criado nem apagado por estas rotas, só lido.

GET/api/v1/storefront/notifications/inboxCliente

Listar os avisos do sino

Parâmetros de consulta

limitintegerpadrão: 20

Quantos avisos devolver, de 1 a 100. Fora da faixa ou não numérico, vale 20.

offsetintegerpadrão: 0

Quantos avisos pular. Valor negativo ou não numérico vale 0.

unread_onlystring

true

Com o texto exato true, devolve só os não lidos. Qualquer outro valor devolve todos.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/notifications/inbox?limit=20&unread_only=true" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Avisos

json

{
  "items": [
    {
      "id": "d7c3a0b4-6f0e-4b19-8c3a-2f6d1e9b7a52",
      "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
      "event_type": "message.created",
      "title": "Nova mensagem de Casa do Café",
      "body": "Seu pedido sai amanhã.",
      "link": "/account/messages?thread=3f0d6c0e-2a8b-4a40-9f69-4a0f7d1e6a77",
      "metadata": { "thread_id": "3f0d6c0e-2a8b-4a40-9f69-4a0f7d1e6a77" },
      "created_at": "2026-10-11T18:30:00Z"
    }
  ],
  "total_count": 12,
  "unread_count": 3
}

Campos da resposta

itemsarray

Avisos da página, do mais novo para o mais antigo. [] quando não há nenhum.

items[].iduuid

Id do aviso.

items[].user_iduuid

Cliente dono do aviso.

items[].event_typestring

Nome do evento que gerou o aviso, como message.created ou incentive.communication. É texto aberto: a plataforma pode criar tipos novos, então não faça switch fechado.

items[].titlestring

Título do aviso.

items[].bodystring

Texto do aviso. Ausente quando vazio.

items[].linkstring

Caminho dentro da loja para abrir ao clicar (por exemplo /account/messages?thread=...). Ausente quando vazio.

items[].metadataobject

Dados extras do evento, como ids relacionados. Ausente quando não há.

items[].read_atstring

Quando foi lido (RFC 3339). Ausente enquanto não lido.

items[].created_atstring

Quando o aviso foi criado (RFC 3339).

total_countinteger

Total de avisos que combinam com o filtro (use para paginar com offset).

unread_countinteger

Total de avisos não lidos do cliente, independente do filtro.

Erros

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

GET/api/v1/storefront/notifications/inbox/unread-countCliente

Contar avisos não lidos

bash

curl "$BASE_URL/api/v1/storefront/notifications/inbox/unread-count" \
  -H "Authorization: Bearer $TOKEN"

200Contagem

json

{ "count": 3 }

Campos da resposta

countinteger

Avisos ainda não lidos do cliente.

POST/api/v1/storefront/notifications/inbox/{id}/readCliente

Marcar um aviso como lido

Parâmetros de caminho

iduuidobrigatório

items[].id do aviso.

bash

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

200Registrado

json

{ "ok": true }

POST/api/v1/storefront/notifications/inbox/read-allCliente

Marcar todos os avisos como lidos

bash

curl -X POST "$BASE_URL/api/v1/storefront/notifications/inbox/read-all" \
  -H "Authorization: Bearer $TOKEN"

200Registrado

json

{ "ok": true }

Campos da resposta

okboolean

Sempre true quando a operação não falha. As duas rotas de leitura devolvem só isso, sem a quantidade afetada.

Erros das rotas de leitura

Status	Quando	Corpo
401	Sem token, ou token inválido.	`{"error":"missing authorization header"}`
500	`{id}` que não é UUID, ou falha ao gravar.	`{"error":"failed to mark read","detail":"..."}` (ou `failed to mark all read`)

Veja também

Caixa de entrada de avisos

Lista os avisos do sino da conta do cliente, conta os não lidos e marca um ou todos como lidos.

GET/api/v1/storefront/notifications/inboxCliente

Listar os avisos do sino

Parâmetros de consulta

limitintegerpadrão: 20

Quantos avisos devolver, de 1 a 100. Fora da faixa ou não numérico, vale 20.

offsetintegerpadrão: 0

Quantos avisos pular. Valor negativo ou não numérico vale 0.

unread_onlystring

true

Com o texto exato true, devolve só os não lidos. Qualquer outro valor devolve todos.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/notifications/inbox?limit=20&unread_only=true" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Avisos

json

{
  "items": [
    {
      "id": "d7c3a0b4-6f0e-4b19-8c3a-2f6d1e9b7a52",
      "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
      "event_type": "message.created",
      "title": "Nova mensagem de Casa do Café",
      "body": "Seu pedido sai amanhã.",
      "link": "/account/messages?thread=3f0d6c0e-2a8b-4a40-9f69-4a0f7d1e6a77",
      "metadata": { "thread_id": "3f0d6c0e-2a8b-4a40-9f69-4a0f7d1e6a77" },
      "created_at": "2026-10-11T18:30:00Z"
    }
  ],
  "total_count": 12,
  "unread_count": 3
}

Campos da resposta

itemsarray

Avisos da página, do mais novo para o mais antigo. [] quando não há nenhum.

items[].iduuid

Id do aviso.

items[].user_iduuid

Cliente dono do aviso.

items[].event_typestring

Nome do evento que gerou o aviso, como message.created ou incentive.communication. É texto aberto: a plataforma pode criar tipos novos, então não faça switch fechado.

items[].titlestring

Título do aviso.

items[].bodystring

Texto do aviso. Ausente quando vazio.

items[].linkstring

Caminho dentro da loja para abrir ao clicar (por exemplo /account/messages?thread=...). Ausente quando vazio.

items[].metadataobject

Dados extras do evento, como ids relacionados. Ausente quando não há.

items[].read_atstring

Quando foi lido (RFC 3339). Ausente enquanto não lido.

items[].created_atstring

Quando o aviso foi criado (RFC 3339).

total_countinteger

Total de avisos que combinam com o filtro (use para paginar com offset).

unread_countinteger

Total de avisos não lidos do cliente, independente do filtro.

Erros

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

GET/api/v1/storefront/notifications/inbox/unread-countCliente

Contar avisos não lidos

bash

curl "$BASE_URL/api/v1/storefront/notifications/inbox/unread-count" \
  -H "Authorization: Bearer $TOKEN"

200Contagem

json

{ "count": 3 }

Campos da resposta

countinteger

Avisos ainda não lidos do cliente.

POST/api/v1/storefront/notifications/inbox/{id}/readCliente

Marcar um aviso como lido

Parâmetros de caminho

iduuidobrigatório

items[].id do aviso.

bash

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

200Registrado

json

{ "ok": true }

POST/api/v1/storefront/notifications/inbox/read-allCliente

Marcar todos os avisos como lidos

bash

curl -X POST "$BASE_URL/api/v1/storefront/notifications/inbox/read-all" \
  -H "Authorization: Bearer $TOKEN"

200Registrado

json

{ "ok": true }

Campos da resposta

okboolean

Sempre true quando a operação não falha. As duas rotas de leitura devolvem só isso, sem a quantidade afetada.

Erros das rotas de leitura

Status	Quando	Corpo
401	Sem token, ou token inválido.	`{"error":"missing authorization header"}`
500	`{id}` que não é UUID, ou falha ao gravar.	`{"error":"failed to mark read","detail":"..."}` (ou `failed to mark all read`)