API atual/Referência completa/Avaliações

Moderar avaliações

Aprova, rejeita ou apaga avaliações, uma a uma ou em lote.

Aprovar avaliação

Muda a avaliação para approved. Ela passa a aparecer na página do produto e entra na média de notas do produto, que é recalculada na hora. A plataforma também emite o evento review.approved, que a loja pode usar para premiar o cliente. Não precisa de corpo.

PUT/api/v1/admin/reviews/{id}/approveAdmin

Aprova uma avaliação e a publica na vitrine

Rota ligada ao módulo product-reviews: com o módulo desligado a resposta é 403. Leitura exige manage_content ou view_content; escrita exige manage_reviews ou manage_content.

Parâmetros de caminho

iduuidobrigatório

Identificador da avaliação.

Exemplo de requisição (Aprovar)

bash

curl -X PUT "$BASE_URL/api/v1/admin/reviews/9a6b0b5e-3d3c-4d0f-b6ad-0e9c4f6f2a71/approve" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Aprovar)

200Avaliação aprovada

json

{
  "id": "9a6b0b5e-3d3c-4d0f-b6ad-0e9c4f6f2a71",
  "product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
  "rating": 5,
  "title": "Ótima",
  "body": "Tecido muito bom e chegou rápido.",
  "pros": "Caimento",
  "cons": "",
  "images": [],
  "status": "approved",
  "helpful_count": 0,
  "created_at": "2026-10-10T14:00:00Z"
}

Campos da resposta

iduuid

Avaliação.

product_iduuid

Produto.

user_iduuid

Cliente, quando registrado.

guest_namestring

Nome do visitante, quando foi anônima.

guest_emailstring

E-mail do visitante (dado pessoal).

ratinginteger

Nota, 1 a 5.

titlestring

Título.

bodystring

Texto.

prosstring

Pontos positivos.

consstring

Pontos negativos.

imagesarray

Fotos.

statusstring

Estado, em palavra.

helpful_countinteger

Votos de "útil".

created_atstring

Envio, RFC 3339.

Erros (Aprovar)

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O administrador não tem o privilégio exigido.	`{"error":"insufficient privileges","privilege_required_any":["manage_reviews","manage_content"]}`
500	Avaliação inexistente, ou `id` que não é UUID. A plataforma responde 500, não 404.	`{"error":"failed to approve review","detail":"review not found"}`

Rejeitar avaliação

Muda a avaliação para rejected: ela sai da vitrine e da média do produto, mas continua guardada (dá para aprovar depois). Não precisa de corpo. A resposta tem o mesmo formato de approve.

PUT/api/v1/admin/reviews/{id}/rejectAdmin

Rejeita uma avaliação

Rota ligada ao módulo product-reviews: com o módulo desligado a resposta é 403. Leitura exige manage_content ou view_content; escrita exige manage_reviews ou manage_content.

Parâmetros de caminho

iduuidobrigatório

Identificador da avaliação.

Exemplo de requisição (Rejeitar)

bash

curl -X PUT "$BASE_URL/api/v1/admin/reviews/9a6b0b5e-3d3c-4d0f-b6ad-0e9c4f6f2a71/reject" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Rejeitar)

200Avaliação rejeitada

json

{
  "id": "9a6b0b5e-3d3c-4d0f-b6ad-0e9c4f6f2a71",
  "product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
  "rating": 1,
  "title": "Ruim",
  "body": "...",
  "pros": "",
  "cons": "",
  "images": [],
  "status": "rejected",
  "helpful_count": 0,
  "created_at": "2026-10-10T14:00:00Z"
}

Erros (Rejeitar)

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O administrador não tem o privilégio exigido.	`{"error":"insufficient privileges","privilege_required_any":["manage_reviews","manage_content"]}`
500	Avaliação inexistente, ou `id` que não é UUID.	`{"error":"failed to reject review","detail":"review not found"}`

Apagar avaliação

Remove a avaliação de vez. Para só escondê-la, prefira reject.

DELETE/api/v1/admin/reviews/{id}Admin

Apaga uma avaliação

Rota ligada ao módulo product-reviews: com o módulo desligado a resposta é 403. Leitura exige manage_content ou view_content; escrita exige manage_reviews ou manage_content.

Parâmetros de caminho

iduuidobrigatório

Identificador da avaliação.

Exemplo de requisição (Apagar)

bash

curl -X DELETE "$BASE_URL/api/v1/admin/reviews/9a6b0b5e-3d3c-4d0f-b6ad-0e9c4f6f2a71" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Apagar)

200Avaliação apagada

json

{
  "message": "review deleted"
}

