Skip to content

⭐ Avaliações

📋 Visão Geral

As avaliações são análises e críticas feitas por compradores sobre um produto, serviço ou ferramenta, permitindo relatar experiência, satisfação pessoal e recomendações para outros clientes.

Elas trazem transparência para a decisão de compra e fornecem ao lojista feedbacks valiosos, possibilitando melhorias e ajustes para aumentar a satisfação dos clientes.

🔄 Entidades Relacionadas

No contexto Uappi, as avaliações estão relacionadas a três tipos principais: App, Produto e Canal de Venda.

Apesar das particularidades de cada um, todos compartilham muitas características em relação às avaliações.

🧩 App — Usuário

Um App funciona como um plug-in para a loja, adicionando funcionalidades extras como login social, métodos de pagamento, cálculo de frete, envio de e-mails ou integração com redes sociais.

As avaliações de Apps permitem ao lojista analisar experiências de outros usuários, ajudando a decidir se vale a pena ativar determinada ferramenta no ecossistema da loja.

Nesse contexto, o avaliador é identificado pelo ID do usuário (userId).

🏪 Canal de Venda — Cliente

O canal de venda define como a loja é disponibilizada e acessada pelos clientes, incluindo o domínio e o contexto de operação.

As avaliações nesse contexto refletem a experiência do cliente com a loja, indicando confiabilidade e qualidade do serviço/produtos, além de fornecer feedback direto ao lojista.

O objeto retornado inclui o salesChannelId e o salesChannelDomain associados à avaliação.

📦 Produto — Cliente

Um produto pode ser físico ou digital, incluindo serviços, plataformas ou funcionalidades.

O foco principal é o valor entregue ao usuário.

As avaliações de produtos ajudam outros clientes a tomar decisões mais conscientes, enquanto permitem ao lojista entender satisfação, pontos fortes e melhorias necessárias.

O objeto retornado pode incluir o objeto resumido do produto (product) e as mídias vinculadas (medias), quando solicitados.

🗂️ Estrutura da Avaliação

Todos os tipos de avaliação compartilham um conjunto base de campos, estendido com campos específicos conforme o contexto.

📄 Campos base (todos os tipos)

  • id — identificador único da avaliação
  • name — nome do avaliador
  • email — e-mail do avaliador; omitido nas consultas públicas (publicSearch = true)
  • comment — texto descritivo com o relato da avaliação
  • recommended — indica se o avaliador recomenda o item avaliado (true / false)
  • score — nota atribuída ao item pelo avaliador
  • active — indica se a avaliação está ativa e contabilizada na média
  • masked — indica se os dados sensíveis do avaliador foram mascarados
  • createdAt — data e hora de cadastro da avaliação
  • updatedAt — data e hora da última atualização da avaliação

    • 📦 Campos adicionais — Avaliação de Produto

  • productId — ID do produto avaliado
  • customerId — ID do cliente que realizou a avaliação
  • medias — lista de mídias vinculadas à avaliação, ou null quando não solicitada (campo customizado medias)
  • product — objeto resumido do produto avaliado (SimpleProductDMC), ou null quando não solicitado (campo customizado products)

    • 🖼️ Estrutura de Mídia da Avaliação (medias)

    Cada item da lista de mídias contém:

  • reviewId — ID da avaliação à qual a mídia está vinculada
  • mediaId — ID da mídia
  • image — URL da imagem vinculada à avaliação
  • createdAt — data e hora de cadastro da mídia

    • 🛍️ Estrutura do Produto Resumido (product)

    Quando o campo product é retornado, ele contém:

  • productId — ID do produto
  • brandId — ID da marca do produto, ou null quando não disponível
  • brandName — nome da marca, ou null quando não disponível
  • mainCategoryId — ID da categoria principal, ou null quando não disponível
  • mainCategoryName — nome da categoria principal, ou null quando não disponível
  • type — tipo do produto
  • sku — SKU do produto
  • name — nome do produto
  • active — indica se o produto está ativo
  • url — URL amigável do produto na loja
  • comparisonPrice — preço de comparação do produto
  • stock — estoque disponível, ou null quando não disponível
  • medias — lista de mídias do produto
  • combination — lista de combinações do produto
  • currentAttributes — lista de atributos atuais do produto
  • restriction — restrição de acesso ao produto, ou null quando não aplicável

    • 🏪 Campos adicionais — Avaliação de Canal de Venda

  • salesChannelId — ID do canal de venda associado à avaliação
  • customerId — ID do cliente que realizou a avaliação
  • salesChannelDomain — domínio do canal de venda

    • 🧩 Campos adicionais — Avaliação de App

  • appId — ID do App avaliado
  • userId — ID do usuário que realizou a avaliação

    • 📌 Regras Gerais

  • Uma avaliação não pode ser feita mais de uma vez por item (App, produto ou canal de venda)
  • Toda avaliação feita por um cliente é cadastrada inicialmente como inativa; a ativação é responsabilidade do lojista (no caso de Apps, apenas o Admin Sources)
  • Qualquer ativação ou desativação de avaliação recalcula a nota média do item, considerando ou desconsiderando a avaliação atual

