❤️ Lista de Desejos

📋 Visão Geral

A Lista de Desejos é um recurso que permite ao cliente autenticado salvar e organizar produtos de seu interesse para acompanhamento futuro, sem a necessidade de adicioná-los ao carrinho imediatamente.

Cada cliente pode possuir múltiplas listas com nomes e configurações independentes. As listas podem ser privadas ou compartilhadas publicamente por meio de um uriCode único, gerado automaticamente pela plataforma no momento da criação.

Este módulo é amplamente utilizado em contextos como:

• Listas de presentes — para eventos como casamentos, aniversários e formaturas
• Wishlist pessoal — para acompanhar produtos de interesse ao longo do tempo
• Compartilhamento social — para enviar a lista a terceiros via link público

🔄 Entidades Envolvidas

As seguintes entidades participam do fluxo de lista de desejos:

• Cliente — dono da lista, identificado pelo token de autenticação
• Lista de Desejos (CustomerWishList) — estrutura que agrupa os produtos favoritados
• Produto da Lista (CustomerWishListProduct) — vínculo entre um produto e uma lista

📐 Estrutura da Lista de Desejos

Cada lista de desejos possui os seguintes atributos:

Campo	Tipo	Descrição
id	integer	Identificador único da lista
customerId	integer	ID do cliente dono da lista
name	string	Nome definido pelo cliente para a lista
shareList	boolean	Define se a lista é pública e pode ser acessada por terceiros via link
default	boolean	Indica se esta é a lista padrão do cliente — usada quando nenhuma lista é especificada ao favoritar
uriCode	string	Código único de compartilhamento, gerado automaticamente — usado para acessar a lista publicamente
createdAt	datetime	Data e hora de criação da lista

🔐 Permissão

Todas as rotas desta seção exigem dupla autenticação:

• PublicAuth — autenticação do canal de venda (identificação da loja/aplicação)
• CustomerAuth — token do cliente autenticado, enviado via header Authorization: Bearer {customerToken}

> Requisições sem os dois tokens serão rejeitadas com erro de autenticação.

⭐ Lista Padrão

Todo cliente possui uma lista padrão (default: true), criada automaticamente pela plataforma. Quando um produto é favoritado sem especificar uma lista (customerWishListId omitido), o produto é adicionado automaticamente à lista padrão.

A lista padrão não pode ser excluída.

🌐 Compartilhamento Público

Quando shareList é definido como true, a lista recebe um uriCode único que pode ser utilizado para acessá-la publicamente, sem necessidade de autenticação do cliente dono da lista. Isso permite funcionalidades como:

• Envio de lista de presentes para amigos e familiares
• Integração com páginas públicas de casamento ou chá de bebê
• Compartilhamento via link em redes sociais

🔍 Verificação de Favoritos

O endpoint GET /customer/wish-list/product é usado para verificar, em lote, quais produtos de uma listagem estão favoritados pelo cliente. A resposta é um mapa de productId → boolean, ideal para renderizar ícones de coração nas páginas de listagem de produtos de forma eficiente, sem a necessidade de consultar cada produto individualmente.

📌 Notas e Considerações

• Um produto pode estar em múltiplas listas ao mesmo tempo — não há restrição de unicidade entre listas distintas.
• A exclusão de uma lista remove todos os produtos vinculados a ela de forma permanente e irreversível.
• O campo uriCode é gerado automaticamente e não pode ser alterado após a criação da lista.
• Listas com shareList: false são privadas e acessíveis apenas pelo cliente autenticado dono da lista.
• O campo default é gerenciado pela plataforma e não é enviado na criação ou atualização pelo cliente.

❤️ Listagem de Lista de Desejos

📋 Descrição

Endpoint responsável por listar todas as listas de desejos do cliente autenticado.

O resultado é paginado e suporta filtragem e ordenação por campos específicos, permitindo ao cliente localizar rapidamente listas por nome, visibilidade ou identificador. Cada item retornado inclui os dados essenciais da lista: nome, status de compartilhamento, se é a lista padrão e o código de compartilhamento público (uriCode).

O campo customerId enviado na condição de busca é ignorado automaticamente — a listagem sempre reflete as listas do cliente identificado pelo token de autenticação, garantindo isolamento entre contas.

🔐 Permissão

• CustomerAuth — autenticação do cliente via token JWT

📝 Parâmetros

🏷️ Headers Obrigatórios

📊 Campos de Condição Disponíveis

📊 Campos de Ordenação Disponíveis

💡 Exemplo de Requisição

