Pular para o conteúdo principal

Introdução

O módulo Discounts permite que você gerencie e aplique descontos a produtos e pedidos.

Mais informações sobre a interface do usuário do módulo https://doc.oneentry.cloud/docs/category/discounts

🎯 O que este módulo faz?​

O módulo Discounts permite que você recupere descontos e valide códigos de cupom — reduções em porcentagem ou valor fixo, acúmulo de pontos bônus e descontos pessoais. Você define as regras de desconto no painel de administração do OneEntry; este 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: os descontos são criados e configurados no painel de administração.

🚀 Início Rápido​

Inicialize o módulo a partir de defineOneEntry:


const { Discounts } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

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("SUMMER20");

if (result.valid) {
  console.log("Coupon applied:", result.coupon);
} else {
  console.log("Invalid coupon:", result.error);
}

✨ Conceitos Chave​

O que é um Desconto?​

Um Desconto (IDiscountsEntity) é uma regra de precificação que reduz o custo de produtos ou pedidos:

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

Estrutura do Desconto​

{
  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: [
    { type: 'MIN_CART_AMOUNT', value: '50' }
  ]
}

Tipos de Desconto​

O campo type classifica o desconto:

typeDescrição
DISCOUNTDesconto padrão aplicado a produtos/pedidos
BONUSAcúmulo de pontos bônus (fidelidade)
PERSONAL_DISCOUNTDesconto direcionado a usuários ou grupos específicos

Como a redução é calculada está em discountValue.discountType:

discountValue.discountTypeDescriçãoExemplo
PERCENTReduz o preço por uma porcentagem20% de desconto em todos os itens de verão
FIXED_AMOUNTReduz o preço por um valor fixo$10 de desconto em pedidos acima de $50

📋 O que você precisa saber​

Descontos são criados no painel de administração​

Você não pode criar descontos via SDK — eles são criados no painel de administração do OneEntry. Ao criar um, você fornece 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.

O que o módulo faz​

  • ✅ Recupera todos os descontos — getAllDiscounts()
  • ✅ Recupera um desconto específico por marcador — getDiscountByMarker()
  • ✅ Valida códigos de cupom no checkout — validateDiscountsCoupon()
  • ✅ Lê o saldo e o histórico de bônus do usuário atual
  • ❌ Não cria ou modifica descontos (use o painel de administração)

📊 Tabela de Referência Rápida​

MétodoDescrição
getAllDiscounts()Obter todos os descontos
getDiscountByMarker()Obter um único desconto por 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

❓ Perguntas Comuns (FAQ)​

Como aplico um desconto no checkout?​

Recupere o desconto com getDiscountByMarker() ou valide um cupom com validateDiscountsCoupon(), em seguida, use o valor de desconto retornado para calcular o preço reduzido.

Um desconto pode ter uma data de expiração?​

Sim. Os descontos podem ter campos opcionais startDate e endDate — verifique-os antes de exibir um desconto para garantir que ele esteja ativo no momento.

Como mostro distintivos de desconto em produtos?​

Recupere todos os descontos com getAllDiscounts(), combine-os com produtos de acordo com sua lógica de negócios e renderize um distintivo a partir de localizeInfos.title e discountValue.value.

O que acontece se um código de cupom for inválido?​

validateDiscountsCoupon() retorna um ICouponValidationResult — { valid: boolean; coupon?; error? }. Quando o cupom não existe ou expirou, valid é false e uma mensagem de error é fornecida. Verifique result.valid e mostre uma mensagem apropriada.

🎓 Melhores Práticas​

  • Cache os descontos ao carregar — eles mudam com pouca frequência; evite chamadas repetidas à API.
  • Valide cupons antes de aplicar — sempre chame validateDiscountsCoupon() antes de precificar um pedido.
  • Lide com descontos expirados — verifique endDate antes de exibir um desconto.
  • Use marcadores descritivos — summer_sale_2025, não discount1.
  • Localize os nomes dos descontos — use localizeInfos para suporte a múltiplos idiomas.

🔗 Documentação Relacionada​