🧩 Documentação de Apps

📋 Visão Geral

O módulo de Apps é um marketplace de integrações e ferramentas que expandem as capacidades da plataforma.

Cada app é disponibilizado em uma categoria e pode ser instalado por loja, tornando-se parte do ecossistema operacional da operação.

Após instalado, um app pode ser configurado individualmente por canal de vendas — permitindo que cada contexto de venda tenha suas próprias definições ativas.

Isso viabiliza cenários como ativar uma integração de rastreamento apenas para um canal específico, sem impactar os demais.

Cada app possui um appCode — um identificador único em formato de texto (ex.: "meu-app-exemplo") que é utilizado em todos os endpoints do módulo como parâmetro de rota.

Esse código é imutável e serve como chave de referência entre instalação, configuração e execução.

🔄 Entidades Envolvidas

O módulo de Apps é composto por três grupos funcionais:

APPS — Navegação e Instalação

Responsável pela descoberta e gestão do ciclo de vida dos apps.

Permite listar todos os apps disponíveis agrupados por categoria, consultar detalhes de um app específico, verificar quais apps já estão instalados na loja e realizar operações de instalação e desinstalação.

A listagem por categoria também suporta filtragem por nome, facilitando a busca em marketplaces com muitos apps disponíveis.

Cada app retorna o campo installed, indicando se aquele app já está ativo na loja do usuário autenticado.

Configurações — Ajustes por Canal de Vendas

Responsável pela leitura e atualização das configurações de um app instalado em um canal de vendas específico.

As configurações variam por app e são definidas como campos tipados — podendo ser textos, booleanos ou valores enumerados — cada um com suas próprias regras de validação.

Cada campo de configuração possui code, name, type, value (valor atual), default (valor padrão) e rules (regras de validação aplicáveis).

Além da leitura e escrita de configurações, também é possível executar ações diretamente sobre o app via canal de vendas.

Favorito — Marcações por Usuário

Permite que o usuário autenticado marque e desmarque apps como favoritos, além de listar todos os apps favoritados.

As marcações de favorito são por usuário, não por loja — cada usuário mantém sua própria lista independente.

📌 Notas e Considerações

• O escopo APP_READ é obrigatório para todos os endpoints de leitura do módulo — listagem por categoria, detalhes de um app, apps instalados e favoritos.
• O escopo APP_CONFIGURE é obrigatório para os endpoints de configuração e execução — leitura e atualização de configurações por canal de vendas, e execução de ações via app.
• O campo appCode é o identificador único de cada app em formato de texto (ex.: "ferramenta-exemplo"). Ele é utilizado como parâmetro de rota em todos os endpoints que operam sobre um app específico.
• Apps só podem ser configurados e executados após estarem instalados na loja. Tentativas de configurar um app não instalado resultam em erro.
• Instalação e desinstalação são operações por loja — realizadas no contexto da loja autenticada. Configurações, por sua vez, são por canal de vendas dentro da loja.

📦 Listagem de Apps por Categoria

Descrição

Endpoint utilizado para obter a listagem completa de apps ativos, agrupados por suas respectivas categorias.

A resposta não é paginada — todos os registros são retornados em uma única chamada.

Categorias que não possuem apps ativos são automaticamente omitidas da resposta, garantindo que apenas categorias com conteúdo relevante sejam exibidas.

Os apps dentro de cada categoria são ordenados pelo campo order, respeitando a ordem de exibição definida na plataforma.

Filtro por nome de app

O campo de condição appName permite filtrar apps pelo nome utilizando correspondência parcial (busca do tipo LIKE).

Ao informar esse campo, apenas os apps cujo nome contenha o valor informado serão incluídos nos resultados — porém a estrutura de categorias é mantida normalmente.

Campo installed

O campo installed indica se o app está ativo no contexto da loja autenticada.

Seu valor é true quando existe um registro de appStore vinculando o app à loja atual; caso contrário, retorna false.

Requer o escopo APP_READ.

Parâmetros

🏷️ Headers Obrigatórios

🔍 Campos de Condição Disponíveis

💡 Exemplo de Requisição

> Nota: esta API aceita corpo JSON em requisições GET, seguindo a convenção da plataforma. Utilize o header Content-Type: application/json e envie os parâmetros no corpo da requisição.

