Documentação de Regras de Preço

Visão Geral

O módulo de Regras de Preço é o motor de inteligência comercial da plataforma, permitindo a criação de lógicas dinâmicas para a aplicação de valores diferenciados no catálogo. ✨

Diferente do preço fixo, a regra de preço permite que o valor de um item varie de acordo com gatilhos e condições específicas, como a quantidade no carrinho, o local de oferta (Upsell/Compre Junto) ou períodos sazonais programados. 🚀

As regras podem ser configuradas para agir de forma Automática, sendo aplicadas assim que as condições são atendidas, ou através de Códigos específicos. Elas são fundamentais para estratégias de Atacado, onde o preço unitário diminui conforme a quantidade aumenta. 💰

O gerenciamento do módulo abrange desde a definição da lógica (valor percentual ou fixo) até o vínculo massivo com produtos, marcas ou categorias. 🛠️

O acesso às funcionalidades deste módulo é controlado por escopos de segurança:

PRICE_RULE_READ: Necessário para visualizar as regras e seus detalhes. 🔒
PRICE_RULE_WRITE: Necessário para criar, editar, remover ou gerenciar os vínculos das regras. 🔒

Mecanismos de Disparo (Triggers)

Automatic: A regra é aplicada instantaneamente quando o produto é visualizado ou adicionado ao carrinho, desde que as condições de segmentação e agendamento sejam atendidas. ⚡
Quantity Rule (Atacado): Ativada com base em faixas de quantidade (beginQuantity e endQuantity), permitindo tabelas de preço regressivas. 📊
Code: Exige um código específico para ser ativada (comportamento similar a cupons de desconto integrados ao preço). 🎫
Meta Condition: Avalia um grupo de condições (metaCondition) contra os dados do cliente autenticado. Só é aplicada quando há um cliente logado que satisfaça as condições configuradas. 🎯

isCorporate

gender

nationality

email

origin

active

walletAmount

pointSystemAmount

orderQuantity

cancelledOrderQuantity

orderValue

documents

addresses

additionalFields

pelo menos um item

addresses.{stateCode,state,city,district,zipCode,countryCode,main}

documents.{type,document}

additionalFields.{code,value,type,name}

"field": "addresses.stateCode"

qualquer

!=

notIn

"field": "addresses.stateCode", "operator": "!="

qualquer

Alvos e Vínculos

Uma regra de preço pode ser vinculada de forma flexível a diferentes níveis do catálogo:

Produto: Aplicação específica em um item. 📦
Marca: Aplicação em todos os produtos de uma marca selecionada. 🏢
Categoria: Aplicação em toda uma árvore de categorias. 📂

Quando valueType é balance, o alvo é sempre Produto e o preço não vem do campo value da regra — cada produto vinculado tem seu próprio preço fixo (balanceSalePrice), definido diretamente no endpoint de vínculo. Um produto vinculado sem preço válido (ausente ou ≤ 0) simplesmente mantém seu preço original. 🏷️

Notas e Considerações

As regras possuem um sistema de Prioridade. Em cenários onde múltiplas regras podem ser aplicadas ao mesmo item, o sistema utiliza a prioridade e a ordem de processamento para definir o valor final. 📶

Além disso, o recurso de Agendamento permite que campanhas de preço sejam configuradas com antecedência, ativando e desativando automaticamente em datas e horários precisos. ⏰

Listagem de Regras de Preço

GET /products/prices/rules

Retorna a listagem de regras de preço com filtros e paginação.

Descrição

Este endpoint permite a consulta de todas as estratégias de preço dinâmico ativas ou cadastradas no sistema. 📋

A listagem fornece uma visão completa das regras, incluindo seus gatilhos de disparo, valores (fixos ou percentuais), períodos de agendamento e status de ativação. 🔍

Através dos filtros, é possível isolar regras por origem (ex: regras criadas para Upsell), tipos de gatilho ou até mesmo por políticas comerciais vinculadas. Isso facilita a auditoria de campanhas e o gerenciamento de preços por atacado. 📊

O acesso a este recurso requer a permissão PRICE_RULE_READ. 🔒

---

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
Content-Type	application/json	Tipo de conteúdo
Authorization	Bearer {userToken}	Token de autenticação

Campos de Condição Disponíveis

