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

Listar e moderar avaliações

Lista as avaliações dos produtos do seller e aprova ou rejeita uma delas.

A lista é a fila de trabalho do seller: filtre por status, por quem já foi respondida ou por texto. Aprovar e rejeitar mudam o status e recalculam a nota média do produto.

Listar avaliações

GET/api/v1/vendor/reviewsSeller

Lista as avaliações dos produtos do seller

Mais novas primeiro. Cobre apenas os produtos do seller.

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Parâmetros de consulta

statusstring

Filtra por status: palavra (approved, pending, rejected, spam, disabled, hidden) ou a letra.

replystring

repliedunreplied

replied só as que têm resposta do seller; unreplied só as que não têm. Outro valor é ignorado.

searchstring

Texto procurado no nome do produto, nome do avaliador, título, texto e número do pedido.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Fora da faixa volta a 20.

Exemplo de requisição

bash

curl -X GET "$BASE_URL/api/v1/vendor/reviews?reply=unreplied&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Avaliações

json

{
  "reviews": [
    {
      "id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
      "product_id": "1c5e8a30-92b4-4d6f-8e21-5a7b9c0d3e44",
      "product_name": "Chinelo Verão Azul",
      "product_slug": "chinelo-verao-azul",
      "rating": 5,
      "title": "Muito confortável",
      "body": "Chegou rápido e é ótimo.",
      "status": "approved",
      "reviewer_name": "Maria Souza",
      "created_at": "2026-10-10T14:00:00Z",
      "vendor_reply": {
        "id": "5c4b3a29-1807-4f6e-9d8c-7b6a59483726",
        "review_id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
        "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
        "reply_text": "Obrigado pelo carinho, Maria!",
        "replied_at": "2026-10-11T13:00:00Z"
      },
      "order_id": "b3a1c9d2-8e47-4f10-a2b5-6d7e8f901234",
      "order_number": "PEDIDO-20261010-0004"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1,
  "vendor_replies_allowed": true
}

Campos da resposta

reviewsarray

Avaliações da página.

iduuid

Id da avaliação.

product_iduuid

Produto avaliado.

product_namestring

Nome do produto.

product_slugstring

Slug do produto.

ratinginteger

Nota de 1 a 5.

titlestring

Título. Ausente se vazio.

bodystring

Texto. Ausente se vazio.

statusstring

Status em palavra.

reviewer_namestring

Nome de exibição do avaliador; Anonymous se não houver.

created_atstring

Quando foi avaliada (RFC 3339).

vendor_replyobject

Resposta do seller: id, review_id, vendor_id, reply_text, replied_at. Ausente sem resposta.

order_iduuid

Pedido de origem. Ausente se não houver.

order_numberstring

Número do pedido. Ausente se não houver.

totalinteger

Total que atende aos filtros.

pageinteger

Página devolvida.

per_pageinteger

Itens por página efetivos.

total_pagesinteger

Total de páginas.

vendor_replies_allowedboolean

false se o administrador desligou as respostas de seller.

Aprovar avaliação

PUT/api/v1/vendor/reviews/{id}/approveSeller

Aprova uma avaliação

Muda o status para approved, recalcula a nota média do produto e emite o evento review.approved. Sem corpo. Exige o privilégio vendor_manage_reviews.

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Parâmetros de caminho

iduuidobrigatório

Id da avaliação.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/vendor/reviews/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60/approve" \
  -H "Authorization: Bearer $TOKEN"

200Avaliação aprovada

json

{
  "id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
  "product_id": "1c5e8a30-92b4-4d6f-8e21-5a7b9c0d3e44",
  "user_id": "3093f506-d6af-4c27-9ef6-c245e8e602f9",
  "rating": 5,
  "title": "Muito confortável",
  "body": "Chegou rápido e é ótimo.",
  "pros": "",
  "cons": "",
  "images": [],
  "status": "approved",
  "helpful_count": 0,
  "created_at": "2026-10-10T14:00:00Z"
}

Rejeitar avaliação

PUT/api/v1/vendor/reviews/{id}/rejectSeller

Rejeita uma avaliação

Muda o status para rejected, recalcula a nota média e emite review.rejected. Sem corpo. Exige vendor_manage_reviews.

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Parâmetros de caminho

iduuidobrigatório

Id da avaliação.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/vendor/reviews/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60/reject" \
  -H "Authorization: Bearer $TOKEN"

200Avaliação rejeitada

json

{
  "id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
  "product_id": "1c5e8a30-92b4-4d6f-8e21-5a7b9c0d3e44",
  "user_id": "3093f506-d6af-4c27-9ef6-c245e8e602f9",
  "rating": 5,
  "title": "Muito confortável",
  "body": "Chegou rápido e é ótimo.",
  "pros": "",
  "cons": "",
  "images": [],
  "status": "rejected",
  "helpful_count": 0,
  "created_at": "2026-10-10T14:00:00Z"
}

Campos da resposta

iduuid

Id da avaliação.

product_iduuid

Produto.

user_iduuid

Cliente que avaliou. Ausente em avaliações de visitante.

guest_namestring

Nome informado pelo visitante. Ausente se vazio.

guest_emailstring

E-mail do visitante. Ausente se vazio. Dado pessoal.

ratinginteger

Nota de 1 a 5.

titlestring

Título.

bodystring

Texto.

prosstring

Pontos positivos.

consstring

Pontos negativos.

imagesarray

Fotos: url, thumbnail_url, position.

statusstring

Novo status, em palavra.

helpful_countinteger

Votos "útil".

created_atstring

Criação.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador).	`{"error":"insufficient permissions"}`
403	O módulo de avaliações (`product-reviews`) está desligado nesta loja.	`{"error":"module_disabled","module":"product-reviews"}`
403	O usuário não está vinculado a um seller.	`{"error":"user is not a vendor"}`
403	A avaliação é de um produto de outro seller (ou não existe).	`{"error":"review is not on your product"}`
403	Aprovar/rejeitar com token de seller: a verificação de privilégio exige um administrador.	`{"error":"admin access required"}`
500	Avaliação inexistente em aprovar/rejeitar, ou falha de banco.	`{"error":"failed to moderate review","detail":"review not found"}`

Veja também

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

Listar e moderar avaliações

Lista as avaliações dos produtos do seller e aprova ou rejeita uma delas.

A lista é a fila de trabalho do seller: filtre por status, por quem já foi respondida ou por texto. Aprovar e rejeitar mudam o status e recalculam a nota média do produto.

Listar avaliações

GET/api/v1/vendor/reviewsSeller

Lista as avaliações dos produtos do seller

Mais novas primeiro. Cobre apenas os produtos do seller.

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Parâmetros de consulta

statusstring

Filtra por status: palavra (approved, pending, rejected, spam, disabled, hidden) ou a letra.

replystring

repliedunreplied

replied só as que têm resposta do seller; unreplied só as que não têm. Outro valor é ignorado.

searchstring

Texto procurado no nome do produto, nome do avaliador, título, texto e número do pedido.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Fora da faixa volta a 20.

Exemplo de requisição

bash

curl -X GET "$BASE_URL/api/v1/vendor/reviews?reply=unreplied&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Avaliações

json

{
  "reviews": [
    {
      "id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
      "product_id": "1c5e8a30-92b4-4d6f-8e21-5a7b9c0d3e44",
      "product_name": "Chinelo Verão Azul",
      "product_slug": "chinelo-verao-azul",
      "rating": 5,
      "title": "Muito confortável",
      "body": "Chegou rápido e é ótimo.",
      "status": "approved",
      "reviewer_name": "Maria Souza",
      "created_at": "2026-10-10T14:00:00Z",
      "vendor_reply": {
        "id": "5c4b3a29-1807-4f6e-9d8c-7b6a59483726",
        "review_id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
        "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
        "reply_text": "Obrigado pelo carinho, Maria!",
        "replied_at": "2026-10-11T13:00:00Z"
      },
      "order_id": "b3a1c9d2-8e47-4f10-a2b5-6d7e8f901234",
      "order_number": "PEDIDO-20261010-0004"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1,
  "vendor_replies_allowed": true
}

Campos da resposta

reviewsarray

Avaliações da página.

iduuid

Id da avaliação.

product_iduuid

Produto avaliado.

product_namestring

Nome do produto.

product_slugstring

Slug do produto.

ratinginteger

Nota de 1 a 5.

titlestring

Título. Ausente se vazio.

bodystring

Texto. Ausente se vazio.

statusstring

Status em palavra.

reviewer_namestring

Nome de exibição do avaliador; Anonymous se não houver.

created_atstring

Quando foi avaliada (RFC 3339).

vendor_replyobject

Resposta do seller: id, review_id, vendor_id, reply_text, replied_at. Ausente sem resposta.

order_iduuid

Pedido de origem. Ausente se não houver.

order_numberstring

Número do pedido. Ausente se não houver.

totalinteger

Total que atende aos filtros.

pageinteger

Página devolvida.

per_pageinteger

Itens por página efetivos.

total_pagesinteger

Total de páginas.

vendor_replies_allowedboolean

false se o administrador desligou as respostas de seller.

Aprovar avaliação

PUT/api/v1/vendor/reviews/{id}/approveSeller

Aprova uma avaliação

Muda o status para approved, recalcula a nota média do produto e emite o evento review.approved. Sem corpo. Exige o privilégio vendor_manage_reviews.

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Parâmetros de caminho

iduuidobrigatório

Id da avaliação.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/vendor/reviews/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60/approve" \
  -H "Authorization: Bearer $TOKEN"

200Avaliação aprovada

json

{
  "id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
  "product_id": "1c5e8a30-92b4-4d6f-8e21-5a7b9c0d3e44",
  "user_id": "3093f506-d6af-4c27-9ef6-c245e8e602f9",
  "rating": 5,
  "title": "Muito confortável",
  "body": "Chegou rápido e é ótimo.",
  "pros": "",
  "cons": "",
  "images": [],
  "status": "approved",
  "helpful_count": 0,
  "created_at": "2026-10-10T14:00:00Z"
}

Rejeitar avaliação

PUT/api/v1/vendor/reviews/{id}/rejectSeller

Rejeita uma avaliação

Muda o status para rejected, recalcula a nota média e emite review.rejected. Sem corpo. Exige vendor_manage_reviews.

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Parâmetros de caminho

iduuidobrigatório

Id da avaliação.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/vendor/reviews/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60/reject" \
  -H "Authorization: Bearer $TOKEN"

200Avaliação rejeitada

json

{
  "id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
  "product_id": "1c5e8a30-92b4-4d6f-8e21-5a7b9c0d3e44",
  "user_id": "3093f506-d6af-4c27-9ef6-c245e8e602f9",
  "rating": 5,
  "title": "Muito confortável",
  "body": "Chegou rápido e é ótimo.",
  "pros": "",
  "cons": "",
  "images": [],
  "status": "rejected",
  "helpful_count": 0,
  "created_at": "2026-10-10T14:00:00Z"
}

Campos da resposta

iduuid

Id da avaliação.

product_iduuid

Produto.

user_iduuid

Cliente que avaliou. Ausente em avaliações de visitante.

guest_namestring

Nome informado pelo visitante. Ausente se vazio.

guest_emailstring

E-mail do visitante. Ausente se vazio. Dado pessoal.

ratinginteger

Nota de 1 a 5.

titlestring

Título.

bodystring

Texto.

prosstring

Pontos positivos.

consstring

Pontos negativos.

imagesarray

Fotos: url, thumbnail_url, position.

statusstring

Novo status, em palavra.

helpful_countinteger

Votos "útil".

created_atstring

Criação.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador).	`{"error":"insufficient permissions"}`
403	O módulo de avaliações (`product-reviews`) está desligado nesta loja.	`{"error":"module_disabled","module":"product-reviews"}`
403	O usuário não está vinculado a um seller.	`{"error":"user is not a vendor"}`
403	A avaliação é de um produto de outro seller (ou não existe).	`{"error":"review is not on your product"}`
403	Aprovar/rejeitar com token de seller: a verificação de privilégio exige um administrador.	`{"error":"admin access required"}`
500	Avaliação inexistente em aprovar/rejeitar, ou falha de banco.	`{"error":"failed to moderate review","detail":"review not found"}`