1curl --request GET \
2  --url {{MAIN_URL}}/apps/list-by-category \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "conditions": {
7      "appName": "pagamento"
8    }
9  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": [
4    {
5      "id": 7,
6      "name": "Automações",
7      "icon": "",
8      "description": "Simplifique e automatize as operações do seu negócio conectando recursos internos a fluxos de trabalho personalizados.",
9      "active": true,
10      "order": 1,
11      "apps": [
12        {
13          "id": 42,
14          "code": "meu-app-exemplo",
15          "name": "App de Pagamento Avançado",
16          "icon": "",
17          "shortDescription": "Processe pagamentos com regras customizadas e integração nativa ao checkout.",
18          "averageRating": 4.67,
19          "ratingQuantity": 12,
20          "active": true,
21          "installed": false
22        }
23      ]
24    }
25  ]
26}

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

📦 Apps Instalados

Descrição

Endpoint utilizado para obter a lista de apps instalados na loja do usuário autenticado.

A resposta retorna um array de strings, onde cada elemento é o appCode de um app instalado.

Não há paginação — todos os apps instalados da loja são retornados em uma única chamada.

O resultado reflete o estado atual da loja: caso nenhum app esteja instalado, o array retornado será vazio ([]).

Requer o escopo APP_READ.

Parâmetros

🏷️ Headers Obrigatórios

💡 Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/apps/installed \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json"

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": ["google-tag-manager", "whatsapp-notificacoes"]
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.

🔍 Detalhes de um App

Descrição

Endpoint utilizado para obter as informações completas de um app, identificado pelo seu appCode.

A resposta inclui dados descritivos do app — como nome, descrição curta, descrição longa e ícone — além de métricas de avaliação: averageRating (nota média, decimal com 2 casas) e ratingQuantity (total de avaliações).

O campo installed indica se o app já está instalado na loja do usuário autenticado.

Seu valor é true quando existe um vínculo ativo entre o app e a loja atual; caso contrário, retorna false.

O campo active indica se o app está disponível para uso na plataforma.

Apps inativos podem ser retornados pela busca, mas não podem ser instalados.

Requer o escopo APP_READ.

Parâmetros

🏷️ Headers Obrigatórios

🔗 Parâmetros da URL

💡 Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/apps/google-tag-manager \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json"

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "id": 12,
5    "categoryId": 3,
6    "code": "google-tag-manager",
7    "name": "Google Tag Manager",
8    "icon": "",
9    "shortDescription": "Gerencie tags e scripts de rastreamento sem precisar alterar o código da loja.",
10    "longDescription": "<b>Simplifique o gerenciamento de tags...</b>",
11    "averageRating": 4.67,
12    "ratingQuantity": 28,
13    "active": true,
14    "installed": false,
15    "order": 2
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.

⬇️ Instalação de App

Descrição

Endpoint responsável por instalar um app na loja do usuário autenticado, identificado pelo seu appCode.

A instalação é uma operação por loja — o app é vinculado ao contexto da loja autenticada no momento da requisição.

Após a instalação, o app passa a aparecer com installed: true nas listagens e no endpoint de detalhes.

A instalação também é o pré-requisito obrigatório para acessar e configurar o app por canal de vendas: tentativas de configurar um app não instalado resultam em erro.

Não há corpo de requisição — o appCode informado na URL é suficiente para identificar o app a ser instalado.

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/google-tag-manager/install \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json"

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

🗑️ Desinstalação de App

Descrição

Endpoint responsável por desinstalar um app da loja do usuário autenticado, identificado pelo seu appCode.

A desinstalação é uma operação por loja — o vínculo entre o app e a loja autenticada é removido no momento da requisição.

Após a desinstalação, o app passa a aparecer com installed: false nas listagens e no endpoint de detalhes.

Atenção: ao desinstalar um app, as configurações por canal de vendas associadas a ele também são removidas.

Qualquer tentativa de acessar ou configurar o app após a desinstalação resultará em erro até que ele seja instalado novamente.

Não há corpo de requisição — o appCode informado na URL é suficiente para identificar o app a ser desinstalado.

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/google-tag-manager/install \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json"

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