⚙️ Documentação de Configurações de Apps

📋 Visão Geral

O módulo de Configurações é responsável por ler, atualizar e executar ações em apps instalados, sempre no contexto de um canal de vendas específico.

Cada app pode expor um conjunto de campos de configuração tipados, que definem o comportamento daquele app para o canal em questão.

Exemplos típicos incluem ativar ou desativar a integração, informar credenciais de API e habilitar modos de depuração.

As configurações são isoladas por canal de vendas — o mesmo app pode estar configurado de formas diferentes em canais distintos da mesma loja.

Além de ler e gravar configurações, o módulo oferece uma rota de execução que permite enviar um payload arbitrário ao app, disparando uma ação definida pelo próprio app.

🔄 Entidades Envolvidas

O módulo de Configurações opera sobre dois contratos principais:

Campo de configuração (SettingDMC)

Cada item retornado pela leitura de configurações representa um campo de configuração do app. Ele carrega o code — um identificador único em formato de caminho, como "apps/facebook-graph-api/active" — e o name, que é o rótulo legível do campo.

O type determina como o valor deve ser interpretado e renderizado.

Os tipos suportados são text, int, decimal, bool, array e enum. Quando o tipo é enum, o campo enum contém a lista de opções válidas para seleção.

O value traz o valor atualmente salvo para aquele canal de vendas, enquanto o default representa o valor original definido pelo app.

O campo rules expõe as regras de validação do Laravel aplicadas ao campo — por exemplo, ["required", "boolean"] ou ["required", "string", "max:50"].

Atualização de configurações (UpdateAppSettingDMC)

A atualização é enviada como um mapa de chave-valor dentro do campo settings, onde cada chave é o code do campo de configuração e o valor é o novo conteúdo desejado.

Apenas os campos incluídos na requisição são atualizados — os demais permanecem inalterados.

Execução de app (ExecuteAppDMC)

A execução envia um payload arbitrário ao app.

O conteúdo e a estrutura desse payload são definidos pelo próprio app instalado — o módulo de configurações apenas encaminha os dados recebidos para a lógica interna do app.

📌 Notas e Considerações

• O escopo APP_CONFIGURE é obrigatório para as três rotas do módulo: leitura de configurações, atualização de configurações e execução.
• Configuração e execução só funcionam em apps instalados.
• Tentativas de operar sobre um app não instalado na loja resultam em erro.
• Os campos de configuração variam por app — cada app define seus próprios campos, tipos e regras de validação.
• A leitura de configurações sempre reflete o esquema atual definido pelo app.
• O campo rules de cada configuração contém as mesmas regras aplicadas pelo servidor na atualização.
• Isso permite que interfaces de usuário validem os valores localmente antes de enviá-los.
• A rota de execução é de propósito geral — o que ela faz depende inteiramente do app.
• Consulte a documentação específica de cada app para entender o comportamento esperado do payload.

⚙️ Campos de Configuração do App

📄 Descrição

Endpoint utilizado para obter a lista completa de campos de configuração de um app instalado, referentes a um canal de venda específico.

Cada campo retornado contém as propriedades code, name, type, value, default e rules, que descrevem a identidade, o tipo de dado, o valor atual salvo e as regras de validação daquela configuração.

O campo value reflete o valor atualmente salvo para o canal de venda informado — não o valor padrão do app.

Os campos variam por app: cada app define o seu próprio conjunto de configurações, portanto a estrutura da resposta depende do appCode utilizado.

Requer o escopo APP_CONFIGURE.

📋 Parâmetros

🏷️ Headers Obrigatórios

🔗 Parâmetros da URL

💡 Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/apps/meu-app-exemplo/sales-channel/1/configure \
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    {
5      "code": "apps/meu-app-exemplo/active",
6      "name": "Active",
7      "description": "",
8      "type": "bool",
9      "enum": [],
10      "value": false,
11      "default": false,
12      "rules": ["required", "boolean"]
13    },
14    {
15      "code": "apps/meu-app-exemplo/identificador",
16      "name": "Identificador",
17      "description": "",
18      "type": "text",
19      "enum": [],
20      "value": "",
21      "default": "",
22      "rules": ["required", "string", "max:50"]
23    },
24    {
25      "code": "apps/meu-app-exemplo/token-acesso",
26      "name": "Token de Acesso",
27      "description": "",
28      "type": "text",
29      "enum": [],
30      "value": "",
31      "default": "",
32      "rules": ["required", "string"]
33    },
34    {
35      "code": "apps/meu-app-exemplo/debug",
36      "name": "Debug",
37      "description": "Determina se os erros da integração serão enviados para observabilidade.",
38      "type": "bool",
39      "enum": [],
40      "value": false,
41      "default": false,
42      "rules": ["required", "boolean"]
43    },
44    {
45      "code": "apps/meu-app-exemplo/active-tracking",
46      "name": "Rastreamento ativo",
47      "description": "",
48      "type": "bool",
49      "enum": [],
50      "value": false,
51      "default": false,
52      "rules": ["required", "boolean"]
53    }
54  ]
55}

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

✏️ Atualização de Configurações do App

📋 Descrição

Endpoint responsável por atualizar os campos de configuração de um app instalado, referentes a um canal de venda específico.

O corpo da requisição deve conter o campo settings, que é um mapa chave-valor onde cada chave é o code de uma configuração do app (ex.: "apps/meu-app-exemplo/active") e o valor é o novo dado desejado para aquele campo.

A validação é dinâmica: cada campo em settings é validado contra as regras definidas pelo próprio app para aquela configuração. As regras variam conforme o app e o tipo do campo — consulte o endpoint de listagem (GET /apps/{appCode}/sales-channel/{salesChannelId}/configure) para verificar as regras de cada campo.

Apenas os campos enviados no corpo são atualizados. Configurações não incluídas na requisição não são alteradas.

O app deve estar instalado no canal de venda informado. Caso contrário, o endpoint retorna o erro UAPPI_APP_APP_NOT_INSTALLED.

Requer o escopo APP_CONFIGURE.

📝 Parâmetros

🏷️ Headers Obrigatórios

🔗 Parâmetros da URL

📦 Parâmetros do Corpo

💡 Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/apps/meu-app-exemplo/sales-channel/1/configure \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "settings": {
7      "apps/meu-app-exemplo/active": true,
8      "apps/meu-app-exemplo/identificador": "id-loja-123",
9      "apps/meu-app-exemplo/token-acesso": "tk_abc456xyz",
10      "apps/meu-app-exemplo/debug": false
11    }
12  }'

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

▶️ Execução de App

📋 Descrição

Endpoint responsável por acionar a lógica de execução de um app instalado em um canal de venda específico.

O campo payload é opcional e de estrutura livre — seu conteúdo, significado e validações são definidos pelo próprio app, não pela plataforma. Quando enviado, deve ser um array.

O app deve estar instalado na loja autenticada. Caso contrário, o endpoint retorna o erro UAPPI_APP_APP_NOT_INSTALLED.

Requer o escopo APP_CONFIGURE.

📝 Parâmetros

🏷️ Headers Obrigatórios

🔗 Parâmetros da URL

📦 Parâmetros do Corpo

💡 Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/apps/meu-app-exemplo/sales-channel/1/execute \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "payload": {
7      "acao": "sincronizar-catalogo",
8      "forcar": true
9    }
10  }'

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