API legada/Referência completa/Registros da loja (1.0)

Avaliações

Lista, lê, cria e apaga avaliações de produto no formato de "discussão" da Venddor 1.0, para moderação e importação.

Uma avaliação é a nota (de 1 a 5) e o comentário que um cliente deixa num produto. Na 1.0 esse recurso se chamava discussão (discussions). Estas rotas servem a um sistema que modera avaliações, as importa de outra plataforma ou as exporta. São rotas de administrador e veem as avaliações de todos os produtos, em qualquer situação.

Para mostrar avaliações a clientes, as avaliações aprovadas de um produto também saem na API 4.0.

GET/api/v1.0/discussionsAdmin

Listar avaliações (API 1.0)

Da mais nova para a mais antiga. Avaliações de produtos excluídos não aparecem.

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

items_per_pageintegerpadrão: 10

Itens por página. Entre 101 e 250 a lista usa 20, não o valor pedido; use no máximo 100.

object_iduuid

Só avaliações deste produto.

statusstring

AND

A aprovada, N pendente de moderação, D recusada.

GET/api/v1.0/discussions/{id}Admin

Ler uma avaliação (API 1.0)

Parâmetros de caminho

iduuidobrigatório

Id da avaliação (thread_id).

POST/api/v1.0/discussionsAdmin

Criar uma avaliação (API 1.0)

Cria a avaliação em nome do cliente indicado e devolve o id. A criação segue as regras de avaliação da loja: por padrão só quem comprou o produto pode avaliar, cada cliente avalia um produto uma única vez e a avaliação entra aprovada ou pendente conforme a moderação da loja.

Corpo da requisição

object_iduuidobrigatório

Produto avaliado.

user_iduuidobrigatório

Cliente autor da avaliação.

rating_valueintegerpadrão: 5

Nota de 1 a 5.

messagestring

Comentário. O HTML perigoso é removido.

thread_subjectstring

Título da avaliação (texto puro).

DELETE/api/v1.0/discussions/{id}Admin

Apagar uma avaliação (API 1.0)

Apaga a avaliação de vez. Responde 204 sem corpo. Para só esconder, a moderação do painel (recusar) é o caminho; esta API não tem rota de moderação.

Parâmetros de caminho

iduuidobrigatório

Id da avaliação.

GET/api/discussionsAdmin

Listar avaliações, sem o prefixo /v1.0

Idêntica a GET /api/v1.0/discussions.

GET/api/discussions/{id}Admin

Ler uma avaliação, sem o prefixo /v1.0

Idêntica a GET /api/v1.0/discussions/{id}. O caminho aceita só o UUID.

POST/api/discussionsAdmin

Criar uma avaliação, sem o prefixo /v1.0

Idêntica a POST /api/v1.0/discussions.

DELETE/api/discussions/{id}Admin

Apagar uma avaliação, sem o prefixo /v1.0

Idêntica a DELETE /api/v1.0/discussions/{id}. O caminho aceita só o UUID.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1.0/discussions" \
  -u "$EMAIL:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "object_id": "302a9a40-f4ca-4d84-bcf3-b9c0c4b0272f",
  "user_id": "ed7a3fbc-86f7-4b56-84de-67c583efbc3f",
  "rating_value": 4,
  "thread_subject": "Bom custo-benefício",
  "message": "Chegou rápido e funciona bem."
}'

Resposta

201Avaliação criada

json

{ "thread_id": "6d1f5b1e-3a52-4ac2-9c31-1c6d5a4f0e11" }

200Lista de avaliações

json

{
  "discussions": [
    {
      "thread_id": "6d1f5b1e-3a52-4ac2-9c31-1c6d5a4f0e11",
      "object_type": "P",
      "object_id": "302a9a40-f4ca-4d84-bcf3-b9c0c4b0272f",
      "name": "Carlos L.",
      "message": "Chegou rápido e funciona bem.",
      "rating_value": 4,
      "status": "A",
      "timestamp": 1791676800
    }
  ],
  "params": { "page": 1, "items_per_page": 10, "total_items": 1 }
}

Campos da resposta

thread_iduuid

Id da avaliação.

object_typestring

P

Sempre P: avaliação de produto.

object_iduuid

Produto avaliado.

namestring

Nome de quem avaliou. Na leitura individual vem sempre vazio.

messagestring

Comentário.

rating_valueinteger

Nota de 1 a 5.

statusstring

AND

A aprovada, N pendente, D recusada. Avaliações marcadas como spam, desativadas ou escondidas no painel também saem como A.

timestampinteger

Criação em Unix timestamp (segundos, UTC).

thread_subjectstring

Título da avaliação. Só na leitura individual, quando existe.

paramsobject

