Cupons
Cupons são códigos promocionais que os clientes podem resgatar para obter descontos em compras e faturas.
Campos do Cupom
| Campo | Descrição |
|---|---|
| Código | Código único, armazenado em maiúsculas |
| Nome | Nome interno do cupom |
| Descrição | Detalhes da promoção |
| Tipo de desconto | percentage (percentual) ou fixed_amount (valor fixo) |
| Valor do desconto | Percentual ou valor em subcents |
| Moeda | Padr��o: BRL |
| Compra mínima | Valor mínimo do pedido para usar o cupom |
| Desconto máximo | Teto do desconto (para cupons percentuais) |
| Limite de uso total | Máximo de resgates permitidos |
| Limite por cliente | Máximo de resgates por conta de cobrança |
| Válido de / até | Período de validade |
| Aplica-se a | Planos e/ou produtos específicos (JSON) |
| Exclui | Planos e/ou produtos excluídos (JSON) |
| Ativo | Se o cupom está habilitado |
Validação de Cupom
Ao validar um cupom, o sistema verifica:
- O cupom existe e o código confere
- O cupom está ativo (
isActive = true) - Está dentro do período de validade
- O limite de uso total não foi atingido
- O limite de uso por cliente não foi atingido
- A compra atinge o valor mínimo
Cálculo do Desconto
Se percentual: desconto = subtotal × percentual / 100
Se fixo: desconto = valor_do_desconto
Aplica teto: desconto = min(desconto, maxDiscountCents)
Não excede subtotal: desconto = min(desconto, subtotal)
Resgatando um Cupom
Ao aplicar um cupom:
- Valida todas as condições
- Cria um registro de
CouponRedemptioncom o valor do desconto - Incrementa o contador de uso do cupom
- Retorna o resgate com o valor descontado
O processo é atômico (transação) para prevenir condições de corrida.
Operações
- Ativar/Desativar: Controla se o cupom pode ser validado
- Deletar: Apenas se nunca utilizado (nenhum resgate registrado)
- Atualizar: Código, nome, limites, datas e valores editáveis
Relatório de Resgates
Para cada cupom, o sistema rastreia:
- Quem resgatou (conta de cobrança)
- Quando resgatou
- Valor do desconto aplicado
- Fatura associada (opcional)
Captura de tela
A tela /dashboard/coupons lista todos os cupons da organização, com código, tipo de desconto, valor, validade, número de resgates e status. A interface permite criar cupons percentuais ou de valor fixo, com limite total e por cliente.