1curl --request GET \
2  --url '{{MAIN_URL}}/customer/wish-list' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "fields": [],
7    "order": [
8      { "field": "id", "order": "ASC" }
9    ],
10    "condition": {
11      "type": "AND",
12      "conditions": []
13    }
14  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "registers": [
5      {
6        "customerId": 123,
7        "name": "Lista de trabalho",
8        "shareList": true,
9        "default": false,
10        "id": 123,
11        "uriCode": "z69VMQ23qG",
12        "createdAt": "2025-04-04 14:54:06"
13      }
14    ],
15    "pagination": {
16      "limit": 10,
17      "offset": 0,
18      "pages": 16,
19      "registers": 156
20    }
21  }
22}

⚠️ 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.

❤️ Verificação de Produtos Favoritados

📋 Descrição

Endpoint responsável por verificar, em lote, quais produtos de uma lista de IDs estão favoritados pelo cliente autenticado em alguma de suas listas de desejos.

A resposta é um mapa de productId → boolean, onde cada chave é um ID de produto enviado na requisição e o valor indica se aquele produto está ou não favoritado. Esse formato é otimizado para renderizar ícones de coração em páginas de listagem de produtos, evitando múltiplas requisições individuais.

O endpoint considera todas as listas de desejos do cliente ao verificar os favoritos — um produto é considerado favoritado se estiver em qualquer lista pertencente ao cliente autenticado.

🔐 Permissão

• CustomerAuth — autenticação do cliente via token JWT

📝 Parâmetros

🏷️ Headers Obrigatórios

📦 Parâmetros do Corpo

💡 Exemplo de Requisição

1curl --request GET \
2  --url '{{MAIN_URL}}/customer/wish-list/product' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "products": [1, 2, 3, 4]
7  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

A resposta retorna um mapa onde a chave é o ID do produto e o valor é um booleano indicando se está favoritado.

1{
2  "status": true,
3  "data": {
4    "1": true,
5    "2": false,
6    "3": true,
7    "4": false
8  }
9}

⚠️ 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.

❤️ Detalhe da Lista de Desejos

📋 Descrição

Endpoint responsável por retornar os dados completos de uma lista de desejos e seus produtos cadastrados, combinando em uma única resposta as informações da lista e a listagem paginada dos produtos vinculados a ela.

O acesso é restrito ao cliente autenticado dono da lista — não é possível consultar listas de outros clientes por esta rota. Caso o ID informado não pertença ao cliente autenticado, o erro UAPPI_STORE_WISH_LIST_NOT_FOUND é retornado.

A listagem de produtos retornada segue o padrão paginado da plataforma, com suporte a limit e offset via parâmetros de busca.

🔐 Permissão

• CustomerAuth — autenticação do cliente via token JWT

📝 Parâmetros

🏷️ Headers Obrigatórios

🔗 Parâmetros de URL

💡 Exemplo de Requisição

1curl --request GET \
2  --url '{{MAIN_URL}}/customer/wish-list/123/products' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "wishList": {
5      "customerId": 456,
6      "name": "Minha Lista",
7      "shareList": true,
8      "default": false,
9      "id": 123,
10      "uriCode": "z69VMQ23qG",
11      "createdAt": "2025-04-04 14:54:06"
12    },
13    "products": {
14      "registers": [],
15      "pagination": {
16        "limit": 10,
17        "offset": 0,
18        "pages": 0,
19        "registers": 0
20      }
21    }
22  }
23}

⚠️ 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.

❤️ Criar Lista de Desejos

📋 Descrição

Endpoint responsável por criar uma nova lista de desejos vinculada ao cliente autenticado.

O campo shareList define se a lista será pública ou privada. Quando true, a plataforma gera automaticamente um uriCode único — um código de 10 caracteres usado para compartilhar a lista com terceiros via link público, sem necessidade de autenticação. Quando false, a lista permanece privada e acessível apenas pelo cliente autenticado.

Os campos id, customerId, default, uriCode e createdAt são gerenciados pela plataforma e não devem ser enviados na requisição — qualquer tentativa de enviá-los resultará em erro de validação.

🔐 Permissão

• CustomerAuth — autenticação do cliente via token JWT

📝 Parâmetros

🏷️ Headers Obrigatórios

📦 Parâmetros do Corpo

💡 Exemplo de Requisição

1curl --request POST \
2  --url '{{MAIN_URL}}/customer/wish-list' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "name": "Minha Lista de Natal",
7    "shareList": true
8  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "customerId": 456,
5    "name": "Minha Lista de Natal",
6    "shareList": true,
7    "default": false,
8    "id": 123,
9    "uriCode": "z69VMQ23qG",
10    "createdAt": "2026-04-22 10:00:00"
11  }
12}

