Avaliações e perguntas

A página de produto convence pela opinião de quem já comprou. Esta seção cobre as leituras públicas de avaliações (lista, notas médias, resumo), as perguntas e respostas que qualquer visitante pode enviar, e os selos de prova social ("120 vendidos em 30 dias", "últimas 3 unidades"). Todas funcionam sem login; o envio de uma avaliação, ao contrário, só acontece a partir de um pedido entregue.

Como funciona

1. Mostrar a nota

   Notas do produto devolve a média e quantas avaliações há de 1 a 5 estrelas, para o cabeçalho e o histograma.

2. Listar as avaliações

   Listar avaliações devolve as avaliações aprovadas, com paginação e ordenação (mais recentes, melhores, mais úteis).

3. Resumo e prova social

   Resumo das avaliações traz um texto-síntese e os aspectos mais citados. Prova social traz os selos de venda e urgência.

4. Perguntas

   Perguntas do produto lista as perguntas respondidas e deixa o visitante enviar uma nova.

Conceitos-chave

Quem pode avaliar

Quem comprou. A avaliação é criada na tela de pedido, uma por produto do pedido entregue (POST /api/v1/storefront/orders/{id}/items/{productID}/review, que pertence à seção de pedidos do cliente). Ela entra pendente e só aparece depois de aprovada. A rota antiga de avaliação direta no produto está descrita em Enviar avaliação.

Nota

A nota é um inteiro de 1 a 5. A média (avg_rating) e a distribuição consideram apenas avaliações aprovadas.

Id do produto

As rotas de avaliação aceitam o UUID ou o slug do produto. As rotas de perguntas e de prova social aceitam só o UUID.

Cache e módulos

As leituras desta seção vêm com Cache-Control: public, max-age=300, stale-while-revalidate=1800. Lojas sem o módulo respondem 403 module_disabled ou feature_not_available.

Endpoints

Erros comuns

• Tentar criar avaliação por POST /products/{id}/reviews. Responde sempre 410 reviews_only_from_order.
• Esperar [] em reviews de um produto sem avaliações. Hoje a lista vem null nesse caso; trate null como vazio.
• Mandar pergunta com menos de 5 ou mais de 500 caracteres. Responde 400.
• Esquecer o e-mail na pergunta de visitante. Sem token, o corpo precisa de guest.email.
• Esperar resumo em qualquer produto. O resumo só existe com avaliações suficientes; sem ele a resposta é null.

Próximos passos