⭐ 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 de Produto

📋 Descrição

Endpoint responsável por permitir que o cliente crie uma avaliação sobre um produto.

Alguns pontos importantes sobre o funcionamento:

• Cada produto pode ser avaliado apenas uma vez pelo mesmo cliente.
• A criação não define automaticamente o status como "ativo" — a exibição da avaliação é decisão do lojista.
• A nota da avaliação só é contabilizada quando a avaliação estiver ativa.
• Alterações de status recalculam a nota média do produto, permitindo que o lojista gerencie a avaliação geral de forma dinâmica.

Se name ou email não forem enviados no corpo da requisição, o sistema preenche automaticamente com os dados cadastrados na conta do cliente autenticado.

📝 Parâmetros

🏷️ Headers Obrigatórios

🔗 Parâmetros da URL

📦 Parâmetros do Corpo

💡 Exemplo de Requisição

1curl --request POST \
2  --url '{{MAIN_URL}}/review/product/42' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "comment": "Produto excelente, chegou antes do prazo e bem embalado!",
7    "recommended": true,
8    "score": 5
9  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "id": 101,
5    "name": "Maria Souza",
6    "email": "maria@exemplo.com",
7    "comment": "Produto excelente, chegou antes do prazo e bem embalado!",
8    "recommended": true,
9    "score": 5,
10    "active": false,
11    "masked": false,
12    "createdAt": "2026-05-26 14:30:00",
13    "updatedAt": "2026-05-26 14:30:00",
14    "productId": 42,
15    "customerId": 7,
16    "medias": null,
17    "product": null
18  }
19}

⚠️ Possíveis Erros

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

📋 Listagem de avaliações de produtos do cliente

📄 Descrição

Endpoint responsável por retornar todas as avaliações de produtos realizadas pelo cliente autenticado 📝.

Permite que o cliente visualize o histórico completo de suas avaliações, com suporte a filtros, ordenação e carregamento de dados relacionados.

O campo email é automaticamente mascarado (retornado vazio) sempre que o campo products for solicitado no body, pois nesse contexto a busca de produto segue o fluxo público.

📝 Parâmetros

🏷️ Headers Obrigatórios

📦 Campos Disponíveis (fields)

Informe apenas os campos necessários para otimizar a performance da resposta.

📊 Campos de Condição Disponíveis (condition)

🔃 Campos de Ordenação Disponíveis (order)

📐 Paginação

💡 Exemplo de Requisição

1curl --request GET \
2  --url '{{MAIN_URL}}/api/v3/review/product/customer' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "fields": ["products", "medias"],
7    "order": [
8      {"field": "createdAt", "order": "DESC"}
9    ],
10    "condition": {
11      "type": "AND",
12      "conditions": [
13        {"field": "score", "value": 5, "operator": ">="}
14      ]
15    },
16    "limit": 10,
17    "offset": 0
18  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "registers": [
5      {
6        "id": 42,
7        "name": "Maria Silva",
8        "email": "",
9        "comment": "Produto excelente! Chegou rápido e bem embalado.",
10        "recommended": true,
11        "score": 5,
12        "active": true,
13        "masked": false,
14        "createdAt": "2025-10-15 17:29:39",
15        "updatedAt": "2025-10-15 17:32:00",
16        "productId": 7,
17        "customerId": 12,
18        "medias": [],
19        "product": {
20          "productId": 7,
21          "brandId": 3,
22          "brandName": "TechBrand",
23          "mainCategoryId": 2,
24          "mainCategoryName": "Eletrônicos",
25          "type": "product",
26          "sku": "SKU-TB-7432",
27          "name": "Fone de Ouvido Bluetooth TechBrand Pro",
28          "active": true,
29          "url": "/fone-de-ouvido-bluetooth-techbrand-pro",
30          "comparisonPrice": 299.90,
31          "stock": 45,
32          "medias": [],
33          "combination": [],
34          "currentAttributes": [],
35          "restriction": null
36        }
37      }
38    ],
39    "pagination": {
40      "limit": 10,
41      "offset": 0,
42      "pages": 1,
43      "registers": 1
44    }
45  }
46}

Observações sobre a resposta:

O campo medias retorna null por padrão. Ele retorna um array (vazio ou com objetos) somente quando "medias" é incluído em fields.

O campo product retorna null por padrão. Ele retorna o objeto do produto somente quando "products" é incluído em fields.

O campo email retorna vazio ("") sempre que o campo products for solicitado — isso ocorre porque, nesse contexto, o processo de busca é executado em modo público.

⚠️ 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 de Produto

📋 Descrição

Endpoint responsável por atualizar uma avaliação de produto previamente cadastrada pelo cliente autenticado 📝.