Erros (Apagar)

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O administrador não tem o privilégio exigido.	`{"error":"insufficient privileges","privilege_required_any":["manage_reviews","manage_content"]}`
500	Avaliação inexistente, ou `id` que não é UUID.	`{"error":"failed to delete review","detail":"review not found"}`

Moderar várias avaliações

Aplica a mesma ação a uma lista de avaliações numa transação só e recalcula a nota média de cada produto envolvido. A resposta mostra quantas foram pedidas e quantas realmente mudaram.

POST/api/v1/admin/reviews/bulkAdmin

Aprova, rejeita ou apaga várias avaliações de uma vez

Rota ligada ao módulo product-reviews: com o módulo desligado a resposta é 403. Leitura exige manage_content ou view_content; escrita exige manage_reviews ou manage_content.

Corpo da requisição

actionstringobrigatório

approverejectdelete

Ação a aplicar.

idsarrayobrigatório

Ids das avaliações (UUIDs), de 1 a 200.

simulateboolean

Com true, não aplica: devolve a contagem e uma amostra, mais um confirm_token. Recurso avançado de operação em lote.

confirm_tokenstring

Token devolvido pela simulação, para executar a mesma operação.

Exemplo de requisição (Ação em lote)

bash

curl -X POST "$BASE_URL/api/v1/admin/reviews/bulk" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "approve",
  "ids": [
    "9a6b0b5e-3d3c-4d0f-b6ad-0e9c4f6f2a71"
  ]
}'

Resposta (Ação em lote)

200Resultado

json

{
  "requested": 1,
  "affected": 1,
  "ids": [
    "9a6b0b5e-3d3c-4d0f-b6ad-0e9c4f6f2a71"
  ]
}

Campos da resposta

requestedinteger

Ids recebidos (sem repetição e sem vazios, conforme a ação).

affectedinteger

Avaliações realmente alteradas. Menor que requested quando algum id não existe.

idsarray

Ids processados.

Erros (Ação em lote)

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O administrador não tem o privilégio exigido.	`{"error":"insufficient privileges","privilege_required_any":["manage_reviews","manage_content"]}`
400	`ids` vazio ou com mais de 200; id que não é UUID (o valor aparece em `detail`); ação desconhecida.	`{"error":"unknown action","detail":"must be one of approve\|reject\|delete"}`
500	Falha de banco.	`{"error":"bulk action failed","detail":"..."}`

Veja também

API atual/Referência completa/Avaliações

Moderar avaliações

Aprova, rejeita ou apaga avaliações, uma a uma ou em lote.

Aprovar avaliação

PUT/api/v1/admin/reviews/{id}/approveAdmin

Aprova uma avaliação e a publica na vitrine

Rota ligada ao módulo product-reviews: com o módulo desligado a resposta é 403. Leitura exige manage_content ou view_content; escrita exige manage_reviews ou manage_content.

Parâmetros de caminho

iduuidobrigatório

Identificador da avaliação.

Exemplo de requisição (Aprovar)

bash

curl -X PUT "$BASE_URL/api/v1/admin/reviews/9a6b0b5e-3d3c-4d0f-b6ad-0e9c4f6f2a71/approve" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Aprovar)

200Avaliação aprovada

json

{
  "id": "9a6b0b5e-3d3c-4d0f-b6ad-0e9c4f6f2a71",
  "product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
  "rating": 5,
  "title": "Ótima",
  "body": "Tecido muito bom e chegou rápido.",
  "pros": "Caimento",
  "cons": "",
  "images": [],
  "status": "approved",
  "helpful_count": 0,
  "created_at": "2026-10-10T14:00:00Z"
}

Campos da resposta

iduuid

Avaliação.

product_iduuid

Produto.

user_iduuid

Cliente, quando registrado.

guest_namestring

Nome do visitante, quando foi anônima.

guest_emailstring

E-mail do visitante (dado pessoal).

ratinginteger

Nota, 1 a 5.

titlestring

Título.

bodystring

Texto.

prosstring

Pontos positivos.

consstring

Pontos negativos.

imagesarray

Fotos.

statusstring

Estado, em palavra.

helpful_countinteger

Votos de "útil".

created_atstring

Envio, RFC 3339.

Erros (Aprovar)

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O administrador não tem o privilégio exigido.	`{"error":"insufficient privileges","privilege_required_any":["manage_reviews","manage_content"]}`
500	Avaliação inexistente, ou `id` que não é UUID. A plataforma responde 500, não 404.	`{"error":"failed to approve review","detail":"review not found"}`

Rejeitar avaliação