Listagem de Avaliações de Produto

GET /review/product

Retorna lista paginada de avaliações públicas de produtos

Descrição

Endpoint responsável por retornar uma lista paginada de todas as avaliações de produtos ⭐.

Esta rota é pública, mas realiza uma busca criteriosa, garantindo que apenas avaliações ativas sejam retornadas.

Permite aos clientes consultar experiências de outros usuários e tomar decisões de compra mais informadas.

Parâmetros de Query

Campos Disponíveis (fields)

Especifique apenas os campos necessários para otimizar a performance:

CampoDescrição
productsInformações resumidas do produto avaliado
mediasRetorna url das imagens do item avaliado

Campos de Condição Disponíveis

CampoTipoDescrição
productIdintegerFiltra avaliações por id do produto
namestringFiltra avaliações pelo nome
emailstringFiltra avaliações pelo e-mail de quem avaliou
recommendedbooleanFiltra avaliações por clientes que recomendam ou não o produto (true/false)
scoreintFiltra avaliações pela nota (de 0 a 5)
createdAtstringFiltra avaliações baseado na data de cadastro

Campos de Ordenação Disponíveis

CampoDescrição
idOrdena a listagem pelo id da avaliação
productIdOrdena a listagem pelo id do produto
customerIdOrdena a listagem pelo id do cliente/avaliador
nameOrdena a listagem pelo nome da avaliação
scoreOrdena a listagem pela nota da avaliação
createdAtOrdena a listagem pela data em que a avaliação foi criada
updatedAtOrdena a listagem pela data em que a avaliação foi atualizada

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/review/product \
3  --data '{
4    "fields": [
5      "products",
6      "medias"
7    ]
8  }'

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "registers": [
5      {
6        "id": 201,
7        "productId": 1234,
8        "customerId": 567,
9        "name": "Maria Silva",
10        "email":"",
11        "score": 5,
12        "comment": "Superou todas as minhas expectativas. Qualidade impecável e entrega rápida.",
13        "recommended": true,
14        "active": true,
15        "masked":true,
16        "medias": [
17          {
18            "reviewId": 1001,
19            "mediaId": 1,
20            "image": "https://cdn.sua-loja.com.br/reviews/review-photo-1.jpg",
21            "createdAt": "2024-09-15 10:15:00"
22          }
23        ],
24        "product": {
25					"productId": 1234,
26					"brandId": 1,
27					"brandName": "TechBrand",
28					"mainCategoryId": 123,
29					"mainCategoryName": "Smartphones",
30					"type": "product",
31					"sku": "SMPH001",
32					"name": "Smartphone XYZ Pro 128GB",
33					"active": true,
34					"url": "/smartphone-xyz-pro-128gb",
35					"comparisonPrice": 1499.90,
36					"stock": 15,
37					"medias": [
38						{
39							"id": 1234,
40							"type": "image",
41							"title": "Imagem Principal",
42							"alternativeText": "Smartphone XYZ Pro vista frontal",
43              "file": "https://cdn.loja.com.br/products/smartphone-xyz-pro-01.jpg",
44              "originalFile": "https://cdn.loja.com.br/products/smartphone-xyz-pro-01-original.jpg",
45							"size": 245680,
46							"originalSize": 1567890,
47							"width": 800,
48							"height": 800,
49              "url": "https://cdn.loja.com.br/products/smartphone-xyz-pro-01.jpg"
50						}
51					],
52					"combination": [],
53					"currentAttributes": []
54				},
55        "createdAt": "2024-09-15 14:30:00",
56        "updatedAt": "2024-09-15 14:30:00"
57      },
58      {
59        "id": 202,
60        "productId": 1234,
61        "customerId": 890,
62        "name": "João Oliveira",
63        "score": 4,
64        "email": "",
65        "comment": "Produto de boa qualidade, atende bem às expectativas. Apenas a bateria poderia durar mais.",
66        "recommended": true,
67        "active": true,
68        "masked":true,
69        "medias": [
70          {
71            "reviewId": 1001,
72            "mediaId": 1,
73            "image": "https://cdn.sua-loja.com.br/reviews/review-photo-1.jpg",
74            "createdAt": "2024-09-15 10:15:00"
75          }
76        ],
77        "product": {
78					"productId": 1234,
79					"brandId": 1,
80					"brandName": "TechBrand",
81					"mainCategoryId": 123,
82					"mainCategoryName": "Smartphones",
83					"type": "product",
84					"sku": "SMPH001",
85					"name": "Smartphone XYZ Pro 128GB",
86					"active": true,
87					"url": "/smartphone-xyz-pro-128gb",
88					"comparisonPrice": 1499.90,
89					"stock": 15,
90					"medias": [
91						{
92							"id": 1234,
93							"type": "image",
94							"title": "Imagem Principal",
95							"alternativeText": "Smartphone XYZ Pro vista frontal",
96              "file": "https://cdn.loja.com.br/products/smartphone-xyz-pro-01.jpg",
97              "originalFile": "https://cdn.loja.com.br/products/smartphone-xyz-pro-01-original.jpg",
98							"size": 245680,
99							"originalSize": 1567890,
100							"width": 800,
101							"height": 800,
102              "url": "https://cdn.loja.com.br/products/smartphone-xyz-pro-01.jpg"
103						}
104					],
105					"combination": [],
106					"currentAttributes": []
107				},
108        "createdAt": "2024-09-10 10:15:00",
109        "updatedAt": "2024-09-10 10:15:00"
110      }
111    ],
112    "pagination": {
113      "limit": 10,
114      "offset": 0,
115      "pages": 5,
116      "registers": 48
117    }
118  }
119}

