⭐ Documentação de Favoritos de Apps

📋 Visão Geral

O módulo de Favoritos permite que cada usuário marque apps de sua preferência para acesso rápido.

Os favoritos são vinculados ao usuário autenticado — não à loja. Isso significa que dois usuários diferentes que operam na mesma loja possuem listas de favoritos independentes.

O módulo oferece três operações: listar os apps favoritados pelo usuário atual, adicionar um app à lista de favoritos e remover um app dessa lista.

Todas as rotas do módulo exigem autenticação via token de usuário e o escopo APP_READ.

🔄 Entidades Envolvidas

App favoritado

Cada item retornado pela listagem representa um app que o usuário marcou como favorito.

O objeto carrega o id e o code do app — identificadores únicos na plataforma. O campo name contém o nome legível do app e icon aponta para o ícone visual.

O shortDescription fornece uma descrição resumida do app. Os campos averageRating e ratingQuantity refletem a avaliação média (decimal com 2 casas, ex.: 4.67) e o número de avaliações recebidas pelo app na plataforma.

O campo active indica se o app está ativo na plataforma. O campo installed indica se o app está instalado na loja do contexto autenticado.

O campo categoryId identifica a categoria à qual o app pertence, e order determina a ordem de exibição dos favoritos do usuário.

Operações de marcação

Para adicionar um favorito, o appCode é passado diretamente na URL da rota POST /apps/{appCode}/favorite. Não é necessário corpo na requisição.

Para remover, o mesmo padrão é utilizado com o método DELETE /apps/{appCode}/favorite.

📌 Notas e Considerações

O escopo APP_READ é obrigatório para as três rotas do módulo: listagem, adição e remoção.

Os favoritos são isolados por usuário — a lista retornada sempre reflete exclusivamente os favoritos do usuário autenticado na requisição.

Ao tentar adicionar um app que já está na lista de favoritos do usuário, o sistema retorna sucesso sem duplicar o registro.

A operação de adição exige que o app esteja instalado na loja autenticada. Apps não instalados não podem ser favoritados.

A operação de remoção não exige que o app esteja instalado — valida apenas a existência do app pelo appCode.

Somente apps com o campo active igual a true são retornados na listagem de favoritos.

⭐ Listagem de Apps Favoritos

📄 Descrição

Endpoint utilizado para obter a lista de apps favoritados pelo usuário autenticado.

A resposta é um array de objetos, onde cada objeto representa um app que o usuário marcou como favorito. O array pode ser vazio caso o usuário não tenha nenhum favorito registrado.

Os resultados são retornados ordenados pelo campo order, que representa a posição definida pelo usuário para cada favorito.

Apenas apps com status ativo na plataforma aparecem na listagem — apps desativados são excluídos automaticamente da resposta.

Requer o escopo APP_READ.

📋 Parâmetros

🏷️ Headers Obrigatórios

💡 Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/apps/favorite \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": [
4    {
5      "id": 5,
6      "categoryId": 2,
7      "code": "meu-app-exemplo",
8      "name": "Meu App Exemplo",
9      "icon": "https://cdn.exemplo.com/apps/meu-app-exemplo/icon.png",
10      "shortDescription": "Descrição resumida do app para exibição nas listagens.",
11      "longDescription": "",
12      "averageRating": 4.67,
13      "ratingQuantity": 12,
14      "active": true,
15      "installed": true,
16      "order": 1
17    },
18    {
19      "id": 9,
20      "categoryId": 1,
21      "code": "outro-app-exemplo",
22      "name": "Outro App Exemplo",
23      "icon": "https://cdn.exemplo.com/apps/outro-app-exemplo/icon.png",
24      "shortDescription": "Outro app marcado como favorito pelo usuário.",
25      "longDescription": "",
26      "averageRating": 5,
27      "ratingQuantity": 3,
28      "active": true,
29      "installed": false,
30      "order": 2
31    }
32  ]
33}

Campos da resposta

⚠️ 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 App aos Favoritos

📋 Descrição

Endpoint utilizado para adicionar um app à lista de favoritos do usuário autenticado.

O appCode é passado diretamente na URL — nenhum corpo de requisição é necessário.

O app deve estar instalado na loja do contexto autenticado. Tentativas de favoritar um app não instalado resultam no erro UAPPI_APP_APP_NOT_INSTALLED.

Caso o app já esteja na lista de favoritos do usuário, o endpoint retorna sucesso sem criar um registro duplicado.

Requer o escopo APP_READ.

📝 Parâmetros

🏷️ Headers Obrigatórios

🔗 Parâmetros da URL

💡 Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/apps/meu-app-exemplo/favorite \
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.

🗑️ Remover App dos Favoritos

📋 Descrição

Endpoint utilizado para remover um app da lista de favoritos do usuário autenticado.

O appCode é passado diretamente na URL — nenhum corpo de requisição é necessário.

O endpoint valida a existência do app pelo appCode informado, mas não exige que o app esteja instalado na loja. A remoção opera sobre o registro de favorito vinculado ao usuário e à loja do contexto autenticado.

Requer o escopo APP_READ.

📝 Parâmetros

🏷️ Headers Obrigatórios

🔗 Parâmetros da URL

💡 Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/apps/meu-app-exemplo/favorite \
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.