API atual/Referência completa/Conteúdo da vitrine

Voto de utilidade em avaliação

Registra que uma avaliação de produto foi útil, um voto por cliente ou por sessão de visitante.

Nas páginas de produto, cada avaliação tem o botão "Esta avaliação foi útil?". Esta rota soma o voto. Cada pessoa vota uma vez por avaliação, e votar de novo não faz nada: a resposta devolve a avaliação como está.

POST/api/v1/storefront/reviews/{id}/helpfulPública

Votar que uma avaliação foi útil

Parâmetros de caminho

iduuidobrigatório

Id da avaliação (reviews[].id da listagem de avaliações do produto).

Cabeçalhos

Authorizationstring

Bearer <access_token> do cliente. Opcional quando houver X-Session-ID.

X-Session-IDstring

Identificador da sessão do visitante (um UUID que o seu front-end gera e guarda). Obrigatório se não houver token.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/reviews/$REVIEW_ID/helpful" \
  -H "X-Session-ID: $SESSION_ID"

Resposta

200Voto registrado

json

{
  "id": "7d6c5b4a-3928-4170-8695-a4b3c2d1e0f9",
  "product_id": "0f6c3b0a-6a52-4c53-8d2c-0e1a1d7a9b21",
  "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
  "rating": 5,
  "title": "Excelente",
  "body": "Chegou rápido e o café é muito bom.",
  "pros": "Sabor",
  "cons": "",
  "images": [],
  "status": "approved",
  "helpful_count": 4,
  "created_at": "2026-10-05T10:00:00Z"
}

Campos da resposta

iduuid

Id da avaliação.

product_iduuid

Produto avaliado.

user_iduuid

Cliente que avaliou. Ausente em avaliação de visitante.

guest_namestring

Nome informado pelo visitante que avaliou. Ausente quando não há.

guest_emailstring

E-mail informado pelo visitante que avaliou. É dado pessoal: não exiba. Ausente quando não há.

ratinginteger

Nota, de 1 a 5.

titlestring

Título da avaliação. Ausente quando não há.

bodystring

Texto da avaliação. Ausente quando não há.

prosstring

Pontos positivos. Pode ser vazio.

consstring

Pontos negativos. Pode ser vazio.

imagesarray

Fotos da avaliação: objetos com url, thumbnail_url (opcional) e position.

statusstring

approvedpendingrejectedspamdisabledhidden

Estado de moderação.

helpful_countinteger

Total de votos "útil", já contando o seu.

created_atstring

Quando foi publicada (RFC 3339).

Erros

Status	Quando	Corpo
400	Sem token e sem `X-Session-ID`.	`{"error":"session_id or authentication required"}`
400	`id` não é UUID.	`{"error":"invalid id","detail":"id must be a valid UUID"}`
403	Módulo `product-reviews` desligado.	`{"error":"module_disabled","module":"product-reviews"}`
404	A avaliação não existe.	`{"error":"review not found","detail":"review not found"}`
500	Falha ao gravar.	`{"error":"failed to mark helpful","detail":"..."}`

Veja também