⭐ 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

Criar Avaliação do Cliente ao canal de venda

📋 Descrição

Endpoint responsável por criar uma avaliação de um canal de venda (loja) feita por um cliente 🏬⭐.

Regras importantes:

• Cada cliente pode avaliar a loja apenas uma vez
• A avaliação é cadastrada inicialmente com status "inativo"
• A exibição é definida exclusivamente pelo lojista
• A nota só é contabilizada quando a avaliação estiver ativa
• Sempre que o status for alterado (ativação ou inativação), o cálculo da nota média da loja é refeito, considerando ou desconsiderando a avaliação

📝 Parâmetros

🏷️ Headers Obrigatórios

📦 Parâmetros do Corpo

💡 Exemplo de Requisição

1curl --request POST \
2  --url '{{MAIN_URL}}/review/sales-channel/' \
3  --header 'Content-Type: application/json' \
4  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
5  --data '{
6    "comment": "Ótima loja, recomendo a todos!",
7    "recommended": true,
8    "score": 5
9  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "id": 18,
5    "name": "joão",
6    "email": "joão@email.com",
7    "comment": "Essa é definitivamente uma das lojas já feitas",
8    "recommended": true,
9    "score": 5,
10    "active": false,
11    "masked": false,
12    "createdAt": "2025-06-24 20:01:15",
13    "updatedAt": "2025-06-24 20:01:15",
14    "salesChannelId": 1,
15    "customerId": 1,
16    "salesChannelDomain": "sualoja.com.br"
17  }
18}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

Busca por avaliação de cliente

📋 Descrição

Endpoint responsável por buscar e retornar a avaliação do cliente referente a um canal de venda específico 🏬⭐.

Como cada cliente pode realizar apenas uma avaliação por loja, o retorno será único, caso a avaliação já tenha sido cadastrada.

Neste cenário, não é necessário informar parâmetros adicionais na requisição.

A identificação é feita exclusivamente por meio do token de autenticação do cliente, que permite localizar diretamente a avaliação vinculada à loja atual.

📝 Parâmetros

🏷️ Headers Obrigatórios

💡 Exemplo de Requisição

1curl --request GET \
2  --url '{{MAIN_URL}}/review/sales-channel/customer' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "id": 1,
5    "name": "Maria",
6    "email": "mariabatata@email.com",
7    "comment": "Teste",
8    "recommended": true,
9    "score": 5,
10    "active": false,
11    "masked": false,
12    "createdAt": "2025-10-15 17:34:56",
13    "updatedAt": "2025-10-15 17:34:56",
14    "salesChannelId": 1,
15    "customerId": 1,
16    "salesChannelDomain": "sualoja.com.br"
17  }
18}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

Atualizar avaliação do canal de venda

📋 Descrição

Endpoint responsável por atualizar uma avaliação de um canal de venda (loja) realizada pelo cliente 📝⭐.

Permite a alteração das informações previamente cadastradas na avaliação.

Importante: o cliente não pode alterar o status da própria avaliação. A decisão sobre a exibição (ativação ou inativação) é exclusiva do lojista.

📝 Parâmetros

🏷️ Headers Obrigatórios

🔗 Parâmetros da URL

📦 Parâmetros do Corpo

💡 Exemplo de Requisição

1curl --request PUT \
2  --url '{{MAIN_URL}}/review/{reviewId}/sales-channel/' \
3  --header 'Content-Type: application/json' \
4  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
5  --data '{
6    "comment": "Ótima loja, recomendo a todos!",
7    "recommended": true,
8    "score": 5
9  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "id": 1,
5    "name": "joão",
6    "email": "joão@email.com",
7    "comment": "Ótima loja, recomendo a todos!",
8    "recommended": true,
9    "score": 5,
10    "active": false,
11    "masked": false,
12    "createdAt": "2025-10-15 17:34:56",
13    "updatedAt": "2026-01-22 20:26:54",
14    "salesChannelId": 1,
15    "customerId": 1,
16    "salesChannelDomain": "sualoja.com.br"
17  }
18}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

Excluir avaliação do canal de venda

📋 Descrição

Endpoint responsável por excluir uma avaliação de um canal de venda (loja) realizada pelo cliente 🗑️⭐.

Importante: caso a avaliação excluída estivesse ativa, a exclusão impacta diretamente na nota média da loja, pois o cálculo é refeito desconsiderando a avaliação removida, garantindo que a pontuação reflita apenas as avaliações ativas restantes.

📝 Parâmetros

🏷️ Headers Obrigatórios

🔗 Parâmetros da URL

💡 Exemplo de Requisição

1curl --request DELETE \
2  --url '{{MAIN_URL}}/review/{reviewId}/sales-channel/' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": true
4}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.