Discounts

O módulo Discounts permite ler descontos, validar cupons e consultar o saldo de bônus do usuário.

Mais informações sobre a interface do módulo: https://doc.oneentry.cloud/docs/category/discounts (abre em uma nova aba)

---

Use este módulo para buscar descontos e validar códigos de cupom: reduções percentuais ou de valor fixo, acúmulo de pontos de bônus e descontos pessoais. Você define as regras de desconto no painel de administração do OneEntry. O módulo as recupera, valida cupons no checkout e lê o saldo e o histórico de bônus do usuário atual.

O SDK é somente leitura. Não é possível criar ou modificar descontos por meio dele; isso é feito no painel de administração. Ao criar um desconto lá, você define um nome, um marcador (identifier), um tipo (DISCOUNT, BONUS ou PERSONAL_DISCOUNT), um discountValue (PERCENT ou FIXED_AMOUNT mais o value numérico), um período de validade opcional (startDate / endDate) e condições opcionais.

Início rápido

Inicialize o módulo a partir de defineOneEntry:

const {  } = defineOneEntry(
  , {
    
  }
);

Valide um código de cupom no checkout e leia o resultado:

// Validate a coupon code entered by the customer.
const result = await Discounts.validateDiscountsCoupon("SUMMER-KBWZ-2428");

if ('statusCode' in result) {
  console.error(result.message); // IError: the request failed
} else if (result.valid) {
  console.log("Coupon applied:", result.coupon);
} else {
  console.log("Invalid coupon:", result.error); // e.g. "Coupon not found"
}

Objeto de desconto

Um desconto (IDiscountsEntity) é uma regra de preço que reduz o custo de produtos ou pedidos:

• type: DISCOUNT, BONUS ou PERSONAL_DISCOUNT.
• discountValue: como a redução é calculada. Contém um discountType (PERCENT ou FIXED_AMOUNT), um value numérico, uma applicability (TO_PRODUCT ou TO_ORDER) e um maxAmount opcional.
• identifier: o marcador único usado para filtragem e referência.
• startDate / endDate: o período de validade opcional.
• conditions: regras que decidem quando o desconto se aplica (por produto, categoria, valor do carrinho, usuário, …).

{
  id: 1,
  identifier: 'summer_sale',
  localizeInfos: {
    title: 'Summer Sale'
  },
  type: 'DISCOUNT',
  startDate: '2025-06-01T00:00:00.000Z',
  endDate: '2025-08-31T23:59:59.999Z',
  discountValue: {
    applicability: 'TO_ORDER',
    discountType: 'PERCENT',
    value: 20,
    maxAmount: 100
  },
  conditionLogic: 'AND',
  conditions: [
    { id: 1, conditionType: 'MIN_CART_AMOUNT', entityIds: null, value: { amount: 50 } }
  ]
}

Tipos de desconto

O campo type classifica o desconto:

type	Descrição
DISCOUNT	Desconto padrão aplicado a produtos/pedidos
BONUS	Acúmulo de pontos de bônus (fidelidade)
PERSONAL_DISCOUNT	Desconto direcionado a usuários ou grupos específicos

A forma como a redução é calculada é definida em discountValue.discountType:

discountValue.discountType	Descrição	Exemplo
PERCENT	Reduz o preço em uma porcentagem	20% de desconto em todos os itens de verão
FIXED_AMOUNT	Reduz o preço em um valor fixo	$10 de desconto em pedidos acima de $50

---

Métodos

Método	Descrição
getAllDiscounts()	Obter todos os descontos
getDiscountByMarker()	Obter um único desconto pelo marcador
validateDiscountsCoupon()	Validar um código de cupom de desconto
getBonusBalance()	Obter o saldo de bônus do usuário atual
getBonusHistory()	Obter o histórico de transações de bônus do usuário atual
getDiscountsByVectorSearch()	Buscar descontos pelo significado (busca vetorial)

Aplicando um desconto no checkout

Valide o código que o cliente informa com validateDiscountsCoupon() e, em seguida, passe-o como couponCode para Orders.previewOrder() para obter os totais com desconto, e para Orders.createOrder() ao fazer o pedido. Para aplicar um desconto sem cupom, passe o marcador dele em additionalDiscountsMarkers. A plataforma aplica descontos e cupons ao calcular o pedido, então não recalcule os preços no cliente. Use getDiscountByMarker() apenas para exibir um desconto (por exemplo, seu discountValue). createOrder() requer autorização do usuário.

validateDiscountsCoupon() retorna um ICouponValidationResult: { valid: boolean; coupon?; error? }. Se o cupom não existir ou um cupom de uso único já tiver sido usado, valid é false e error contém o motivo (por exemplo, "Coupon not found"). A validação do cupom não verifica startDate/endDate do desconto, então verifique-os você mesmo (veja Período de validade).

Período de validade

startDate e endDate são opcionais. Verifique-os antes de exibir um desconto, para mostrar apenas os descontos que estão ativos no momento.

Selos de desconto nos produtos

Busque todos os descontos com getAllDiscounts(), associe-os aos produtos usando a sua própria lógica de negócio e exiba um selo a partir de localizeInfos.title e discountValue.value. Os descontos mudam com pouca frequência, então armazene-os em cache no carregamento em vez de chamar a API repetidamente. Para nomes em vários idiomas, use localizeInfos.

---

Relacionados

• Products: produtos aos quais os descontos se aplicam
• Orders: pré-visualizar e criar pedidos com descontos aplicados
• Payments: pagamentos de pedidos com desconto
• Locales: nomes de desconto em vários idiomas

---