API atual/Referência completa/Mini-loja WhatsApp: catálogo

Avaliações de produtos

Lê as avaliações de um produto e avalia, um a um, os produtos de um pedido entregue; as rotas antigas de avaliação direta foram aposentadas.

As avaliações da mini-loja são as mesmas do site: só aparecem as aprovadas, respeitando a nota mínima que a loja definiu. Para escrever uma avaliação, a regra é uma só: o cliente avalia um produto de cada vez, a partir de um pedido já entregue. Isso evita avaliações de quem nunca comprou.

Por isso há cinco rotas, mas duas delas existem só para responder que foram aposentadas (410 Gone) e levar quem ainda as usa para o caminho certo.

Ler as avaliações de um produto

GET/api/v1/storefront/wa-coex/product/{token}/{productID}/reviewsPública

Avaliações aprovadas do produto, resumo ou folha completa

Sem parâmetros, devolve o resumo da ficha: média, total e as 3 avaliações mais recentes. Com all=1, devolve a folha de avaliações: até 20 avaliações, a distribuição por estrelas e se este cliente pode avaliar.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

productIDuuidobrigatório

Id do produto.

Parâmetros de consulta

allstring

1

Com 1, devolve a folha completa. Qualquer outro valor devolve o resumo.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/wa-coex/product/$TOKEN/$PRODUCT_ID/reviews?all=1"

Resposta

200Folha de avaliações

json

{
  "reviews": {
    "avg_rating": 4.5,
    "total": 12,
    "latest": [
      { "rating": 5, "title": "Chegou rápido", "body": "Produto igual ao anunciado.", "author": "Maria S.", "created_at": "2026-10-02T14:21:00Z", "store_reply": "Obrigado pela compra!" }
    ],
    "distribution": [0, 1, 1, 3, 7]
  },
  "logged_in": true,
  "can_submit": true
}

Campos da resposta

reviewsobject

Bloco de avaliações. null quando o recurso está desligado, o produto não é visível neste canal ou não há avaliações.

avg_ratingnumber

Nota média, de 1 a 5.

totalinteger

Quantidade de avaliações aprovadas.

latestarray

Avaliações mais recentes: rating (1 a 5), title, body, author, created_at (RFC 3339) e store_reply (resposta da loja).

distributionarray

Só com all=1. Cinco números: avaliações com 1, 2, 3, 4 e 5 estrelas, nesta ordem.

logged_inboolean

Só com all=1. O token tem uma conta identificada.

can_submitboolean

Só com all=1. A loja aceita avaliações. A permissão de verdade é por pedido entregue.

Erros

Status	Quando	Corpo
403	O recurso de avaliações está desligado na loja.	`{"error":"feature_not_available","feature":"reviews","detail":"switched off for this store"}`
403	Porta de entrada fechada, ou login exigido.	`{"error":"entry_required"}` ou `{"error":"account_required","message":"..."}`

Rotas aposentadas de avaliação direta

POST/api/v1/storefront/wa-coex/product/{token}/{productID}/reviewsPública

Aposentada: avaliação direta do produto

Antes, o cliente avaliava um produto direto da ficha. Hoje isso é recusado: responde sempre 410, sem olhar o corpo. Avalie pelo pedido entregue (rotas abaixo).

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

productIDuuidobrigatório

Id do produto.

POST/api/v1/storefront/wa-coex/order/{token}/{orderID}/reviewPública

Aposentada: avaliação do pedido inteiro

Também aposentada, com a mesma resposta. A avaliação é por produto do pedido, não pelo pedido todo.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

orderIDuuidobrigatório

Id do pedido.

410Aposentada

json

{ "error": "reviews_only_from_order", "detail": "review products from your delivered order" }

Listar o que o pedido permite avaliar

GET/api/v1/storefront/wa-coex/order/{token}/{orderID}/reviewablePública

Produtos do pedido entregue e se cada um ainda pode ser avaliado

Só funciona para um pedido entregue do cliente identificado no token. Num pedido que ainda não foi entregue, a lista vem vazia.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

orderIDuuidobrigatório

Id do pedido.

200Itens avaliáveis

json

{
  "items": [
    { "product_id": "68836206-cb76-4814-9811-335f02e4e956", "already_reviewed": false, "can_review": true }
  ]
}

Campos da resposta

itemsarray

Um item por produto do pedido.

product_iduuid

Produto do pedido.