Permite alterar os dados da avaliação, como o comentário, a nota e a recomendação.

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

Se name ou email não forem enviados no corpo da requisição, o sistema preenche automaticamente com os dados cadastrados na conta do cliente autenticado.

📝 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/12/product/42/' \
3  --header 'Content-Type: application/json' \
4  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
5  --data '{
6    "comment": "Produto muito bom, entrega rápida e embalagem impecável!",
7    "recommended": true,
8    "score": 5
9  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "id": 12,
5    "name": "Maria Souza",
6    "email": "maria@exemplo.com",
7    "comment": "Produto muito bom, entrega rápida e embalagem impecável!",
8    "recommended": true,
9    "score": 5,
10    "active": false,
11    "masked": false,
12    "createdAt": "2025-10-15 17:29:39",
13    "updatedAt": "2026-05-26 12:55:36",
14    "productId": 42,
15    "customerId": 7,
16    "medias": null,
17    "product": null
18  }
19}

⚠️ 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 de Produto

📋 Descrição

Endpoint responsável por excluir permanentemente uma avaliação de produto realizada pelo cliente autenticado. 🗑️

A exclusão só é permitida para avaliações pertencentes ao próprio cliente do token informado. Avaliações de outros clientes não podem ser removidas por este endpoint.

Mídias associadas: caso a avaliação possua imagens ou vídeos vinculados, eles são removidos automaticamente junto com a avaliação. ⚠️

Impacto na nota média: se a avaliação excluída estava ativa, a média de pontuação do produto é recalculada imediatamente, desconsiderando a avaliação removida. Avaliações inativas não afetam o cálculo da média.

📝 Parâmetros

🏷️ Headers Obrigatórios

🔗 Parâmetros da URL

💡 Exemplo de Requisição

1curl --request DELETE \
2  --url '{{MAIN_URL}}/review/42/product/' \
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.

📸 Cadastrar Imagens em uma Avaliação de Produto

📋 Descrição

Endpoint responsável por adicionar imagens a uma avaliação de produto feita pelo cliente 📸.

Essa funcionalidade permite que o cliente complemente sua avaliação com provas visuais, ajudando outros usuários a ter uma melhor percepção do produto e aumentando a confiabilidade do feedback.

Cada avaliação suporta no máximo 3 imagens no total.

O limite é cumulativo: se a avaliação já possuir 2 imagens cadastradas, apenas 1 nova imagem pode ser enviada nesta chamada.

Tentar enviar mais imagens do que o limite disponível retorna o erro UAPPI_TOOLS_AMOUNT_MEDIA_EXCEED_LIMIT.

📝 Parâmetros

🏷️ Headers Obrigatórios

🔗 Parâmetros da URL

📦 Parâmetros do Corpo

💡 Exemplo de Requisição

1curl --request POST \
2  --url '{{MAIN_URL}}/review/47/product/media' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --form 'medias[]=@foto-produto-1.png' \
5  --form 'medias[]=@foto-produto-2.jpg'

✅ Resposta de Sucesso

HTTP Status: 200 OK

A resposta retorna todas as imagens vinculadas à avaliação após a inserção, não apenas as recém-enviadas.

1{
2  "status": true,
3  "data": [
4    {
5      "reviewId": 47,
6      "mediaId": 1,
7      "image": "/upload/stores/product-reviews/a1b2c3d4e5f6g7h8i9j0.webp",
8      "createdAt": "2026-05-20 10:15:00"
9    },
10    {
11      "reviewId": 47,
12      "mediaId": 2,
13      "image": "/upload/stores/product-reviews/z9y8x7w6v5u4t3s2r1q0.webp",
14      "createdAt": "2026-05-26 09:42:31"
15    }
16  ]
17}

⚠️ 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 Imagens de uma Avaliação de Produto

📋 Descrição

Endpoint responsável por remover mídias específicas de uma avaliação de produto feita pelo cliente autenticado 🗑️📸.

O cliente informa os IDs das mídias que deseja excluir. Apenas as mídias pertencentes à avaliação do próprio cliente são removidas — mídias de outros clientes ou de outras avaliações são ignoradas silenciosamente.

Caso nenhuma das mídias informadas corresponda aos registros do cliente, a resposta de sucesso retorna data: false sem lançar erro.

📝 Parâmetros

🏷️ Headers Obrigatórios

🔗 Parâmetros da URL

📦 Parâmetros do Corpo

💡 Exemplo de Requisição

1curl --request DELETE \
2  --url '{{MAIN_URL}}/review/47/product/media' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "medias": [3, 5]
7  }'

✅ 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.