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

GETListar avaliações

Devolve as avaliações aprovadas de um produto, com média, paginação e ordenação.

Use para montar a seção "Avaliações dos clientes" da página do produto. A lista traz só avaliações aprovadas de produtos ativos; avaliações pendentes ou rejeitadas nunca aparecem, e a loja pode esconder as de nota abaixo de um mínimo configurado. Se o lojista respondeu uma avaliação, a resposta vem em vendor_reply.

A resposta pode ser guardada em cache por até 5 minutos. O módulo de avaliações precisa estar ligado na loja.

GET/api/v1/storefront/products/{id}/reviewsPública

Lista as avaliações aprovadas de um produto

Parâmetros de caminho

idstringobrigatório

UUID ou slug do produto.

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

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

sort_bystringpadrão: recent

recentcreated_athighestratinghelpfulhelpful_count

Ordenação, sempre do maior para o menor: mais recentes, melhor nota ou mais úteis. Valor desconhecido vale recent.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/products/5e833a7f-1a77-402c-835a-32594350d7a7/reviews?page=1&per_page=20&sort_by=helpful"

Resposta

200Avaliações retornadas

json

{
  "reviews": [
    {
      "id": "3f8a2d10-6a54-4a0e-9c0d-5f1d7a2b9e44",
      "product_id": "5e833a7f-1a77-402c-835a-32594350d7a7",
      "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
      "rating": 5,
      "title": "Chegou rápido",
      "body": "Caneca bonita e bem embalada.",
      "status": "A",
      "helpful_count": 3,
      "created_at": "2026-10-02T14:20:11Z",
      "images": [],
      "user_name": "Maria S.",
      "vendor_reply": {"vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36", "vendor_name": "Loja Seller Teste", "reply_text": "Obrigado pela avaliação!", "replied_at": "2026-10-03T09:00:00Z"}
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1,
  "avg_rating": 5
}

Produto sem avaliações (resposta real da loja de teste):

200Sem avaliações

json

{"reviews":null,"total":0,"page":1,"per_page":20,"total_pages":0,"avg_rating":0}

Campos da resposta

reviewsarray

Avaliações da página. Pode vir null em vez de [] quando não há nenhuma.

reviews[].iduuid

Id da avaliação.

reviews[].product_iduuid

Id do produto.

reviews[].user_iduuid

Id do cliente autor, quando há.

reviews[].ratinginteger

Nota de 1 a 5.

reviews[].titlestring

Título. Ausente quando não informado.

reviews[].bodystring

Texto da avaliação. Ausente quando não informado.

reviews[].prosstring

Pontos positivos informados pelo autor. Ausente quando vazio.

reviews[].consstring

Pontos negativos informados pelo autor. Ausente quando vazio.

reviews[].imagesarray

Fotos anexadas: url, thumbnail_url e position.

reviews[].statusstring

Letra do estado. Na vitrine é sempre A (aprovada).

reviews[].helpful_countinteger

Quantas pessoas marcaram a avaliação como útil.

reviews[].created_atstring

Data da avaliação, RFC 3339 em UTC.

reviews[].user_namestring

Nome de exibição do autor.

reviews[].vendor_replyobject

Resposta pública do lojista: vendor_id, vendor_name, reply_text e replied_at. Ausente sem resposta.

totalinteger

Total de avaliações que atendem ao filtro, em todas as páginas.

pageinteger

Página devolvida.

per_pageinteger

Itens por página usados.

total_pagesinteger

Total de páginas.

avg_ratingnumber

Média das avaliações aprovadas.

Erros

Status	Quando	Corpo de exemplo
403	O módulo de avaliações está desligado na loja.	`{"error":"module_disabled","module":"product-reviews"}`
401	A loja exige login para navegar.	`{"error":"shopping_requires_login","message":"this storefront requires login to browse"}`

Produto inexistente, desativado ou oculto devolve 200 com lista vazia, não 404.

Veja também

GETListar avaliações

Devolve as avaliações aprovadas de um produto, com média, paginação e ordenação.

A resposta pode ser guardada em cache por até 5 minutos. O módulo de avaliações precisa estar ligado na loja.

GET/api/v1/storefront/products/{id}/reviewsPública

Lista as avaliações aprovadas de um produto

Parâmetros de caminho

idstringobrigatório

UUID ou slug do produto.

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

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

sort_bystringpadrão: recent

recentcreated_athighestratinghelpfulhelpful_count

Ordenação, sempre do maior para o menor: mais recentes, melhor nota ou mais úteis. Valor desconhecido vale recent.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/products/5e833a7f-1a77-402c-835a-32594350d7a7/reviews?page=1&per_page=20&sort_by=helpful"

Resposta

200Avaliações retornadas

json

{
  "reviews": [
    {
      "id": "3f8a2d10-6a54-4a0e-9c0d-5f1d7a2b9e44",
      "product_id": "5e833a7f-1a77-402c-835a-32594350d7a7",
      "user_id": "f12f30a9-cbec-40ba-98f1-b7fa8f2e8e10",
      "rating": 5,
      "title": "Chegou rápido",
      "body": "Caneca bonita e bem embalada.",
      "status": "A",
      "helpful_count": 3,
      "created_at": "2026-10-02T14:20:11Z",
      "images": [],
      "user_name": "Maria S.",
      "vendor_reply": {"vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36", "vendor_name": "Loja Seller Teste", "reply_text": "Obrigado pela avaliação!", "replied_at": "2026-10-03T09:00:00Z"}
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1,
  "avg_rating": 5
}

Produto sem avaliações (resposta real da loja de teste):

200Sem avaliações

json

{"reviews":null,"total":0,"page":1,"per_page":20,"total_pages":0,"avg_rating":0}

Campos da resposta

reviewsarray

Avaliações da página. Pode vir null em vez de [] quando não há nenhuma.

reviews[].iduuid

Id da avaliação.

reviews[].product_iduuid

Id do produto.

reviews[].user_iduuid

Id do cliente autor, quando há.

reviews[].ratinginteger

Nota de 1 a 5.

reviews[].titlestring

Título. Ausente quando não informado.

reviews[].bodystring

Texto da avaliação. Ausente quando não informado.

reviews[].prosstring

Pontos positivos informados pelo autor. Ausente quando vazio.

reviews[].consstring

Pontos negativos informados pelo autor. Ausente quando vazio.

reviews[].imagesarray

Fotos anexadas: url, thumbnail_url e position.

reviews[].statusstring

Letra do estado. Na vitrine é sempre A (aprovada).

reviews[].helpful_countinteger

Quantas pessoas marcaram a avaliação como útil.

reviews[].created_atstring

Data da avaliação, RFC 3339 em UTC.

reviews[].user_namestring

Nome de exibição do autor.

reviews[].vendor_replyobject

Resposta pública do lojista: vendor_id, vendor_name, reply_text e replied_at. Ausente sem resposta.

totalinteger

Total de avaliações que atendem ao filtro, em todas as páginas.

pageinteger

Página devolvida.

per_pageinteger

Itens por página usados.

total_pagesinteger

Total de páginas.

avg_ratingnumber

Média das avaliações aprovadas.

Erros

Status	Quando	Corpo de exemplo
403	O módulo de avaliações está desligado na loja.	`{"error":"module_disabled","module":"product-reviews"}`
401	A loja exige login para navegar.	`{"error":"shopping_requires_login","message":"this storefront requires login to browse"}`

Produto inexistente, desativado ou oculto devolve 200 com lista vazia, não 404.