Avaliações
Moderação das avaliações de produtos feitas pelos clientes: aprovar, rejeitar, responder em nome do seller e regenerar o resumo.
Depois de comprar, o cliente pode avaliar o produto com uma nota de 1 a 5 estrelas, um texto, fotos e até um vídeo. Na maioria das lojas essas avaliações passam por moderação antes de aparecer. Esta seção é a API da moderação: listar o que chegou, aprovar ou rejeitar (uma a uma ou em lote), responder em nome do seller e pedir o resumo por IA de um produto.
Como funciona
Uma avaliação nasce na vitrine (ou no app) e entra na fila. O moderador lista as pendentes (status=pending), aprova as boas e rejeita as impróprias. O seller (ou o administrador por ele) pode responder publicamente.
| Estado | Letra | Significado | Aparece na vitrine |
|---|---|---|---|
pending | P | Aguardando moderação. | Não |
approved | A | Aprovada. | Sim |
rejected | R | Rejeitada. | Não |
spam | S | Marcada como spam. | Não |
disabled | D | Desativada. | Não |
hidden | H | Oculta. | Não |
Nas respostas os estados voltam por extenso. Nos filtros você pode usar a palavra ou a letra.
Conceitos importantes
Avaliação de visitante
Uma avaliação pode vir de um cliente cadastrado ou de um visitante, que informa e-mail e, se quiser, nome. Nesse caso is_guest vem true e o e-mail fica guardado para o contato da moderação (não é exibido na vitrine).
Resposta do seller
A resposta pública fica abaixo da avaliação e leva o nome do seller dono do produto. Por esta API o administrador escreve, edita ou remove essa resposta, mesmo sendo de um seller. Produtos sem seller (da própria loja) não aceitam resposta.
Nota média
Cada produto guarda a média das avaliações aprovadas. As rotas de moderação a recalculam.
Resumo por IA
Quando um produto tem avaliações suficientes, a vitrine pode mostrar um resumo gerado por IA. A rota regenerate refaz esse resumo sob demanda.
Mídia
Fotos (images) e vídeo (video) são enviados pelo cliente. O vídeo só é servido quando a avaliação está aprovada.
Endpoints
| Método | Caminho | Para que serve | Autenticação |
|---|---|---|---|
| GET | /api/v1/admin/reviews | Lista as avaliações de produtos para moderação | admin |
| PUT | /api/v1/admin/reviews/{id}/approve | Aprova uma avaliação e a publica na vitrine | admin |
| PUT | /api/v1/admin/reviews/{id}/reject | Rejeita uma avaliação | admin |
| DELETE | /api/v1/admin/reviews/{id} | Apaga uma avaliação | admin |
| POST | /api/v1/admin/reviews/bulk | Aprova, rejeita ou apaga várias avaliações de uma vez | admin |
| POST | /api/v1/admin/reviews/{id}/vendor-reply | Escreve a resposta do seller a uma avaliação | admin |
| PATCH | /api/v1/admin/reviews/{id}/vendor-reply | Altera o texto de uma resposta existente | admin |
| DELETE | /api/v1/admin/reviews/{id}/vendor-reply | Remove a resposta do seller | admin |
| POST | /api/v1/admin/reviews/summaries/regenerate | Refaz o resumo por IA das avaliações de um produto | admin |
Erros comuns
- Esperar 404 ao aprovar, rejeitar ou apagar uma avaliação inexistente: a resposta é 500 com
review not foundemdetail. - Mandar mais de 200 ids na ação em lote: recusado com 400.
- Ler
affectedcomo "tudo certo": ids inexistentes são ignorados, compare comrequested. - Responder uma avaliação de um produto sem seller: recusado com 400.
- Apagar uma avaliação individual esperando que a média do produto se ajuste: use a ação em lote ou confira o produto.
- Contar com o resumo novo depois de
regenerate: com menos de 5 avaliações aprovadas nada é gerado.