Campo	Tipo	Descrição
id	integer	ID da regra de preço
name	string	Nome descritivo da regra
trigger	string	Gatilho (automatic, code, quantity-rule, meta-condition)
ruleTarget	string	Alvo (product, brand, category)
updateComparisonPrice	string	Comportamento do preço "De" (not-update, original-sale-price, apply-rule)
basePriceField	number	Base de cálculo: base-price, sale-price
code	string	código da regra de preço
origin	string	Origem (product, upsell, pair-offer)
valueType	string	Tipo do valor (value, percentage, balance)
applyInGroup	bool	Sim	Busca por "Atacado Mixado" (soma quantidades de itens diferentes da mesma regra)
active	boolean	Status de ativação
tradePolicyId	integer	ID da política comercial vinculada
beginQuantity	number	Quantidade inicial para atacado
endQuantity	number	Quantidade final para atacado
createdAt	string	Data de criação
updatedAt	string	Data de atualização

Campos de Ordenação Disponíveis

Campo	Descrição
id	ID da entidade
createdAt	Data de criação

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/products/prices/rules \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "conditions": {
6      "type": "AND",
7      "conditions": []
8    },
9    "limit": 10,
10    "offset": 0
11  }'
curl --request GET \
  --url {{MAIN_URL}}/products/prices/rules \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "conditions": {
      "type": "AND",
      "conditions": []
    },
    "limit": 10,
    "offset": 0
  }'

✅ Resposta de Sucesso

