💸 Documentação de Descontos

📋 Visão Geral

Um desconto define o valor percentual ou absoluto a ser aplicado a uma entidade promocional (cupom ou promoção) conforme a quantidade de itens no carrinho.

Cada desconto é associado a uma faixa de quantidade (itemAmount), permitindo configurar valores progressivos — por exemplo, 10% para 1 item, 20% para 2 itens.

🔄 Entidades Envolvidas

Todo desconto está obrigatoriamente vinculado a uma entidade promocional, identificada pelos campos entityId e entity.

O campo entity aceita dois valores: coupon para vincular o desconto a um cupom, ou promotion para vincular a uma promoção.

A chave primária composta (entityId, entity, itemAmount) garante que cada faixa de quantidade seja única por entidade — não é possível ter dois descontos com o mesmo itemAmount para a mesma entidade.

📐 Conceito de Faixa (itemAmount)

O campo itemAmount representa a faixa de quantidade de itens à qual o desconto se aplica.

Exemplo de configuração progressiva para entityId: 1, entity: coupon:

📌 Notas e Considerações

• Substituição completa no PUT — ao salvar descontos, todos os descontos anteriores da entidade são removidos antes de inserir os novos. Trata-se de uma substituição total, não incremental.
• O campo entity aceita apenas coupon ou promotion. Qualquer outro valor resulta em erro de validação.
• O campo value aceita valores numéricos com até 6 casas decimais.
• Promoções com multiplyItem ativo não suportam múltiplos itens de desconto (máximo 1) e não podem ter desconto direcionado ao frete.

💾 Salvar Descontos

📋 Descrição

Endpoint responsável por salvar os descontos de uma entidade promocional (cupom ou promoção).

Esta operação realiza uma substituição completa — todos os descontos anteriores da entidade (entityId + entity) são removidos antes de inserir os novos itens enviados. Não é uma atualização incremental.

Cada item do array items representa uma faixa de quantidade (itemAmount) com seu respectivo valor de desconto (value). A chave composta (entityId, entity, itemAmount) é única por entidade.

Promoções com multiplyItem ativo têm restrições adicionais: o array items deve conter no máximo 1 elemento e o desconto não pode ser direcionado ao frete.

📝 Parâmetros

🏷️ Headers Obrigatórios

📦 Parâmetros do Corpo

💡 Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/promotionals/discounts \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "entityId": 1,
7    "entity": "coupon",
8    "items": [
9      { "itemAmount": 1, "value": 10 },
10      { "itemAmount": 2, "value": 20 }
11    ]
12  }'

✅ Resposta de Sucesso

HTTP Status: 201 Created

1{
2  "status": true,
3  "data": [
4    { "itemAmount": 1, "value": 10 },
5    { "itemAmount": 2, "value": 20 }
6  ]
7}

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

🗑️ Remoção de Desconto

📋 Descrição

Endpoint responsável por remover um desconto de uma entidade promocional (cupom ou promoção), identificado pela combinação de entity, entityId e itemAmount.

A remoção é precisa e unitária — apenas a faixa correspondente ao itemAmount informado é excluída. Os demais descontos da entidade são preservados.

Quando a remoção é bem-sucedida, o campo data retorna true.

📝 Parâmetros

🏷️ Headers Obrigatórios

📦 Parâmetros do Corpo

💡 Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/promotionals/discounts \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "entityId": 1,
7    "entity": "coupon",
8    "itemAmount": 1
9  }'

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