already_reviewedboolean

O cliente já avaliou este produto.

can_reviewboolean

Pode avaliar agora.

Erros

Status	Quando	Corpo
401	O token não tem conta identificada.	`{"error":"login_required"}`
403	Recurso de avaliações ou módulo desligado.	`{"error":"feature_not_available",...}` ou `{"error":"module_disabled","module":"product-reviews"}`
404	Pedido que não existe ou não é deste cliente.	`{"error":"order_not_found"}`
404	Avaliações desligadas nesta loja.	`{"error":"reviews_off"}`
502	Falha ao ler.	`{"error":"review_failed"}`

Avaliar um produto do pedido

POST/api/v1/storefront/wa-coex/order/{token}/{orderID}/items/{productID}/reviewPública

Avalia um produto de um pedido entregue

Grava a avaliação do produto naquele pedido. Se a loja modera avaliações, ela fica pendente (pending: true) até ser aprovada.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

orderIDuuidobrigatório

Id do pedido entregue.

productIDuuidobrigatório

Produto do pedido que está sendo avaliado.

Corpo da requisição

ratingintegerobrigatório

Nota de 1 a 5.

titlestring

Título. Passando de 120 caracteres, é cortado.

commentstring

Comentário. Passando de 2000 caracteres, é cortado.

O corpo pode ter até 16 KB.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/order/$TOKEN/$ORDER_ID/items/$PRODUCT_ID/review" \
  -H "Content-Type: application/json" \
  -d '{"rating": 5, "title": "Chegou rápido", "comment": "Produto igual ao anunciado."}'

Resposta

201Avaliação registrada

json

{ "pending": true }

Campos da resposta

pendingboolean

true quando a avaliação aguarda moderação da loja e ainda não aparece publicamente.

Erros

Status	Quando	Corpo
400	Corpo ilegível.	`{"error":"invalid_body"}`
400	`rating` fora de 1 a 5.	`{"error":"rating_required"}`
401	O token não tem conta identificada.	`{"error":"login_required"}`
403	O pedido não foi entregue ou o cliente não comprou o produto.	`{"error":"purchase_required"}`
404	Pedido não é deste cliente, ou o produto não está no pedido.	`{"error":"order_not_found"}`
409	O cliente já avaliou este produto.	`{"error":"already_reviewed"}`
409	O mesmo texto já foi enviado em outra avaliação.	`{"error":"duplicate_review"}`
502	Falha ao gravar.	`{"error":"review_failed"}`

Veja também

API atual/Referência completa/Mini-loja WhatsApp: catálogo

Avaliações de produtos

Lê as avaliações de um produto e avalia, um a um, os produtos de um pedido entregue; as rotas antigas de avaliação direta foram aposentadas.

Por isso há cinco rotas, mas duas delas existem só para responder que foram aposentadas (410 Gone) e levar quem ainda as usa para o caminho certo.

Ler as avaliações de um produto

GET/api/v1/storefront/wa-coex/product/{token}/{productID}/reviewsPública

Avaliações aprovadas do produto, resumo ou folha completa

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

productIDuuidobrigatório

Id do produto.

Parâmetros de consulta

allstring

1

Com 1, devolve a folha completa. Qualquer outro valor devolve o resumo.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/wa-coex/product/$TOKEN/$PRODUCT_ID/reviews?all=1"

Resposta

200Folha de avaliações

json

{
  "reviews": {
    "avg_rating": 4.5,
    "total": 12,
    "latest": [
      { "rating": 5, "title": "Chegou rápido", "body": "Produto igual ao anunciado.", "author": "Maria S.", "created_at": "2026-10-02T14:21:00Z", "store_reply": "Obrigado pela compra!" }
    ],
    "distribution": [0, 1, 1, 3, 7]
  },
  "logged_in": true,
  "can_submit": true
}

Campos da resposta

reviewsobject

Bloco de avaliações. null quando o recurso está desligado, o produto não é visível neste canal ou não há avaliações.

avg_ratingnumber

Nota média, de 1 a 5.

totalinteger

Quantidade de avaliações aprovadas.

latestarray

Avaliações mais recentes: rating (1 a 5), title, body, author, created_at (RFC 3339) e store_reply (resposta da loja).

distributionarray

Só com all=1. Cinco números: avaliações com 1, 2, 3, 4 e 5 estrelas, nesta ordem.

logged_inboolean

Só com all=1. O token tem uma conta identificada.