Listagem de Avaliações do Canal de Venda

GET /review/sales-channel

Retorna lista paginada de avaliações públicas do canal de venda (loja)

Descrição

Endpoint responsável por retornar uma lista paginada de todas as avaliações sobre a loja 🏬.

Esta rota é pública, mas aplica uma busca criteriosa, retornando apenas avaliações ativas e relacionadas à loja atual.

Permite que novos clientes consultem a experiência de outros usuários, contribuindo para a confiança e transparência da loja.

Parâmetros de Query

Campos de Condição Disponíveis

CampoTipoDescrição
namestringFiltra avaliações pelo nome
emailstringFiltra avaliações pelo e-mail de quem avaliou
recommendedbooleanFiltra avaliações por clientes que recomendam ou não a loja (true/false)
scoreintFiltra avaliações pela nota (de 0 a 5)
createdAtstringFiltra avaliações baseado na data de cadastro

Campos de Ordenação Disponíveis

CampoDescrição
idOrdena a listagem pelo id da avaliação
customerIdOrdena a listagem pelo id do cliente/avaliador
nameOrdena a listagem pelo nome da avaliação
scoreOrdena a listagem pela nota da avaliação
createdAtOrdena a listagem pela data em que a avaliação foi criada
updatedAtOrdena a listagem pela data em que a avaliação foi atualizada

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/review/sales-channel \

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "registers": [
5      {
6        "id": 301,
7        "salesChannelId": 1,
8        "customerId": 567,
9        "name": "Maria Silva",
10        "email":"",
11        "score": 5,
12        "comment": "Loja confiável, produtos de qualidade e entrega rápida. Recomendo!",
13        "recommended": true,
14        "masked": true,
15        "active": true,
16        "salesChannelDomain":"sualoja.com.br",
17        "createdAt": "2024-09-20T16:45:00Z",
18        "updatedAt": "2024-09-20T16:45:00Z"
19      },
20      {
21        "id": 302,
22        "salesChannelId": 1,
23        "customerId": 890,
24        "name": "João Oliveira",
25        "email":"",
26        "score": 4,
27        "comment": "Boa loja, produtos chegaram conforme descrição. Apenas o prazo de entrega foi um pouco maior que o esperado.",
28        "recommended": true,
29        "masked":true,
30        "active": true,
31        "salesChannelDomain":"loja.com.br",
32        "createdAt": "2024-09-18T11:20:00Z",
33        "updatedAt": "2024-09-18T11:20:00Z"
34      }
35    ],
36    "pagination": {
37      "limit": 10,
38      "offset": 0,
39      "pages": 8,
40      "registers": 78
41    },
42  }
43}

Uappi é a melhor opção para o crescimento da sua loja!

Institucional

;