Muda a avaliação para rejected: ela sai da vitrine e da média do produto, mas continua guardada (dá para aprovar depois). Não precisa de corpo. A resposta tem o mesmo formato de approve.

PUT/api/v1/admin/reviews/{id}/rejectAdmin

Rejeita uma avaliação

Rota ligada ao módulo product-reviews: com o módulo desligado a resposta é 403. Leitura exige manage_content ou view_content; escrita exige manage_reviews ou manage_content.

Parâmetros de caminho

iduuidobrigatório

Identificador da avaliação.

Exemplo de requisição (Rejeitar)

bash

curl -X PUT "$BASE_URL/api/v1/admin/reviews/9a6b0b5e-3d3c-4d0f-b6ad-0e9c4f6f2a71/reject" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Rejeitar)

200Avaliação rejeitada

json

{
  "id": "9a6b0b5e-3d3c-4d0f-b6ad-0e9c4f6f2a71",
  "product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
  "rating": 1,
  "title": "Ruim",
  "body": "...",
  "pros": "",
  "cons": "",
  "images": [],
  "status": "rejected",
  "helpful_count": 0,
  "created_at": "2026-10-10T14:00:00Z"
}

Erros (Rejeitar)

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O administrador não tem o privilégio exigido.	`{"error":"insufficient privileges","privilege_required_any":["manage_reviews","manage_content"]}`
500	Avaliação inexistente, ou `id` que não é UUID.	`{"error":"failed to reject review","detail":"review not found"}`

Apagar avaliação

Remove a avaliação de vez. Para só escondê-la, prefira reject.

DELETE/api/v1/admin/reviews/{id}Admin

Apaga uma avaliação

Rota ligada ao módulo product-reviews: com o módulo desligado a resposta é 403. Leitura exige manage_content ou view_content; escrita exige manage_reviews ou manage_content.

Parâmetros de caminho

iduuidobrigatório

Identificador da avaliação.

Exemplo de requisição (Apagar)

bash

curl -X DELETE "$BASE_URL/api/v1/admin/reviews/9a6b0b5e-3d3c-4d0f-b6ad-0e9c4f6f2a71" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Apagar)

200Avaliação apagada

json

{
  "message": "review deleted"
}

Erros (Apagar)

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O administrador não tem o privilégio exigido.	`{"error":"insufficient privileges","privilege_required_any":["manage_reviews","manage_content"]}`
500	Avaliação inexistente, ou `id` que não é UUID.	`{"error":"failed to delete review","detail":"review not found"}`

Moderar várias avaliações

Aplica a mesma ação a uma lista de avaliações numa transação só e recalcula a nota média de cada produto envolvido. A resposta mostra quantas foram pedidas e quantas realmente mudaram.

POST/api/v1/admin/reviews/bulkAdmin

Aprova, rejeita ou apaga várias avaliações de uma vez

Rota ligada ao módulo product-reviews: com o módulo desligado a resposta é 403. Leitura exige manage_content ou view_content; escrita exige manage_reviews ou manage_content.

Corpo da requisição

actionstringobrigatório

approverejectdelete

Ação a aplicar.

idsarrayobrigatório

Ids das avaliações (UUIDs), de 1 a 200.

simulateboolean

Com true, não aplica: devolve a contagem e uma amostra, mais um confirm_token. Recurso avançado de operação em lote.

confirm_tokenstring

Token devolvido pela simulação, para executar a mesma operação.

Exemplo de requisição (Ação em lote)

bash

curl -X POST "$BASE_URL/api/v1/admin/reviews/bulk" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "approve",
  "ids": [
    "9a6b0b5e-3d3c-4d0f-b6ad-0e9c4f6f2a71"
  ]
}'

Resposta (Ação em lote)

200Resultado

json

{
  "requested": 1,
  "affected": 1,
  "ids": [
    "9a6b0b5e-3d3c-4d0f-b6ad-0e9c4f6f2a71"
  ]
}

Campos da resposta

requestedinteger

Ids recebidos (sem repetição e sem vazios, conforme a ação).

affectedinteger

Avaliações realmente alteradas. Menor que requested quando algum id não existe.

idsarray

Ids processados.

Erros (Ação em lote)

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"invalid or expired token"}`
403	O administrador não tem o privilégio exigido.	`{"error":"insufficient privileges","privilege_required_any":["manage_reviews","manage_content"]}`
400	`ids` vazio ou com mais de 200; id que não é UUID (o valor aparece em `detail`); ação desconhecida.	`{"error":"unknown action","detail":"must be one of approve\|reject\|delete"}`
500	Falha de banco.	`{"error":"bulk action failed","detail":"..."}`