Pular para o conteúdo principal

Introdução

🎯 O que este módulo faz?​

O módulo Discounts permite que você gerencie e aplique descontos a produtos e pedidos - desde promoções baseadas em porcentagem até reduções de valor fixo - suportando códigos de cupom, descontos por categoria e ofertas específicas para clientes em toda a sua loja de e-commerce.

Pense nisso como seu motor de promoções - defina regras de desconto no painel de administração do OneEntry, aplique-as a produtos ou a pedidos inteiros, valide códigos de cupom no checkout e automatize ajustes de preços para seus clientes.

📖 Explicação Simples​

Toda loja de e-commerce precisa de descontos flexíveis:

  • 🏷️ Descontos Percentuais - 10% de desconto em produtos selecionados
  • 💰 Descontos Fixos - $5 de desconto em pedidos acima de $50
  • 🎟️ Códigos de Cupom - Códigos promocionais para campanhas específicas
  • 📦 Descontos por Categoria - Descontos em categorias inteiras de produtos
  • 👤 Descontos para Clientes - Preços especiais para clientes ou grupos específicos
  • 📅 Ofertas por Tempo Limitado - Vendas com datas de início e término definidas

Problemas sem gerenciamento de descontos:

  • 🔒 Preços Inflexíveis - Necessidade de mudanças de código para cada promoção
  • 📊 Difícil de rastrear - Sem gerenciamento centralizado de descontos
  • 🔄 Sem automação - Atualizações manuais de preços para cada venda

A solução Discounts:

Benefícios:

  • 🔒 Promoções flexíveis - Crie e gerencie descontos no painel de administração
  • 📊 Controle centralizado - Todos os descontos em um só lugar
  • 🔄 Aplicação automatizada - Descontos aplicados automaticamente no checkout
  • 🎟️ Validação de cupons - Verificação de códigos de cupom em tempo real

✨ Conceitos Chave​

O que é um Desconto?​

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

  • Tipo de Desconto - Percentual (por exemplo, 20%) ou valor fixo (por exemplo, $10)
  • Valor do Desconto - O montante ou porcentagem a ser reduzido
  • Marcador - Identificador único para filtragem e referência
  • Período de Validade - Datas de início e término opcionais
  • Código de Cupom - Código promocional opcional para descontos acionados pelo cliente

Estrutura do Desconto​

Cada desconto tem esta estrutura:

{
  id: 1,
  identifier: 'summer_sale',
  localizeInfos: {
    title: 'Summer Sale'
  },
  discountType: 'percentage',
  discountValue: 20,
  isActive: true,
  validFrom: '2025-06-01T00:00:00.000Z',
  validTo: '2025-08-31T23:59:59.999Z',
}

Tipos de Desconto​

TipoDescriçãoExemplo
percentualReduzir o preço por uma porcentagem20% de desconto em todos os itens de verão
fixoReduzir o preço por um valor fixo$10 de desconto em pedidos acima de $50

Operações Comuns de Desconto​

OperaçãoDescriçãoCaso de Uso Exemplo
Obter Todos os DescontosListar todos os descontos disponíveisGerenciamento de descontos no admin
Obter Desconto por MarcadorBuscar um desconto específicoExibir badge de desconto
Validar CupomVerificar se um código de cupom é válidoCampo de cupom no checkout

Por que usar o módulo Discounts?​

BenefícioDescrição
Promoções AutomatizadasSem edição manual de preços para cada venda
Gerenciamento de CuponsCriar, distribuir e validar códigos promocionais
Regras FlexíveisDescontos percentuais, fixos, por categoria ou para clientes
Ofertas com PrazoAgendar campanhas com datas de início/fim
Suporte MultilíngueNomes de descontos localizados por idioma

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

Processo de Criação:

  • Fornecer um Nome - Designação do desconto (obrigatório)
  • Fornecer um Marcador - Identificador único (obrigatório)
  • Selecionar Tipo de Desconto - Percentual ou valor fixo
  • Definir Valor do Desconto - O montante da redução
  • Opcionalmente definir Período de Validade - Datas de início e término

Validação de Cupons​

Use validateDiscountsCoupon() no checkout para verificar códigos de cupom em tempo real antes de aplicá-los a um pedido.

💡 Notas Importantes​

Descontos são Criados no Painel de Administração​

O módulo Discounts gerencia:

  • ✅ Busca todos os descontos ativos
  • ✅ Recupera um desconto específico por marcador
  • ✅ Valida códigos de cupom no checkout
  • ❌ NÃO cria ou modifica descontos (use o painel de administração)

Sua responsabilidade:

  • Exibir badges de desconto nas listagens de produtos
  • Aplicar campos de entrada de cupom no checkout
  • Mostrar totais de desconto no resumo do carrinho/pedido

📊 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

❓ Perguntas Comuns (FAQ)​

Como aplico um desconto no checkout?​

Busque o desconto usando getDiscountByMarker() ou valide um código de cupom com validateDiscountsCoupon(). Use o valor de desconto retornado para calcular o preço reduzido no lado do cliente antes de criar o pedido.

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

Sim! Os descontos podem ter campos opcionais validFrom e validTo. Verifique esses campos ao exibir descontos para garantir que estejam atualmente ativos.

Como mostro badges de desconto nos produtos?​

Busque todos os descontos com getAllDiscounts(), depois combine os descontos aos produtos com base na sua lógica de negócios. Renderize um badge usando o localizeInfos.title e discountValue do desconto.

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

validateDiscountsCoupon() retorna false se o cupom não existir ou tiver expirado. Mostre uma mensagem de erro apropriada ao cliente.

🎓 Melhores Práticas​

  • Cache os descontos ao carregar - Eles mudam com pouca frequência; evite chamadas repetidas à API
  • Valide cupons no lado do servidor - Sempre verifique antes de aplicar a um pedido
  • Mostre o desconto claramente - Exiba os preços originais e com desconto juntos
  • Lide com descontos expirados - Verifique validTo antes de exibir um desconto
  • Use marcadores descritivos - summer_sale_2025, não discount1
  • Localize os nomes dos descontos - Use localizeInfos para suporte multilíngue

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

Definição do módulo Discounts​


const { Discounts } = defineOneEntry(
  "sua-url-do-projeto", {
    "token": "seu-token-de-aplicativo"
  }
);

🔗 Documentação Relacionada​