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

Preferências de notificação

Lê e grava, por canal e tipo de evento, o que o cliente aceita receber.

O cliente escolhe por onde (email, sms, push, whatsapp) e sobre o quê (order_status, promotions, newsletter, vendor_updates, security_alerts) quer ser avisado. Cada combinação é uma preferência com enabled verdadeiro ou falso.

GET/api/v1/storefront/notifications/preferencesCliente

Ler as preferências

Exemplo de requisição

bash

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

Resposta

200Preferências gravadas

json

{
  "preferences": [
    {
      "id": "6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d",
      "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
      "channel": "email",
      "event_type": "promotions",
      "enabled": false,
      "created_at": "2026-10-01T12:00:00Z",
      "updated_at": "2026-10-11T09:30:00Z"
    }
  ],
  "total": 1
}

Campos da resposta

preferencesarray

Preferências gravadas, ordenadas por canal e tipo de evento. Pode vir null quando o cliente nunca gravou nenhuma; trate como lista vazia.

preferences[].iduuid

Id do registro.

preferences[].user_iduuid

Cliente dono.

preferences[].channelstring

emailsmspushwhatsapp

Canal.

preferences[].event_typestring

order_statuspromotionsnewslettervendor_updatessecurity_alerts

Tipo de evento.

preferences[].enabledboolean

Se o cliente aceita receber.

preferences[].created_atstring

Primeira gravação (RFC 3339).

preferences[].updated_atstring

Última alteração (RFC 3339).

totalinteger

Quantidade de preferências na lista.

Erros

Status	Quando	Corpo
401	Sem token, ou token inválido.	`{"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 list notification preferences","detail":"..."}`

PUT/api/v1/storefront/notifications/preferences/{channel}Cliente

Gravar uma preferência

Grava uma combinação de canal e tipo de evento e devolve o registro.

Parâmetros de caminho

channelstring

Aceito na URL, mas ignorado: o canal gravado é o do corpo. Use o mesmo valor nos dois para não confundir.

Corpo da requisição

channelstringobrigatório

emailsmspushwhatsapp

Canal a gravar.

event_typestringobrigatório

order_statuspromotionsnewslettervendor_updatessecurity_alerts

Tipo de evento.

enabledbooleanobrigatório

true aceita, false recusa. Se omitido, vale false.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/storefront/notifications/preferences/email" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"channel":"email","event_type":"promotions","enabled":false}'

200Preferência gravada

json

{
  "id": "6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d",
  "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
  "channel": "email",
  "event_type": "promotions",
  "enabled": false,
  "created_at": "2026-10-01T12:00:00Z",
  "updated_at": "2026-10-11T09:30:00Z"
}

A resposta é o registro, com os mesmos campos de preferences[] na leitura.

PUT/api/v1/storefront/notifications/preferencesCliente

Gravar várias preferências

Corpo da requisição

preferencesarrayobrigatório

Lista de preferências, na ordem em que serão gravadas.

channelstringobrigatório

emailsmspushwhatsapp

Canal.

event_typestringobrigatório

order_statuspromotionsnewslettervendor_updatessecurity_alerts

Tipo de evento.

enabledbooleanobrigatório

true aceita, false recusa. Se omitido, vale false.

bash

curl -X PUT "$BASE_URL/api/v1/storefront/notifications/preferences" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"preferences":[
        {"channel":"email","event_type":"promotions","enabled":false},
        {"channel":"push","event_type":"order_status","enabled":true}
      ]}'

200Preferências gravadas

json

{
  "preferences": [
    { "id": "6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d", "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10", "channel": "email", "event_type": "promotions", "enabled": false, "created_at": "2026-10-01T12:00:00Z", "updated_at": "2026-10-11T09:30:00Z" },
    { "id": "0f1e2d3c-4b5a-4968-8776-655443322110", "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10", "channel": "push", "event_type": "order_status", "enabled": true, "created_at": "2026-10-11T09:30:00Z", "updated_at": "2026-10-11T09:30:00Z" }
  ],
  "total": 2
}

A resposta traz apenas as preferências enviadas, na mesma ordem, e não a lista completa do cliente. Uma lista preferences vazia devolve "preferences": null e "total": 0.

Erros

As duas rotas de gravação têm os mesmos erros.

Status	Quando	Corpo
400	JSON inválido.	`{"error":"invalid request body","detail":"..."}`
400	Canal fora da lista.	`{"error":"invalid channel: fax (must be email, sms, push, or whatsapp)"}`
400	Tipo de evento fora da lista.	`{"error":"invalid event_type: x"}`
400	Item inválido na gravação em lote.	`{"error":"set preference fax/promotions: invalid channel: fax (must be email, sms, push, or whatsapp)"}`
401	Sem token, ou token inválido.	`{"error":"missing authorization header"}`
403	Token de chave de API sem o escopo `customer:write`.	`{"error":"missing_scope","required":"customer:write"}`

