Interesses de Produto

Visão Geral

O módulo de Interesses de Produto é uma ferramenta estratégica para a gestão de demanda e relacionamento com o cliente na plataforma Uappi.

Ele centraliza todas as solicitações enviadas pelos usuários através das funcionalidades de Avise-me quando chegar e Produto Sob Consulta. 📩

Este recurso permite que a equipe administrativa visualize, organize e responda às intenções de compra de produtos que estão temporariamente indisponíveis ou que exigem um orçamento personalizado.

Através desta interface, é possível capturar dados valiosos como nome, e-mail, telefone e a mensagem específica do cliente vinculada a um item do catálogo.

A gestão eficiente destes interesses possibilita a recuperação de vendas perdidas por falta de estoque e abre canais de negociação direta para produtos de alto valor agregado.

Além disso, os dados acumulados servem como indicadores de demanda, auxiliando na tomada de decisão sobre reposição de estoque e expansão de mix.

Entidades Envolvidas

* Interesse: Representa o registro individual da intenção do cliente, contendo seus dados de contato e a mensagem.

* Produto: O item do catálogo ao qual o interesse está vinculado. A API permite expandir os dados para visualizar detalhes do produto (DMC de produto simples).

* Canal de Venda: O contexto no qual o interesse foi gerado, garantindo a segmentação correta das solicitações.

Notas e Considerações

As operações administrativas deste módulo exigem o escopo de permissão PRODUCT_INTEREST_READ para consultas e visualização.

Para ações que alteram o estado do registro (como atualizações de status ou resposta), o sistema valida a integridade dos dados através de processos de negócio específicos.

As rotas estão protegidas pelo middleware UserAuth, garantindo que apenas usuários autenticados e autorizados da plataforma possam acessar as informações sensíveis de contato dos clientes.

Listagem de Interesses de Produto

Descrição

O endpoint de Listagem de Interesses de Produto permite a visualização centralizada de todas as solicitações de "Avise-me" e "Sob Consulta" enviadas pelos clientes da loja.

Através desta rota, a equipe de atendimento pode monitorar novas demandas e organizar o fluxo de retorno aos consumidores. 📋

A listagem é altamente flexível, suportando o padrão de busca avançada da Uappi.

É possível filtrar solicitações por e-mail, nome do cliente, origem (Avise-me/Sob Consulta), ou até mesmo por dados do produto vinculado (como SKU ou Nome).

Isso facilita a identificação de quais itens estão gerando maior volume de interesse.

Além dos dados básicos do interesse, o endpoint permite a expansão de campos para trazer detalhes técnicos do produto associado, como preço atual e mídias, facilitando o contexto no momento da resposta ao cliente.

O acesso a este recurso requer autenticação administrativa e o escopo de permissão PRODUCT_INTEREST_READ. 🔒

Parâmetros

Headers Obrigatórios

Campos Disponíveis (fields)

Campos de Condição Disponíveis

Campos de Ordenação Disponíveis

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/products/interests \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "fields": [
6      "products"
7    ],
8    "conditions": {
9      "type": "AND",
10      "conditions": [
11        {
12          "field": "origin",
13          "value": "avise-me"
14        }
15      ]
16    },
17    "limit": 10,
18    "offset": 0
19  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "registers": [
3    {
4      "id": 50,
5      "productId": 1200,
6      "origin": "avise-me",
7      "name": "João da Silva",
8      "email": "joao@exemplo.com.br",
9      "phone": "(11) 98888-7777",
10      "message": "Tenho interesse neste produto quando voltar ao estoque.",
11      "repliedAt": null,
12      "createdAt": "2024-05-20 14:30:00",
13      "simpleProduct": {
14        "productId": 1200,
15        "brandId": 2,
16        "name": "Smartphone Uappi X1",
17        "type": "product",
18        "sku": "UAPPI-X1-BLACK",
19        "comparisonPrice": 2000,
20        "stock": 65,
21        "active": true,
22        "url": "/smartphone-uappi-x1",
23        "brandName": "Uappi Tech",
24        "medias": [],
25        "combination": [],
26        "currentAttributes": []
27      }
28    }
29  ],
30  "pagination": {
31    "limit": 10,
32    "offset": 0,
33    "pages": 1,
34    "registers": 1
35  }
36}

Busca de Interesse de Produto

Descrição

O endpoint de Busca de Interesse de Produto permite recuperar todas as informações detalhadas de uma solicitação específica de "Avise-me" ou "Sob Consulta" via seu ID único.

Esta rota é essencial para visualização individual de mensagens e dados de contato de um cliente interessado. 🔍

Ao realizar esta consulta, a plataforma retorna não apenas o conteúdo da mensagem e os dados de contato (nome, e-mail, telefone), mas também inclui automaticamente os detalhes do produto vinculado.