can_submitboolean

Só com all=1. A loja aceita avaliações. A permissão de verdade é por pedido entregue.

Erros

Status	Quando	Corpo
403	O recurso de avaliações está desligado na loja.	`{"error":"feature_not_available","feature":"reviews","detail":"switched off for this store"}`
403	Porta de entrada fechada, ou login exigido.	`{"error":"entry_required"}` ou `{"error":"account_required","message":"..."}`

Rotas aposentadas de avaliação direta

POST/api/v1/storefront/wa-coex/product/{token}/{productID}/reviewsPública

Aposentada: avaliação direta do produto

Antes, o cliente avaliava um produto direto da ficha. Hoje isso é recusado: responde sempre 410, sem olhar o corpo. Avalie pelo pedido entregue (rotas abaixo).

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

productIDuuidobrigatório

Id do produto.

POST/api/v1/storefront/wa-coex/order/{token}/{orderID}/reviewPública

Aposentada: avaliação do pedido inteiro

Também aposentada, com a mesma resposta. A avaliação é por produto do pedido, não pelo pedido todo.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

orderIDuuidobrigatório

Id do pedido.

410Aposentada

json

{ "error": "reviews_only_from_order", "detail": "review products from your delivered order" }

Listar o que o pedido permite avaliar

GET/api/v1/storefront/wa-coex/order/{token}/{orderID}/reviewablePública

Produtos do pedido entregue e se cada um ainda pode ser avaliado

Só funciona para um pedido entregue do cliente identificado no token. Num pedido que ainda não foi entregue, a lista vem vazia.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

orderIDuuidobrigatório

Id do pedido.

200Itens avaliáveis

json

{
  "items": [
    { "product_id": "68836206-cb76-4814-9811-335f02e4e956", "already_reviewed": false, "can_review": true }
  ]
}

Campos da resposta

itemsarray

Um item por produto do pedido.

product_iduuid

Produto do pedido.

already_reviewedboolean

O cliente já avaliou este produto.

can_reviewboolean

Pode avaliar agora.

Erros

Status	Quando	Corpo
401	O token não tem conta identificada.	`{"error":"login_required"}`
403	Recurso de avaliações ou módulo desligado.	`{"error":"feature_not_available",...}` ou `{"error":"module_disabled","module":"product-reviews"}`
404	Pedido que não existe ou não é deste cliente.	`{"error":"order_not_found"}`
404	Avaliações desligadas nesta loja.	`{"error":"reviews_off"}`
502	Falha ao ler.	`{"error":"review_failed"}`

Avaliar um produto do pedido

POST/api/v1/storefront/wa-coex/order/{token}/{orderID}/items/{productID}/reviewPública

Avalia um produto de um pedido entregue

Grava a avaliação do produto naquele pedido. Se a loja modera avaliações, ela fica pendente (pending: true) até ser aprovada.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

orderIDuuidobrigatório

Id do pedido entregue.

productIDuuidobrigatório

Produto do pedido que está sendo avaliado.

Corpo da requisição

ratingintegerobrigatório

Nota de 1 a 5.

titlestring

Título. Passando de 120 caracteres, é cortado.

commentstring

Comentário. Passando de 2000 caracteres, é cortado.

O corpo pode ter até 16 KB.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/order/$TOKEN/$ORDER_ID/items/$PRODUCT_ID/review" \
  -H "Content-Type: application/json" \
  -d '{"rating": 5, "title": "Chegou rápido", "comment": "Produto igual ao anunciado."}'

Resposta

201Avaliação registrada

json

{ "pending": true }

Campos da resposta

pendingboolean

true quando a avaliação aguarda moderação da loja e ainda não aparece publicamente.

Erros

Status	Quando	Corpo
400	Corpo ilegível.	`{"error":"invalid_body"}`
400	`rating` fora de 1 a 5.	`{"error":"rating_required"}`
401	O token não tem conta identificada.	`{"error":"login_required"}`
403	O pedido não foi entregue ou o cliente não comprou o produto.	`{"error":"purchase_required"}`
404	Pedido não é deste cliente, ou o produto não está no pedido.	`{"error":"order_not_found"}`
409	O cliente já avaliou este produto.	`{"error":"already_reviewed"}`
409	O mesmo texto já foi enviado em outra avaliação.	`{"error":"duplicate_review"}`
502	Falha ao gravar.	`{"error":"review_failed"}`