Veja também

Preferências de notificação

Lê e grava, por canal e tipo de evento, o que o cliente aceita receber.

GET/api/v1/storefront/notifications/preferencesCliente

Ler as preferências

Exemplo de requisição

bash

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

Resposta

200Preferências gravadas

json

{
  "preferences": [
    {
      "id": "6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d",
      "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
      "channel": "email",
      "event_type": "promotions",
      "enabled": false,
      "created_at": "2026-10-01T12:00:00Z",
      "updated_at": "2026-10-11T09:30:00Z"
    }
  ],
  "total": 1
}

Campos da resposta

preferencesarray

Preferências gravadas, ordenadas por canal e tipo de evento. Pode vir null quando o cliente nunca gravou nenhuma; trate como lista vazia.

preferences[].iduuid

Id do registro.

preferences[].user_iduuid

Cliente dono.

preferences[].channelstring

emailsmspushwhatsapp

Canal.

preferences[].event_typestring

order_statuspromotionsnewslettervendor_updatessecurity_alerts

Tipo de evento.

preferences[].enabledboolean

Se o cliente aceita receber.

preferences[].created_atstring

Primeira gravação (RFC 3339).

preferences[].updated_atstring

Última alteração (RFC 3339).

totalinteger

Quantidade de preferências na lista.

Erros

Status	Quando	Corpo
401	Sem token, ou token inválido.	`{"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 list notification preferences","detail":"..."}`

PUT/api/v1/storefront/notifications/preferences/{channel}Cliente

Gravar uma preferência

Grava uma combinação de canal e tipo de evento e devolve o registro.

Parâmetros de caminho

channelstring

Aceito na URL, mas ignorado: o canal gravado é o do corpo. Use o mesmo valor nos dois para não confundir.

Corpo da requisição

channelstringobrigatório

emailsmspushwhatsapp

Canal a gravar.

event_typestringobrigatório

order_statuspromotionsnewslettervendor_updatessecurity_alerts

Tipo de evento.

enabledbooleanobrigatório

true aceita, false recusa. Se omitido, vale false.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/storefront/notifications/preferences/email" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"channel":"email","event_type":"promotions","enabled":false}'

200Preferência gravada

json

{
  "id": "6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d",
  "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
  "channel": "email",
  "event_type": "promotions",
  "enabled": false,
  "created_at": "2026-10-01T12:00:00Z",
  "updated_at": "2026-10-11T09:30:00Z"
}

A resposta é o registro, com os mesmos campos de preferences[] na leitura.

PUT/api/v1/storefront/notifications/preferencesCliente

Gravar várias preferências

Corpo da requisição

preferencesarrayobrigatório

Lista de preferências, na ordem em que serão gravadas.

channelstringobrigatório

emailsmspushwhatsapp

Canal.

event_typestringobrigatório

order_statuspromotionsnewslettervendor_updatessecurity_alerts

Tipo de evento.

enabledbooleanobrigatório

true aceita, false recusa. Se omitido, vale false.

bash

curl -X PUT "$BASE_URL/api/v1/storefront/notifications/preferences" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"preferences":[
        {"channel":"email","event_type":"promotions","enabled":false},
        {"channel":"push","event_type":"order_status","enabled":true}
      ]}'

200Preferências gravadas

json

{
  "preferences": [
    { "id": "6a5b4c3d-2e1f-4a0b-9c8d-7e6f5a4b3c2d", "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10", "channel": "email", "event_type": "promotions", "enabled": false, "created_at": "2026-10-01T12:00:00Z", "updated_at": "2026-10-11T09:30:00Z" },
    { "id": "0f1e2d3c-4b5a-4968-8776-655443322110", "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10", "channel": "push", "event_type": "order_status", "enabled": true, "created_at": "2026-10-11T09:30:00Z", "updated_at": "2026-10-11T09:30:00Z" }
  ],
  "total": 2
}

A resposta traz apenas as preferências enviadas, na mesma ordem, e não a lista completa do cliente. Uma lista preferences vazia devolve "preferences": null e "total": 0.

Erros

As duas rotas de gravação têm os mesmos erros.

Status	Quando	Corpo
400	JSON inválido.	`{"error":"invalid request body","detail":"..."}`
400	Canal fora da lista.	`{"error":"invalid channel: fax (must be email, sms, push, or whatsapp)"}`
400	Tipo de evento fora da lista.	`{"error":"invalid event_type: x"}`
400	Item inválido na gravação em lote.	`{"error":"set preference fax/promotions: invalid channel: fax (must be email, sms, push, or whatsapp)"}`
401	Sem token, ou token inválido.	`{"error":"missing authorization header"}`
403	Token de chave de API sem o escopo `customer:write`.	`{"error":"missing_scope","required":"customer:write"}`