Isso garante que o administrador tenha todo o contexto necessário para realizar o atendimento sem precisar de consultas adicionais.

O recurso é protegido pelo escopo de permissão PRODUCT_INTEREST_READ, garantindo que apenas usuários autorizados tenham acesso aos dados de intenção de compra e contato dos consumidores. 🔒

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/products/interests/50 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": 50,
3  "productId": 1200,
4  "origin": "avise-me",
5  "name": "João da Silva",
6  "email": "joao@exemplo.com.br",
7  "phone": "(11) 98888-7777",
8  "message": "Tenho interesse neste produto quando voltar ao estoque.",
9  "repliedAt": null,
10  "createdAt": "2024-05-20 14:30:00",
11  "simpleProduct": {
12    "productId": 1200,
13		"brandId": 2,
14    "name": "Smartphone Uappi X1",
15		"type": "product",
16    "sku": "UAPPI-X1-BLACK",
17		"comparisonPrice": 2000,
18		"stock": 65,
19    "active": true,
20    "url": "/smartphone-uappi-x1",
21    "brandName": "Uappi Tech",
22    "medias": [],
23    "combination": [],
24    "currentAttributes": []
25  }
26}

⚠️ Possíveis erros:

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

Atualização de Interesse de Produto

Descrição

O endpoint de Atualização de Interesse de Produto permite modificar os dados de uma solicitação de interesse já cadastrada.

Esta rota é utilizada principalmente para corrigir informações de contato do cliente ou, mais importante, para marcar um interesse como respondido através do campo repliedAt. ✏️

Ao atualizar o campo repliedAt com a data e hora do atendimento, o lojista consegue manter um controle preciso de quais solicitações de "Avise-me" ou "Sob Consulta" já foram processadas pela equipe de vendas.

Isso evita duplicidade de contatos e ajuda na mensuração do tempo médio de resposta (SLA) do atendimento.

A alteração dos dados é protegida por validações de integridade, garantindo que campos obrigatórios como nome e e-mail sejam mantidos dentro dos padrões da plataforma.

O acesso a esta funcionalidade requer o escopo de permissão PRODUCT_INTEREST_WRITE 🔒

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Parâmetros do Corpo

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/products/interests/50 \
3  --header "Content-Type: application/json" \
4  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
5  --data '{
6    "name": "João da Silva Alterado",
7    "email": "joao.novo@exemplo.com.br",
8    "phone": "(11) 99999-8888",
9    "message": "Mensagem atualizada pelo administrador.",
10    "repliedAt": "2024-05-21 10:00:00"
11  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": 50,
3  "productId": 1200,
4  "origin": "avise-me",
5  "name": "João da Silva",
6  "email": "joao@exemplo.com.br",
7  "phone": "(11) 98888-7777",
8  "message": "Tenho interesse neste produto quando voltar ao estoque.",
9  "repliedAt": null,
10  "createdAt": "2024-05-20 14:30:00",
11  "simpleProduct": {
12    "productId": 1200,
13		"brandId": 2,
14    "name": "Smartphone Uappi X1",
15		"type": "product",
16    "sku": "UAPPI-X1-BLACK",
17		"comparisonPrice": 2000,
18		"stock": 65,
19    "active": true,
20    "url": "/smartphone-uappi-x1",
21    "brandName": "Uappi Tech",
22    "medias": [],
23    "combination": [],
24    "currentAttributes": []
25  }
26}

⚠️ Possíveis erros:

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

Exclusão de Interesse de Produto

Descrição

O endpoint de Exclusão de Interesse de Produto é responsável pela remoção definitiva de uma solicitação de "Avise-me" ou "Sob Consulta" do banco de dados da plataforma Uappi.

Esta operação é utilizada para limpar registros obsoletos, duplicados ou que já cumpriram seu ciclo de vida de atendimento. 🗑️

Diferente de outros módulos onde a exclusão pode ser apenas lógica (soft delete), neste caso o registro é removido permanentemente, liberando espaço e mantendo a base de dados administrativa limpa e focada em interesses ativos.

Antes da remoção, o sistema valida se o ID informado existe, garantindo que a operação seja realizada sobre um alvo válido.

O acesso a este recurso é restrito ao ambiente administrativo e exige obrigatoriamente que o usuário possua o escopo de permissão PRODUCT_INTEREST_WRITE.

Recomenda-se cautela ao utilizar esta rota, pois a ação não pode ser desfeita e os dados de contato do cliente associados ao interesse serão perdidos. 🔒

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/products/interests/50 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

HTTP Status: 200 OK

1true

⚠️ Possíveis erros:

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