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

GETListar avaliações

Lista as avaliações de produtos com filtros por estado, nota, produto, seller, data e texto.

Devolve as avaliações que os clientes deixaram nos produtos, de todos os estados, com filtros e ordenação. Avaliações de produtos que foram apagados não aparecem. A resposta traz também a nota média do conjunto filtrado.

GET/api/v1/admin/reviewsAdmin

Lista as avaliações de produtos para moderaçã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 consulta

statusstring

approvedpendingrejectedspamdisabledhidden

Estado. Aceita a palavra ou a letra (A, P, R, S, D, H).

product_iduuid

Só avaliações desse produto.

user_iduuid

Só avaliações desse cliente.

vendor_iduuid

Só avaliações de produtos desse seller.

ratinginteger

Nota exata, de 1 a 5. Valor fora disso é ignorado.

rating_mininteger

Nota mínima, 1 a 5.

rating_maxinteger

Nota máxima, 1 a 5.

date_fromstring

Enviadas a partir desta data (YYYY-MM-DD, início do dia UTC, ou RFC 3339).

date_tostring

Enviadas até esta data (YYYY-MM-DD inclui o dia inteiro, ou RFC 3339).

searchstring

Texto no nome do produto, no nome do avaliador, no título ou no texto.

sort_bystringpadrão: created_at

created_atratinghelpful_count

Campo de ordenação.

sort_orderstringpadrão: desc

ascdesc

Direção.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, 1 a 100; fora disso vale 20.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/reviews?status=pending&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Avaliações

json

{
  "reviews": [
    {
      "id": "9a6b0b5e-3d3c-4d0f-b6ad-0e9c4f6f2a71",
      "product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
      "product_name": "Camiseta Azul",
      "product_slug": "camiseta-azul",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "rating": 5,
      "title": "Ótima",
      "body": "Tecido muito bom e chegou rápido.",
      "pros": "Caimento",
      "cons": "",
      "images": [],
      "status": "pending",
      "helpful_count": 0,
      "created_at": "2026-10-10T14:00:00Z",
      "reviewer_name": "Maria Souza",
      "user_name": "Maria Souza",
      "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
      "order_number": "PEDIDO-20261011-0002"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1,
  "avg_rating": 5
}

Campos da resposta

reviewsarray

Avaliações da página.

iduuid

Identificador da avaliação.

product_iduuid

Produto avaliado.

product_namestring

Nome do produto, para a tabela de moderação.

product_slugstring

Slug do produto.

vendor_iduuid

Seller dono do produto.

ratinginteger

Nota de 1 a 5 estrelas.

titlestring

Título da avaliação.

bodystring

Texto da avaliação.

prosstring

Pontos positivos.

consstring

Pontos negativos.

imagesarray

Fotos enviadas pelo cliente.

statusstring

approved, pending, rejected, spam, disabled ou hidden.

helpful_countinteger

Votos de "útil".

reviewer_namestring

Nome de quem avaliou (visitante usa o nome informado ou "Anonymous").

user_namestring

Igual a reviewer_name, mantido por compatibilidade.

is_guestboolean

true quando a avaliação veio de um visitante sem cadastro. Ausente caso contrário.

vendor_replyobject

Resposta do seller, quando existe: id, review_id, vendor_id, vendor_name, reply_text, replied_at.

videoobject

Vídeo do cliente (url, poster_url, duration_seconds), só em avaliação aprovada.

order_iduuid

Pedido que originou a avaliação, quando há.

order_numberstring

Número do pedido.

created_atstring

Envio, RFC 3339.

totalinteger

Total que atende ao filtro.

pageinteger

Página devolvida.

per_pageinteger

Itens por página usados.

total_pagesinteger

Total de páginas.

avg_ratingnumber

Nota média do conjunto filtrado (0 quando vazio).

Erros

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_content","view_content"]}`
500	Falha de banco.	`{"error":"failed to list reviews","detail":"..."}`

Veja também

GETListar avaliações

Lista as avaliações de produtos com filtros por estado, nota, produto, seller, data e texto.

GET/api/v1/admin/reviewsAdmin

Lista as avaliações de produtos para moderaçã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 consulta

statusstring

approvedpendingrejectedspamdisabledhidden

Estado. Aceita a palavra ou a letra (A, P, R, S, D, H).

product_iduuid

Só avaliações desse produto.

user_iduuid

Só avaliações desse cliente.

vendor_iduuid

Só avaliações de produtos desse seller.

ratinginteger

Nota exata, de 1 a 5. Valor fora disso é ignorado.

rating_mininteger

Nota mínima, 1 a 5.

rating_maxinteger

Nota máxima, 1 a 5.

date_fromstring

Enviadas a partir desta data (YYYY-MM-DD, início do dia UTC, ou RFC 3339).

date_tostring

Enviadas até esta data (YYYY-MM-DD inclui o dia inteiro, ou RFC 3339).

searchstring

Texto no nome do produto, no nome do avaliador, no título ou no texto.

sort_bystringpadrão: created_at

created_atratinghelpful_count

Campo de ordenação.

sort_orderstringpadrão: desc

ascdesc

Direção.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, 1 a 100; fora disso vale 20.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/reviews?status=pending&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Avaliações

json

{
  "reviews": [
    {
      "id": "9a6b0b5e-3d3c-4d0f-b6ad-0e9c4f6f2a71",
      "product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
      "product_name": "Camiseta Azul",
      "product_slug": "camiseta-azul",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "rating": 5,
      "title": "Ótima",
      "body": "Tecido muito bom e chegou rápido.",
      "pros": "Caimento",
      "cons": "",
      "images": [],
      "status": "pending",
      "helpful_count": 0,
      "created_at": "2026-10-10T14:00:00Z",
      "reviewer_name": "Maria Souza",
      "user_name": "Maria Souza",
      "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
      "order_number": "PEDIDO-20261011-0002"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1,
  "avg_rating": 5
}

Campos da resposta

reviewsarray

Avaliações da página.

iduuid

Identificador da avaliação.

product_iduuid

Produto avaliado.

product_namestring

Nome do produto, para a tabela de moderação.

product_slugstring

Slug do produto.

vendor_iduuid

Seller dono do produto.

ratinginteger

Nota de 1 a 5 estrelas.

titlestring

Título da avaliação.

bodystring

Texto da avaliação.

prosstring

Pontos positivos.

consstring

Pontos negativos.

imagesarray

Fotos enviadas pelo cliente.

statusstring

approved, pending, rejected, spam, disabled ou hidden.

helpful_countinteger

Votos de "útil".

reviewer_namestring

Nome de quem avaliou (visitante usa o nome informado ou "Anonymous").

user_namestring

Igual a reviewer_name, mantido por compatibilidade.

is_guestboolean

true quando a avaliação veio de um visitante sem cadastro. Ausente caso contrário.

vendor_replyobject

Resposta do seller, quando existe: id, review_id, vendor_id, vendor_name, reply_text, replied_at.

videoobject

Vídeo do cliente (url, poster_url, duration_seconds), só em avaliação aprovada.

order_iduuid

Pedido que originou a avaliação, quando há.

order_numberstring

Número do pedido.

created_atstring

Envio, RFC 3339.

totalinteger

Total que atende ao filtro.

pageinteger

Página devolvida.

per_pageinteger

Itens por página usados.

total_pagesinteger

Total de páginas.

avg_ratingnumber

Nota média do conjunto filtrado (0 quando vazio).

Erros

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_content","view_content"]}`
500	Falha de banco.	`{"error":"failed to list reviews","detail":"..."}`