⚠️ 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 Lista de Desejos

📋 Descrição

Endpoint responsável por atualizar o nome e a visibilidade de uma lista de desejos existente do cliente autenticado.

A lista padrão (default: true) não pode ser modificada por esta rota — tentativas de atualização da lista padrão retornam o erro UAPPI_STORE_CANNOT_MODIFY_DEFAULT_WISH_LIST. Apenas listas criadas manualmente pelo cliente podem ser atualizadas.

Ao enviar shareList: true em uma lista que ainda não possui uriCode, a plataforma gera automaticamente um novo código de compartilhamento. Esse código é permanente e não pode ser regenerado após a criação.

Uma vez que a lista possua um uriCode, o compartilhamento não pode ser revertido: enviar shareList: false para uma lista já compartilhada não altera seu estado — a lista permanece compartilhada e a resposta continuará retornando shareList: true com o uriCode existente. Esse é o comportamento definido pela plataforma.

🔐 Permissão

• CustomerAuth — autenticação do cliente via token JWT

📝 Parâmetros

🏷️ Headers Obrigatórios

🔗 Parâmetros de URL

📦 Parâmetros do Corpo

💡 Exemplo de Requisição

1curl --request PUT \
2  --url '{{MAIN_URL}}/customer/wish-list/123' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "name": "Lista Atualizada",
7    "shareList": true
8  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "customerId": 456,
5    "name": "Lista Atualizada",
6    "shareList": true,
7    "default": false,
8    "id": 123,
9    "uriCode": "z69VMQ23qG",
10    "createdAt": "2026-04-22 10:00:00"
11  }
12}

⚠️ 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 Lista de Desejos

📋 Descrição

Endpoint responsável por remover permanentemente uma lista de desejos do cliente autenticado.

A exclusão é irreversível — todos os produtos vinculados à lista também são removidos de forma permanente. Não é possível recuperar os dados após a operação.

A lista padrão (default: true) do cliente não pode ser excluída — tentativas de remoção retornam o erro UAPPI_STORE_CANNOT_MODIFY_DEFAULT_WISH_LIST. Somente listas criadas manualmente pelo cliente podem ser removidas.

🔐 Permissão

• CustomerAuth — autenticação do cliente via token JWT

📝 Parâmetros

🏷️ Headers Obrigatórios

🔗 Parâmetros de URL

💡 Exemplo de Requisição

1curl --request DELETE \
2  --url '{{MAIN_URL}}/customer/wish-list/123' \
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.

➕ Adicionar Produto à Lista de Desejos

📋 Descrição

Endpoint responsável por adicionar um produto a uma lista de desejos do cliente autenticado.

Quando customerWishListId é omitido ou null, o produto é adicionado automaticamente à lista padrão do cliente. Caso o cliente ainda não possua uma lista padrão, a plataforma cria uma automaticamente antes de adicionar o produto.

Apenas produtos do tipo variação (SKUs) podem ser adicionados a listas de desejos — produtos do tipo pai (agrupadores) são rejeitados com o erro UAPPI_STORE_PRODUCT_IS_PARENT. Além disso, o produto informado deve existir na plataforma, caso contrário o erro UAPPI_STORE_PRODUCT_NOT_FOUND é retornado.

Se o produto já estiver na lista, a operação é ignorada silenciosamente — não há erro por duplicidade.

🔐 Permissão

• CustomerAuth — autenticação do cliente via token JWT

📝 Parâmetros

🏷️ Headers Obrigatórios

📦 Parâmetros do Corpo

💡 Exemplo de Requisição

1curl --request POST \
2  --url '{{MAIN_URL}}/customer/wish-list/product' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "productId": 789,
7    "customerWishListId": 123
8  }'

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

🗑️ Remover Produto da Lista de Desejos

📋 Descrição

Endpoint responsável por remover um produto específico de uma lista de desejos do cliente autenticado.

A remoção é direta e permanente — o produto deixa de estar vinculado àquela lista. Se o mesmo produto estiver em outras listas do cliente, ele permanece nelas sem qualquer impacto. A operação não afeta o produto em si, apenas o vínculo entre o produto e a lista informada.

Caso o customerWishListId não pertença ao cliente autenticado, o erro UAPPI_STORE_WISH_LIST_NOT_FOUND é retornado, garantindo isolamento entre clientes.

🔐 Permissão

• CustomerAuth — autenticação do cliente via token JWT

📝 Parâmetros

🏷️ Headers Obrigatórios

🔗 Parâmetros de URL

💡 Exemplo de Requisição

1curl --request DELETE \
2  --url '{{MAIN_URL}}/customer/wish-list/123/product/789' \
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.