Na lista: page, items_per_page e total_items.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"message":"Invalid JSON","status":400}`
400	`object_id` ausente	`{"message":"Field 'object_id' (product_id) is required","status":400}`
400	`user_id` ausente	`{"message":"Field 'user_id' is required","status":400}`
401	Sem credencial	`{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}`
403	Credencial que não é de administrador	`{"message":"Forbidden: admin scope required","status":403}`
404	Avaliação inexistente (UUID válido)	`{"message":"Discussion not found","status":404}`
500	Cliente não comprou o produto	`{"message":"only customers who purchased this product can leave a review","status":500}`
500	Cliente já avaliou o produto	`{"message":"user has already reviewed this product","status":500}`
500	Id que não é UUID	`{"message":"query review abc: ...","status":500}`
500	Apagar avaliação inexistente	`{"message":"review not found","status":500}`

Veja também

Avaliações

Lista, lê, cria e apaga avaliações de produto no formato de "discussão" da Venddor 1.0, para moderação e importação.

Para mostrar avaliações a clientes, as avaliações aprovadas de um produto também saem na API 4.0.

GET/api/v1.0/discussionsAdmin

Listar avaliações (API 1.0)

Da mais nova para a mais antiga. Avaliações de produtos excluídos não aparecem.

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

items_per_pageintegerpadrão: 10

Itens por página. Entre 101 e 250 a lista usa 20, não o valor pedido; use no máximo 100.

object_iduuid

Só avaliações deste produto.

statusstring

AND

A aprovada, N pendente de moderação, D recusada.

GET/api/v1.0/discussions/{id}Admin

Ler uma avaliação (API 1.0)

Parâmetros de caminho

iduuidobrigatório

Id da avaliação (thread_id).

POST/api/v1.0/discussionsAdmin

Criar uma avaliação (API 1.0)

Corpo da requisição

object_iduuidobrigatório

Produto avaliado.

user_iduuidobrigatório

Cliente autor da avaliação.

rating_valueintegerpadrão: 5

Nota de 1 a 5.

messagestring

Comentário. O HTML perigoso é removido.

thread_subjectstring

Título da avaliação (texto puro).

DELETE/api/v1.0/discussions/{id}Admin

Apagar uma avaliação (API 1.0)

Apaga a avaliação de vez. Responde 204 sem corpo. Para só esconder, a moderação do painel (recusar) é o caminho; esta API não tem rota de moderação.

Parâmetros de caminho

iduuidobrigatório

Id da avaliação.

GET/api/discussionsAdmin

Listar avaliações, sem o prefixo /v1.0

Idêntica a GET /api/v1.0/discussions.

GET/api/discussions/{id}Admin

Ler uma avaliação, sem o prefixo /v1.0

Idêntica a GET /api/v1.0/discussions/{id}. O caminho aceita só o UUID.

POST/api/discussionsAdmin

Criar uma avaliação, sem o prefixo /v1.0

Idêntica a POST /api/v1.0/discussions.

DELETE/api/discussions/{id}Admin

Apagar uma avaliação, sem o prefixo /v1.0

Idêntica a DELETE /api/v1.0/discussions/{id}. O caminho aceita só o UUID.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1.0/discussions" \
  -u "$EMAIL:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "object_id": "302a9a40-f4ca-4d84-bcf3-b9c0c4b0272f",
  "user_id": "ed7a3fbc-86f7-4b56-84de-67c583efbc3f",
  "rating_value": 4,
  "thread_subject": "Bom custo-benefício",
  "message": "Chegou rápido e funciona bem."
}'

Resposta

201Avaliação criada

json

{ "thread_id": "6d1f5b1e-3a52-4ac2-9c31-1c6d5a4f0e11" }

200Lista de avaliações

json

{
  "discussions": [
    {
      "thread_id": "6d1f5b1e-3a52-4ac2-9c31-1c6d5a4f0e11",
      "object_type": "P",
      "object_id": "302a9a40-f4ca-4d84-bcf3-b9c0c4b0272f",
      "name": "Carlos L.",
      "message": "Chegou rápido e funciona bem.",
      "rating_value": 4,
      "status": "A",
      "timestamp": 1791676800
    }
  ],
  "params": { "page": 1, "items_per_page": 10, "total_items": 1 }
}

Campos da resposta

thread_iduuid

Id da avaliação.

object_typestring

P

Sempre P: avaliação de produto.

object_iduuid

Produto avaliado.

namestring

Nome de quem avaliou. Na leitura individual vem sempre vazio.

messagestring

Comentário.

rating_valueinteger

Nota de 1 a 5.

statusstring

AND

A aprovada, N pendente, D recusada. Avaliações marcadas como spam, desativadas ou escondidas no painel também saem como A.

timestampinteger

Criação em Unix timestamp (segundos, UTC).

thread_subjectstring

Título da avaliação. Só na leitura individual, quando existe.

paramsobject

Na lista: page, items_per_page e total_items.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"message":"Invalid JSON","status":400}`
400	`object_id` ausente	`{"message":"Field 'object_id' (product_id) is required","status":400}`
400	`user_id` ausente	`{"message":"Field 'user_id' is required","status":400}`
401	Sem credencial	`{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}`
403	Credencial que não é de administrador	`{"message":"Forbidden: admin scope required","status":403}`
404	Avaliação inexistente (UUID válido)	`{"message":"Discussion not found","status":404}`
500	Cliente não comprou o produto	`{"message":"only customers who purchased this product can leave a review","status":500}`
500	Cliente já avaliou o produto	`{"message":"user has already reviewed this product","status":500}`
500	Id que não é UUID	`{"message":"query review abc: ...","status":500}`
500	Apagar avaliação inexistente	`{"message":"review not found","status":500}`