1{
2  "registers": [
3    {
4      "id": 1,
5      "name": "Markup automático",
6      "trigger": "automatic",
7      "ruleTarget": "product",
8      "origin": "pair-offer",
9      "applyInGroup": false,
10      "updateComparisonPrice": "not-update",
11      "basePriceField": "sale-price",
12      "code": null,
13      "beginQuantity": 0,
14      "endQuantity": 0,
15      "value": 30,
16      "valueType": "percentage",
17      "priority": 1,
18      "active": true,
19      "scheduling": null,
20      "tradePolicies": [
21        1, 2, 3
22      ],
23      "productIds": [],
24      "balancePrices": [],
25      "metaCondition": [],
26      "productCategoryIds": [],
27      "productBrandIds": [],
28      "lastUpdateUserName": "Admin uappi",
29      "createdAt": "2026-05-19 16:51:00",
30      "updatedAt": "2026-05-19 16:51:00"
31    }
32  ],
33  "pagination": {
34    "limit": 10,
35    "offset": 0,
36    "pages": 1,
37    "registers": 1
38  }
39}
{
  "registers": [
    {
      "id": 1,
      "name": "Markup automático",
      "trigger": "automatic",
      "ruleTarget": "product",
      "origin": "pair-offer",
      "applyInGroup": false,
      "updateComparisonPrice": "not-update",
      "basePriceField": "sale-price",
      "code": null,
      "beginQuantity": 0,
      "endQuantity": 0,
      "value": 30,
      "valueType": "percentage",
      "priority": 1,
      "active": true,
      "scheduling": null,
      "tradePolicies": [
        1, 2, 3
      ],
      "productIds": [],
      "balancePrices": [],
      "metaCondition": [],
      "productCategoryIds": [],
      "productBrandIds": [],
      "lastUpdateUserName": "Admin uappi",
      "createdAt": "2026-05-19 16:51:00",
      "updatedAt": "2026-05-19 16:51:00"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "pages": 1,
    "registers": 1
  }
}

⚠️ Possíveis erros:

Código Interno	Código Http	Descrição
UAPPI_STORE_PRODUCT_PRICE_RULE_NOT_FOUND	404	A regra de preço solicitada não foi encontrada.

Detalhe de Regra de Preço

GET /products/prices/rules/{priceRuleId}

Retorna os dados detalhados de uma regra de preço.

Descrição

Este endpoint fornece uma visão profunda de uma regra de preço, expondo todas as suas configurações lógicas e os vínculos estabelecidos com o catálogo. 🔍

Além dos dados básicos de valor e gatilho, o detalhe retorna as listas exaustivas de IDs de produtos, marcas e categorias que estão sob a influência desta regra. Também são expostas as políticas comerciais onde a regra é válida e os dados de agendamento. 🗓️

Este recurso é vital para entender exatamente como um desconto ou condição de atacado está configurada e quais itens do catálogo ela afeta. ✨

O acesso a este detalhamento exige a permissão PRICE_RULE_READ. 🔒

---

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
Content-Type	application/json	Tipo de conteúdo
Authorization	Bearer {userToken}	Token de autenticação

Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
priceRuleId	integer	Sim	ID único da regra de preço

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/products/prices/rules/5 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"
curl --request GET \
  --url {{MAIN_URL}}/products/prices/rules/5 \
  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

1{
2  "id": 5,
3  "name": "Desconto de Natal",
4  "trigger": "automatic",
5  "ruleTarget": "product",
6  "origin": "api",
7  "applyInGroup": false,
8  "updateComparisonPrice": "yes",
9  "basePriceField": "salePrice",
10  "code": "NATAL2026",
11  "beginQuantity": 1,
12  "endQuantity": 10,
13  "value": 15.50,
14  "valueType": "percentage",
15  "priority": 1,
16  "active": true,
17  "scheduling": {
18    "id": 10,
19    "startDate": "2026-12-01 00:00:00",
20    "endDate": "2026-12-25 23:59:59"
21  },
22  "tradePolicies": [
23    1,
24    2
25  ],
26  "productIds": [
27    500
28  ],
29  "balancePrices": [],
30  "metaCondition": [],
31  "productCategoryIds": [
32    15
33  ],
34  "productBrandIds": [
35    3
36  ],
37  "lastUpdateUserName": "admin_user",
38  "createdAt": "2023-11-01 09:00:00",
39  "updatedAt": "2023-11-01 10:00:00"
40}
{
  "id": 5,
  "name": "Desconto de Natal",
  "trigger": "automatic",
  "ruleTarget": "product",
  "origin": "api",
  "applyInGroup": false,
  "updateComparisonPrice": "yes",
  "basePriceField": "salePrice",
  "code": "NATAL2026",
  "beginQuantity": 1,
  "endQuantity": 10,
  "value": 15.50,
  "valueType": "percentage",
  "priority": 1,
  "active": true,
  "scheduling": {
    "id": 10,
    "startDate": "2026-12-01 00:00:00",
    "endDate": "2026-12-25 23:59:59"
  },
  "tradePolicies": [
    1,
    2
  ],
  "productIds": [
    500
  ],
  "balancePrices": [],
  "metaCondition": [],
  "productCategoryIds": [
    15
  ],
  "productBrandIds": [
    3
  ],
  "lastUpdateUserName": "admin_user",
  "createdAt": "2023-11-01 09:00:00",
  "updatedAt": "2023-11-01 10:00:00"
}

⚠️ Possíveis erros:

Código Interno	Código Http	Descrição
UAPPI_STORE_PRODUCT_PRICE_RULE_NOT_FOUND	404	A regra de preço solicitada não foi encontrada.

Cadastro de Regra de Preço

POST /products/prices/rules

Cria uma nova regra de preço com configurações lógicas e de disparo.

Descrição

Este endpoint permite a definição de novas lógicas comerciais, criando regras que podem ser aplicadas de forma automática ou por gatilhos de quantidade. 🛠️

Ao criar uma regra, define-se o seu comportamento fundamental: se ela será um desconto percentual, um valor fixo ou um saldo, e qual campo do produto servirá como base para o cálculo (basePriceField). 💰

Também é possível configurar a prioridade da regra (relevante em conflitos) e se ela deve atualizar o preço de comparação do produto ao ser aplicada. 📶

Um parâmetro crucial para estratégias de atacado é o applyInGroup.

Quando ativado (true), o sistema permite o "Atacado Mixado", somando as quantidades de todos os itens do carrinho que compartilham a mesma regra para atingir o gatilho de desconto.

Caso desativado (false), a contagem é estritamente individual por SKU. 📊

Após a criação da regra, utiliza-se o endpoint de vínculos (links) para associá-la aos produtos, marcas ou categorias desejados. ✨

Quando trigger é meta-condition, é obrigatório informar metaCondition, um grupo de condições avaliado em tempo real contra os dados do cliente autenticado. A regra só se aplica quando houver um cliente logado cujos dados satisfaçam as condições. 🎯

Campos escalares do cliente (isCorporate, gender, nationality, email, origin, active, walletAmount, pointSystemAmount, orderQuantity, cancelledOrderQuantity, orderValue) são comparados diretamente. Já documents, addresses e additionalFields são listas — o campo da condição precisa usar notação de ponto pra acessar um subcampo (addresses.stateCode, documents.type, additionalFields.code, etc.), e a condição é satisfeita se pelo menos um item da lista bater — não precisa ser o endereço/documento principal. 📍

A execução desta operação exige o escopo de segurança PRICE_RULE_WRITE. 🔒

---

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
Content-Type	application/json	Tipo de conteúdo
Authorization	Bearer {userToken}	Token de autenticação

Parâmetros de Corpo (JSON)

Parâmetro	Tipo	Obrigatório	Descrição
tradePolicyId	integer	Não	ID da política comercial associada
name	string	Sim	Nome da regra
trigger	string	Sim	Gatilho: `automatic`, `code`, `quantity-rule`, `meta-condition`
ruleTarget	string	Sim	Alvo: `product`, `brand`, `category`. Obrigatoriamente `product` quando `valueType` é `balance`
origin	string	Sim	Origem `pair-offer`, `upsell`, `product` (Default: `product`)
applyInGroup	bool	Sim	Ativa o "Atacado Mixado" (soma quantidades de itens diferentes da mesma regra)
updateComparisonPrice	string	Não	Comportamento do preço "De" `not-update`, `original-sale-price`, `apply-rule`
basePriceField	string	Sim	Base de cálculo: `base-price`, `sale-price`
beginQuantity	number	Obrigatório se o type for "quantity-rule"	Quantidade inicial (para atacado)
endQuantity	number	Obrigatório se o type for "quantity-rule"	Quantidade final (para atacado)
value	number	Obrigatório, exceto quando `valueType` for `balance`	Valor da regra
valueType	string	Sim	Tipo: `percentage`, `value`, `balance`. Quando `balance`, cada produto vinculado tem preço próprio, definido no endpoint de vínculo
priority	integer	Sim	Prioridade (menor valor = maior prioridade)
active	boolean	Não	Status de ativação (Default: true)
tradePolicies	object	Não	Mapa de IDs de políticas comerciais (ex: `{"1": true}`)
metaCondition	object	Obrigatório quando `trigger` for `meta-condition`	Grupo de condições `{type: "AND"\`	"OR", conditions: [{field, operator, value}]}, avaliado contra os dados do cliente autenticado

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/products/prices/rules \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "name": "Black Friday Antecipada",
6    "trigger": "automatic",
7    "ruleTarget": "product",
8    "value": 20,
9    "valueType": "percentage",
10    "applyInGroup": true,
11    "basePriceField": "sale-price",
12    "updateComparisonPrice": 'not-update',
13    "origin": "product",
14    "priority": 1,
15    "active": true,
16    "tradePolicies": {
17      "1": true
18    }
19  }'
curl --request POST \
  --url {{MAIN_URL}}/products/prices/rules \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "name": "Black Friday Antecipada",
    "trigger": "automatic",
    "ruleTarget": "product",
    "value": 20,
    "valueType": "percentage",
    "applyInGroup": true,
    "basePriceField": "sale-price",
    "updateComparisonPrice": 'not-update',
    "origin": "product",
    "priority": 1,
    "active": true,
    "tradePolicies": {
      "1": true
    }
  }'

Exemplo com trigger: meta-condition:

1curl --request POST \
2  --url {{MAIN_URL}}/products/prices/rules \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "name": "Desconto para Pessoa Física",
6    "trigger": "meta-condition",
7    "ruleTarget": "product",
8    "value": 10,
9    "valueType": "percentage",
10    "applyInGroup": false,
11    "basePriceField": "sale-price",
12    "updateComparisonPrice": "not-update",
13    "origin": "product",
14    "priority": 1,
15    "active": true,
16    "tradePolicies": {
17      "1": true
18    },
19    "metaCondition": {
20      "type": "AND",
21      "conditions": [
22        { "field": "isCorporate", "operator": "=", "value": false }
23      ]
24    }
25  }'
curl --request POST \
  --url {{MAIN_URL}}/products/prices/rules \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "name": "Desconto para Pessoa Física",
    "trigger": "meta-condition",
    "ruleTarget": "product",
    "value": 10,
    "valueType": "percentage",
    "applyInGroup": false,
    "basePriceField": "sale-price",
    "updateComparisonPrice": "not-update",
    "origin": "product",
    "priority": 1,
    "active": true,
    "tradePolicies": {
      "1": true
    },
    "metaCondition": {
      "type": "AND",
      "conditions": [
        { "field": "isCorporate", "operator": "=", "value": false }
      ]
    }
  }'

Exemplo com condição sobre um campo de lista (addresses.stateCode — bate se o cliente tiver qualquer endereço em MG, principal ou não):

1curl --request POST \
2  --url {{MAIN_URL}}/products/prices/rules \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "name": "Desconto para clientes de MG",
6    "trigger": "meta-condition",
7    "ruleTarget": "product",
8    "value": 10,
9    "valueType": "percentage",
10    "applyInGroup": false,
11    "basePriceField": "sale-price",
12    "updateComparisonPrice": "not-update",
13    "origin": "product",
14    "priority": 1,
15    "active": true,
16    "tradePolicies": {
17      "1": true
18    },
19    "metaCondition": {
20      "type": "AND",
21      "conditions": [
22        { "field": "addresses.stateCode", "operator": "=", "value": "BR-MG" }
23      ]
24    }
25  }'
curl --request POST \
  --url {{MAIN_URL}}/products/prices/rules \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "name": "Desconto para clientes de MG",
    "trigger": "meta-condition",
    "ruleTarget": "product",
    "value": 10,
    "valueType": "percentage",
    "applyInGroup": false,
    "basePriceField": "sale-price",
    "updateComparisonPrice": "not-update",
    "origin": "product",
    "priority": 1,
    "active": true,
    "tradePolicies": {
      "1": true
    },
    "metaCondition": {
      "type": "AND",
      "conditions": [
        { "field": "addresses.stateCode", "operator": "=", "value": "BR-MG" }
      ]
    }
  }'

✅ Resposta de Sucesso

1{
2  "id": 1,
3  "name": "Markup automático",
4  "trigger": "automatic",
5  "ruleTarget": "product",
6  "origin": "pair-offer",
7  "applyInGroup": false,
8  "updateComparisonPrice": "not-update",
9  "basePriceField": "sale-price",
10  "code": null,
11  "beginQuantity": 0,
12  "endQuantity": 0,
13  "value": 30,
14  "valueType": "percentage",
15  "priority": 1,
16  "active": true,
17  "scheduling": null,
18  "tradePolicies": [
19    1, 2, 3
20  ],
21  "productIds": [],
22  "balancePrices": [],
23  "metaCondition": [],
24  "productCategoryIds": [],
25  "productBrandIds": [],
26  "lastUpdateUserName": "Admin uappi",
27  "createdAt": "2026-05-19 16:51:00",
28  "updatedAt": "2026-05-19 16:51:00"
29}
{
  "id": 1,
  "name": "Markup automático",
  "trigger": "automatic",
  "ruleTarget": "product",
  "origin": "pair-offer",
  "applyInGroup": false,
  "updateComparisonPrice": "not-update",
  "basePriceField": "sale-price",
  "code": null,
  "beginQuantity": 0,
  "endQuantity": 0,
  "value": 30,
  "valueType": "percentage",
  "priority": 1,
  "active": true,
  "scheduling": null,
  "tradePolicies": [
    1, 2, 3
  ],
  "productIds": [],
  "balancePrices": [],
  "metaCondition": [],
  "productCategoryIds": [],
  "productBrandIds": [],
  "lastUpdateUserName": "Admin uappi",
  "createdAt": "2026-05-19 16:51:00",
  "updatedAt": "2026-05-19 16:51:00"
}

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

Código Interno	Código Http	Descrição
UAPPI_CORE_INVALID_TRADE_POLICY_ID	400	Os ids de política comercial solicitadas não são permitidos.
UAPPI_STORE_PRODUCT_PRICE_RULE_NOT_FOUND	404	A regra de preço solicitada não foi encontrada.
UAPPI_STORE_BALANCE_REQUIRES_PRODUCT_TARGET	400	Regras com `valueType=balance` exigem `ruleTarget=product`.
UAPPI_STORE_META_CONDITION_REQUIRED	400	Regras com `trigger=meta-condition` exigem ao menos uma condição em `metaCondition`.

Atualização de Regra de Preço

PUT /products/prices/rules/{priceRuleId}

Altera os dados e comportamentos de uma regra de preço.

Descrição

Este endpoint permite a modificação de estratégias comerciais já cadastradas. 🛠️

É possível alterar desde o nome da regra até as suas configurações mais sensíveis, como o valor do desconto, o gatilho de disparo e os períodos de agendamento. ⏰

Ao atualizar uma regra, o sistema recalcula automaticamente a sua aplicação nos itens vinculados, e a limpeza de cache garante que a nova condição comercial seja refletida nos canais de venda configurados. 🔄

Quando valueType é balance, o ruleTarget é obrigatoriamente product e o campo value não é utilizado — o preço de cada produto é definido individualmente no endpoint de vínculo (balanceSalePrice). Ao trocar a regra para outro valueType, os preços de balance já cadastrados são zerados, mas os vínculos com os produtos permanecem. 🏷️

Quando trigger é meta-condition, é obrigatório informar metaCondition, um grupo de condições avaliado em tempo real contra os dados do cliente autenticado. 🎯

Para executar a atualização, o usuário deve possuir a permissão PRICE_RULE_WRITE. 🔒

---

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
Content-Type	application/json	Tipo de conteúdo
Authorization	Bearer {userToken}	Token de autenticação

Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
priceRuleId	integer	Sim	ID único da regra de preço

Parâmetros de Corpo (JSON)

Parâmetro	Tipo	Obrigatório	Descrição
tradePolicyId	integer	Não	ID da política comercial associada
name	string	Sim	Nome da regra
trigger	string	Sim	Gatilho: `automatic`, `code`, `quantity-rule`, `meta-condition`
ruleTarget	string	Sim	Alvo: `product`, `brand`, `category`. Obrigatoriamente `product` quando `valueType` é `balance`
applyInGroup	bool	Sim	Ativa o "Atacado Mixado" (soma quantidades de itens diferentes da mesma regra)
updateComparisonPrice	string	Não	Comportamento do preço "De" `not-update`, `original-sale-price`, `apply-rule`
basePriceField	string	Sim	Base de cálculo: `base-price`, `sale-price`
beginQuantity	number	Obrigatório se o type for "quantity-rule"	Quantidade inicial (para atacado)
endQuantity	number	Obrigatório se o type for "quantity-rule"	Quantidade final (para atacado)
value	number	Obrigatório, exceto quando `valueType` for `balance`	Valor da regra
valueType	string	Sim	Tipo: `percentage`, `value`, `balance`. Quando `balance`, cada produto vinculado tem preço próprio, definido no endpoint de vínculo
priority	integer	Sim	Prioridade (menor valor = maior prioridade)
active	boolean	Não	Status de ativação (Default: true)
tradePolicies	object	Não	Mapa de IDs de políticas comerciais (ex: `{"1": true}`)
metaCondition	object	Obrigatório quando `trigger` for `meta-condition`	Grupo de condições `{type: "AND"\`	"OR", conditions: [{field, operator, value}]}, avaliado contra os dados do cliente autenticado

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/products/prices/rules/12 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "name": "Black Friday Antecipada",
6    "trigger": "automatic",
7    "ruleTarget": "product",
8    "value": 20,
9    "valueType": "percentage",
10    "applyInGroup": true,
11    "basePriceField": "sale-price",
12    "updateComparisonPrice": 'not-update',
13    "priority": 1,
14    "active": true,
15    "tradePolicies": {
16      "1": true
17    }
18  }'
curl --request PUT \
  --url {{MAIN_URL}}/products/prices/rules/12 \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "name": "Black Friday Antecipada",
    "trigger": "automatic",
    "ruleTarget": "product",
    "value": 20,
    "valueType": "percentage",
    "applyInGroup": true,
    "basePriceField": "sale-price",
    "updateComparisonPrice": 'not-update',
    "priority": 1,
    "active": true,
    "tradePolicies": {
      "1": true
    }
  }'

Exemplo com condição sobre um campo de lista (addresses.stateCode — bate se o cliente tiver qualquer endereço em MG, principal ou não):

1curl --request PUT \
2  --url {{MAIN_URL}}/products/prices/rules/12 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "name": "Desconto para clientes de MG",
6    "trigger": "meta-condition",
7    "ruleTarget": "product",
8    "value": 10,
9    "valueType": "percentage",
10    "applyInGroup": false,
11    "basePriceField": "sale-price",
12    "updateComparisonPrice": "not-update",
13    "priority": 1,
14    "active": true,
15    "tradePolicies": {
16      "1": true
17    },
18    "metaCondition": {
19      "type": "AND",
20      "conditions": [
21        { "field": "addresses.stateCode", "operator": "=", "value": "BR-MG" }
22      ]
23    }
24  }'
curl --request PUT \
  --url {{MAIN_URL}}/products/prices/rules/12 \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "name": "Desconto para clientes de MG",
    "trigger": "meta-condition",
    "ruleTarget": "product",
    "value": 10,
    "valueType": "percentage",
    "applyInGroup": false,
    "basePriceField": "sale-price",
    "updateComparisonPrice": "not-update",
    "priority": 1,
    "active": true,
    "tradePolicies": {
      "1": true
    },
    "metaCondition": {
      "type": "AND",
      "conditions": [
        { "field": "addresses.stateCode", "operator": "=", "value": "BR-MG" }
      ]
    }
  }'

✅ Resposta de Sucesso

1{
2  "id": 1,
3  "name": "Markup automático",
4  "trigger": "automatic",
5  "ruleTarget": "product",
6  "origin": "pair-offer",
7  "applyInGroup": false,
8  "updateComparisonPrice": "not-update",
9  "basePriceField": "sale-price",
10  "code": null,
11  "beginQuantity": 0,
12  "endQuantity": 0,
13  "value": 30,
14  "valueType": "percentage",
15  "priority": 1,
16  "active": true,
17  "scheduling": null,
18  "tradePolicies": [
19    1, 2, 3
20  ],
21  "productIds": [],
22  "balancePrices": [],
23  "metaCondition": [],
24  "productCategoryIds": [],
25  "productBrandIds": [],
26  "lastUpdateUserName": "Admin uappi",
27  "createdAt": "2026-05-19 16:51:00",
28  "updatedAt": "2026-05-19 16:51:00"
29}
{
  "id": 1,
  "name": "Markup automático",
  "trigger": "automatic",
  "ruleTarget": "product",
  "origin": "pair-offer",
  "applyInGroup": false,
  "updateComparisonPrice": "not-update",
  "basePriceField": "sale-price",
  "code": null,
  "beginQuantity": 0,
  "endQuantity": 0,
  "value": 30,
  "valueType": "percentage",
  "priority": 1,
  "active": true,
  "scheduling": null,
  "tradePolicies": [
    1, 2, 3
  ],
  "productIds": [],
  "balancePrices": [],
  "metaCondition": [],
  "productCategoryIds": [],
  "productBrandIds": [],
  "lastUpdateUserName": "Admin uappi",
  "createdAt": "2026-05-19 16:51:00",
  "updatedAt": "2026-05-19 16:51:00"
}

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

Código Interno	Código Http	Descrição
UAPPI_CORE_INVALID_TRADE_POLICY_ID	400	Os ids de política comercial solicitadas não são permitidos.
UAPPI_STORE_PRODUCT_PRICE_RULE_NOT_FOUND	404	A regra de preço solicitada não foi encontrada.
UAPPI_STORE_BALANCE_REQUIRES_PRODUCT_TARGET	400	Regras com `valueType=balance` exigem `ruleTarget=product`.
UAPPI_STORE_META_CONDITION_REQUIRED	400	Regras com `trigger=meta-condition` exigem ao menos uma condição em `metaCondition`.

Vínculo de Regra de Preço

PUT /products/prices/rules/links

Gerencia massivamente os vínculos da regra de preço com as entidades do catálogo.

Descrição

Este endpoint é o canal de associação massiva do módulo de regras de preço. 🛠️

Após criar uma regra, é necessário "dizer" ao sistema quais itens ela afeta. Este endpoint permite enviar uma lista de comandos para vincular (add) ou desvincular (remove) a regra de produtos, marcas ou categorias específicas. 📦

Assim como as outras operações em lote da plataforma, o sistema processa cada comando individualmente e retorna um relatório de sucesso ou erro para cada item, garantindo que falhas em um vínculo não interrompam os demais. ✅

É também neste endpoint que o preço de produtos vinculados a uma regra valueType=balance é definido, através de balanceSalePrice. Se o produto já estiver vinculado à regra, enviar um novo balanceSalePrice atualiza o preço em vez de retornar erro de vínculo duplicado — esse é o único caso em que reenviar uma combinação já existente não é rejeitado. Omitir balanceSalePrice ou enviá-lo como null limpa o preço fixo (mesmo que o vínculo já tivesse um preço definido antes), e o produto passa a usar seu preço original. 🏷️

A execução desta operação exige o escopo de segurança PRICE_RULE_WRITE. 🔒

---

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
Content-Type	application/json	Tipo de conteúdo
Authorization	Bearer {userToken}	Token de autenticação

Parâmetros de Corpo (JSON)

O corpo deve conter um objeto com a chave links, contendo um array de comandos.

Parâmetro	Tipo	Obrigatório	Descrição
links	array	Sim	Lista de comandos de vínculo
links.*.priceRuleId	integer	Sim	ID da regra de preço
links.*.action	string	Sim	Ação: `add` ou `remove`
links.*.productId	integer	Obrigatório quando não houver o id de outra entidade informado	ID do produto para vínculo
links.*.productBrandId	integer	Obrigatório quando não houver o id de outra entidade informado	ID da marca para vínculo
links.*.productCategoryId	integer	Obrigatório quando não houver o id de outra entidade informado	ID da categoria para vínculo
links.*.balanceSalePrice	number	Não	Preço fixo do produto, usado apenas quando a regra tem `valueType=balance`. Deve ser maior que 0 quando informado

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/products/prices/rules/links \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "links": [
6      {
7        "priceRuleId": 12,
8        "productId": 101,
9        "action": "add"
10      },
11      {
12        "priceRuleId": 12,
13        "productBrandId": 50,
14        "action": "add"
15      }
16    ]
17  }'
curl --request PUT \
  --url {{MAIN_URL}}/products/prices/rules/links \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "links": [
      {
        "priceRuleId": 12,
        "productId": 101,
        "action": "add"
      },
      {
        "priceRuleId": 12,
        "productBrandId": 50,
        "action": "add"
      }
    ]
  }'

Exemplo definindo o preço fixo de um produto numa regra balance:

1curl --request PUT \
2  --url {{MAIN_URL}}/products/prices/rules/links \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "links": [
6      {
7        "priceRuleId": 13,
8        "productId": 101,
9        "action": "add",
10        "balanceSalePrice": 99.90
11      }
12    ]
13  }'
curl --request PUT \
  --url {{MAIN_URL}}/products/prices/rules/links \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "links": [
      {
        "priceRuleId": 13,
        "productId": 101,
        "action": "add",
        "balanceSalePrice": 99.90
      }
    ]
  }'

✅ Resposta de Sucesso

1[
2  {
3    "priceRuleId": 12,
4    "productId": 101,
5    "productBrandId": null,
6    "productCategoryId": null,
7    "action": "add",
8    "balanceSalePrice": null,
9    "error": null
10  },
11  {
12    "priceRuleId": 12,
13    "productId": null,
14    "productCategoryId": null,
15    "productBrandId": 50,
16    "action": "add",
17    "balanceSalePrice": null,
18    "error": null
19  }
20]
[
  {
    "priceRuleId": 12,
    "productId": 101,
    "productBrandId": null,
    "productCategoryId": null,
    "action": "add",
    "balanceSalePrice": null,
    "error": null
  },
  {
    "priceRuleId": 12,
    "productId": null,
    "productCategoryId": null,
    "productBrandId": 50,
    "action": "add",
    "balanceSalePrice": null,
    "error": null
  }
]

⚠️ Possíveis erros:

Código Interno	Código Http	Descrição
UAPPI_STORE_PRODUCT_PRICE_RULE_NOT_FOUND	404	A regra de preço solicitada não foi encontrada.
UAPPI_STORE_PRODUCT_NOT_FOUND	404	O produto solicitado não foi encontrado.
UAPPI_STORE_BRAND_NOT_FOUND	404	A marca solicitada não foi encontrada.
UAPPI_STORE_CATEGORY_NOT_FOUND	404	A categoria solicitada não foi encontrada.
UAPPI_STORE_PRICE_RULE_LINK_COMBINATION_ALREADY_USED	400	O vínculo já existe. Só é possível reenviar a mesma combinação para atualizar `balanceSalePrice` em regras `balance` — para outros tipos de regra, o vínculo duplicado é sempre rejeitado.
UAPPI_STORE_INVALID_PRICE_RULE_TARGET	400	O alvo informado no vínculo (produto, marca ou categoria) não corresponde ao `ruleTarget` configurado na regra.

Remoção de Regra de Preço

DELETE /products/prices/rules/{priceRuleId}

Remove uma regra de preço do sistema.

Descrição

Este endpoint realiza a exclusão definitiva de uma regra de preço. 🗑️

Ao remover uma regra, todos os vínculos com produtos, marcas e categorias são desfeitos automaticamente, e os itens afetados deixam de receber os benefícios comerciais que a regra proporcionava. 🔄

Esta operação é irreversível e deve ser realizada com cautela, especialmente em regras que afetam grandes porções do catálogo.

A permissão necessária para esta ação é PRICE_RULE_WRITE. 🔒

---

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
Content-Type	application/json	Tipo de conteúdo
Authorization	Bearer {userToken}	Token de autenticação

Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
priceRuleId	integer	Sim	ID único da regra de preço

Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/products/prices/rules/12 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"
curl --request DELETE \
  --url {{MAIN_URL}}/products/prices/rules/12 \
  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

1true
true

⚠️ Possíveis erros:

Código Interno	Código Http	Descrição
UAPPI_STORE_PRODUCT_PRICE_RULE_NOT_FOUND	404	A regra de preço solicitada não foi encontrada.

Começando

Store Theme

Customização de Interface

Consumo de Dados

Tracking e SEO

Checkout

Consumo de Dados

Tracking e SEO

Ambiente de Pagamento

Área Restrita (Minha Conta)

Consumo de Dados

Tracking e SEO

SDK Público (public-sdk)

Modules

Api

Tracking

API Pública

Área Restrita (Minha Conta)

Carrinho de Compras

API Privada

Apps

Configurações Gerais

Clientes

Template

Avaliações

Notificações

ERPs

Filas

Grupo de Pedidos

Pedidos

Carrinhos

Pagamentos

Anti-Fraude

Produtos

Inteligência Artificial

Marcas

Categorias

Filtros

Atributos

Url

Relatórios

Render

Fretes

Usuários

Promocionais

Marketplace

Third Party

Datalogic

Busca

MCP

Documentação de Regras de Preço

Visão Geral

Mecanismos de Disparo (Triggers)

Alvos e Vínculos

Notas e Considerações

Listagem de Regras de Preço

Descrição

Parâmetros

Headers Obrigatórios

Campos de Condição Disponíveis

Campos de Ordenação Disponíveis

Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis erros:

Detalhe de Regra de Preço

Descrição

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis erros:

Cadastro de Regra de Preço

Descrição

Parâmetros

Headers Obrigatórios

Parâmetros de Corpo (JSON)

Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis erros: