Regras de Valor Customizado (Admin)

Visão Geral

As Regras de Valor Customizado permitem que operadores administrativos apliquem ajustes financeiros pontuais em um carrinho antes de sua conversão em pedido.

Diferente de promoções automáticas ou cupons públicos, estas regras são tratativas comerciais diretas, vinculadas exclusivamente ao contexto daquela negociação assistida.

O sistema permite a aplicação de três tipos principais de ajustes: addition (acréscimos), discount (descontos) e shipping (ajustes de frete). Cada regra é registrada com uma descrição justificativa, garantindo a rastreabilidade da alteração para auditorias futuras.

Entidades Envolvidas

Regras de Negócio e Escopo

Os ajustes podem ser aplicados em três níveis de granularidade, dependendo da necessidade da negociação: 1. Nível de Carrinho: O ajuste impacta o valor total da transação. 2. Nível de Pedido (cartOrderId): Em carrinhos com múltiplos vendedores ou centros de distribuição, o ajuste pode ser restrito a uma parte do pedido. 3. Nível de Item/Produto: Permite bonificar ou sobretaxar um SKU específico através dos vínculos com cartOrderItemId ou cartOrderProductId.

---

Observações de SLA de Entrega

Ao utilizar o tipo shipping, o operador assume o controle sobre a promessa de entrega. Os campos de tempo informados sobrepõem os cálculos originais da transportadora para aquele grupo logístico específico, sendo refletidos diretamente no fechamento do pedido.

Auditoria e Rastreabilidade

Todas as regras criadas geram um registro único com updatedAt. Caso múltiplas regras sejam aplicadas ao mesmo objeto, o sistema realiza o recálculo do saldo total respeitando a ordem cronológica de inserção. Para remover um ajuste, deve-se utilizar o endpoint de exclusão, o que disparará o recálculo imediato dos valores do carrinho.

Listagem de Regras do Carrinho (Admin)

Descrição

Este endpoint retorna a lista completa de todos os ajustes manuais ativos no carrinho administrativo.

Ele é essencial para que o operador realize a conferência dos valores antes do fechamento, garantindo que todas as tratativas comerciais (descontos, acréscimos e fretes) estejam aplicadas corretamente.

Além de servir para a interface do usuário, a listagem provê os IDs necessários (cartRuleId) para operações de atualização ou exclusão de regras específicas.

Os registros são retornados com seus respectivos timestamps de última atualização, permitindo auditar quando cada ajuste foi inserido ou modificado.

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Exemplo de Requisição

1curl --request GET \
2  --url '{{MAIN_URL}}/carts/CART123/rules' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": [
4    {
5      "id": 1,
6      "cartId": "CART123",
7      "cartOrderId": null,
8      "cartOrderItemId": null,
9      "cartOrderProductId": null,
10      "description": "Desconto negociado",
11      "rule": "discount",
12      "beginShippingTime": 0,
13      "endShippingTime": 0,
14      "value": 10.00,
15      "updatedAt": "2026-02-12 11:10:00"
16    }
17  ]
18}

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

Criar Regra do Carrinho (Admin)

Descrição

Este endpoint permite a inclusão de um novo ajuste financeiro manual no carrinho administrativo.

Ele é a ferramenta base para que o operador registre condições comerciais negociadas, como descontos por volume, taxas de serviços adicionais ou subsídios de frete.

Ao criar uma regra, o sistema recalcula imediatamente os totais do carrinho, aplicando o valor nominal informado.

Caso a regra possua vínculos com itens ou produtos específicos, o desconto ou acréscimo será rateado ou aplicado exclusivamente àqueles SKUs no momento da geração do pedido.

---

Comportamento do Tipo Shipping

Quando o tipo rule=shipping é selecionado, os campos de tempo tornam-se obrigatórios. Esta ação substitui os valores de cotação logística originais pelo valor customizado, redefinindo o SLA de entrega para o cliente final.

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Parâmetros do Corpo

Exemplo de Requisição

1curl --request POST \
2  --url '{{MAIN_URL}}/carts/CART123/rules' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "description": "Desconto negociado",
7    "rule": "discount",
8    "value": 10
9  }'

✅ Resposta de Sucesso

HTTP Status: 201 Created

1{
2  "status": true,
3  "data": {
4    "id": 1,
5    "cartId": "CART123",
6    "cartOrderId": null,
7    "cartOrderItemId": null,
8    "cartOrderProductId": null,
9    "description": "Desconto negociado",
10    "rule": "discount",
11    "beginShippingTime": 0,
12    "endShippingTime": 0,
13    "value": 10.00,
14    "updatedAt": "2026-02-12 11:10:00"
15  }
16}

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

Atualizar Regra do Carrinho (Admin)

Descrição

Este endpoint permite a modificação de um ajuste financeiro já existente no carrinho.

Ele é comumente utilizado em fluxos de negociação onde o valor do desconto ou a descrição da taxa precisa ser ajustada após uma nova rodada de conversas com o cliente ou aprovação de um gestor.

Qualquer alteração realizada através deste método dispara automaticamente o recálculo do saldo total do carrinho.

Se o tipo da regra for alterado (ex: de discount para addition), as regras de validação correspondentes serão aplicadas rigorosamente, garantindo a integridade dos dados financeiros do rascunho de venda.

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Parâmetros do Corpo

Exemplo de Requisição

1curl --request PUT \
2  --url '{{MAIN_URL}}/carts/CART123/rules/1' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "description": "Desconto negociado atualizado",
7    "rule": "discount",
8    "value": 15
9  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "id": 1,
5    "cartId": "CART123",
6    "cartOrderId": null,
7    "cartOrderItemId": null,
8    "cartOrderProductId": null,
9    "description": "Desconto negociado atualizado",
10    "rule": "discount",
11    "beginShippingTime": 0,
12    "endShippingTime": 0,
13    "value": 15.00,
14    "updatedAt": "2026-02-12 11:20:00"
15  }
16}

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

Remover Regra do Carrinho (Admin)

Descrição

Este endpoint realiza a exclusão definitiva de uma regra de valor customizado do carrinho administrativo.

Ao remover um ajuste, o sistema invalida imediatamente o impacto financeiro daquela regra e dispara o recálculo dos totais do carrinho, restaurando os valores originais (brutos) ou mantendo apenas as demais regras ainda ativas.

Esta operação é irreversível através de rollback. Caso uma regra seja removida por engano, será necessário criar um novo registro com as mesmas propriedades.

A remoção é recomendada sempre que uma negociação for cancelada ou quando um item vinculado à regra for retirado do carrinho.

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Exemplo de Requisição

1curl --request DELETE \
2  --url '{{MAIN_URL}}/carts/CART123/rules/1' \
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:

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.