Configurações

Visão Geral

O módulo de Configurações é o componente central para a gestão de parâmetros operacionais e de comportamento dos diversos microserviços da plataforma Uappi.

Ele permite a personalização de regras de negócio que afetam desde o fluxo de checkout até integrações externas.

As configurações são segmentadas por serviços (ex: store, integration, auth) e podem ser aplicadas de forma global ou específica para determinadas políticas comerciais ou canais de venda, oferecendo uma granularidade necessária para operações complexas multicanais.

Este módulo utiliza um sistema de herança de valores, onde uma configuração definida como padrão (default) é aplicada a todos os contextos, a menos que exista um valor específico sobrescrevendo-o para uma determinada política comercial.

Entidades Envolvidas

• Configuração (Setting): Define a chave (code), nome, descrição, tipo de dado e as regras de validação para um parâmetro específico.
• Valor da Configuração (SettingValue): Armazena o valor efetivo de uma configuração para um par de loja e política comercial.
• Política Comercial (Trade Policy): Contexto utilizado para segmentar as configurações conforme o modelo de negócio (B2C, B2B, etc).

Notas e Considerações

Para a leitura e escrita de configurações através da API, é obrigatório o uso dos escopos de permissão SYSTEM_CONFIGURATION_READ e SYSTEM_CONFIGURATION_WRITE, respectivamente.

Toda alteração de configuração dispara eventos internos que notificam os serviços interessados sobre a mudança, garantindo a consistência do sistema em tempo real.

Listagem de Configurações

Descrição

O endpoint de listagem de configurações permite recuperar todos os parâmetros editáveis de um serviço específico do sistema.

A consulta deve obrigatoriamente informar o nome do serviço desejado e o ID da política comercial de contexto.

O retorno inclui detalhes extensivos de cada configuração, como o tipo de dado (text, boolean, enum, etc), as opções disponíveis para campos do tipo lista, e as regras de validação aplicáveis.

O campo value reflete o valor ativo para a política comercial informada.

Para acessar este recurso, é necessário que o usuário possua autenticação válida (UserAuth) e o escopo de permissão SYSTEM_CONFIGURATION_READ devidamente vinculado ao seu perfil de acesso.

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Exemplo de Requisição

1curl --request GET \
2  --url "{{MAIN_URL}}/api/v3/setting?serviceName=store&tradePolicyId=1" \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": [
4    {
5      "code": "cart/days-for-expiration",
6      "name": "Tempo em dias para expiração do carrinho",
7      "description": "",
8      "type": "int",
9      "enum": [],
10      "value": 30,
11      "default": 30,
12      "rules": []
13    },
14    {
15      "code": "cart/minutes-to-abandonment",
16      "name": "Tempo em minutos para mudar status como abandono",
17      "description": "",
18      "type": "int",
19      "enum": [],
20      "value": 40,
21      "default": 40,
22      "rules": []
23    }
24  ]
25}

⚠️ Possíveis erros:

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

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Atualização de Configurações

Descrição

O endpoint de atualização de configurações permite modificar o comportamento dos microserviços através do envio de novos valores para chaves específicas.

Esta operação é realizada em lote, aceitando um array de objetos de configuração.

Cada item enviado no lote é validado individualmente quanto à sua existência e à compatibilidade do tipo de dado (ex: não é permitido enviar uma string para uma configuração do tipo integer).

Se um item falhar na validação, um objeto de erro será retornado para esse item.

A alteração de configurações é uma operação sensível que requer o escopo de permissão SYSTEM_CONFIGURATION_WRITE e autenticação UserAuth.

Após o processamento bem-sucedido, o sistema limpa automaticamente os caches relacionados para garantir a propagação imediata das mudanças.

Parâmetros

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/api/v3/setting \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6  	"serviceName": "store",
7  	"settings": [
8  		{
9  			"tradePolicyId": 3,
10  			"code": "promotional/point-system/name",
11  			"value": "Pontos da loja",
12  			"default": true
13  		}
14  	]
15  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": [
4    {
5      "tradePolicyId": 3,
6      "code": "promotional/point-system/name",
7      "value": "Pontos da loja",
8      "default": true,
9      "error": null
10    }
11  ]
12}

⚠️ Possíveis erros:

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

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

⚠️ Exemplo de erro no lote:

Caso uma das configurações enviadas possua um valor inválido, a resposta retornará o objeto de erro no campo correspondente:

1{
2  "status": true,
3  "data": [
4    {
5      "tradePolicyId": 3,
6      "code": "promotional/point-system/invalid",
7      "value": "Pontos da loja",
8      "default": true,
9      "error": {
10        "code": "UAPPI_CORE_INVALID_SETTING",
11        "message": "The requested setting does not exist."
12      }
13    }
14  ]
15}