Cupons

Bem-vindo ao guia completo de Cupons do CMS E-commerce! Este manual detalhado irá guiá-lo através de todas as funcionalidades para criar, gerenciar e monitorar os cupons de desconto do seu catálogo.

---

Visão Geral

A tela de Cupons oferece um conjunto completo de recursos para gerenciar suas promoções:

• 📋 Visualize todos os cupons cadastrados com informações detalhadas
• 🔍 Filtre e busque cupons por código e status de forma eficiente
• ➕ Crie novos cupons com configurações avançadas de uso
• ✏️ Edite cupons existentes para ajustar valores, limites e condições
• 🗑️ Exclua cupons quando necessário
• 📊 Acompanhe o uso em tempo real com histórico detalhado de utilização
• 👥 Restrinja cupons por cliente para promoções personalizadas
• 🛒 Configure limites por usuário e validação de primeira compra
• 📈 Visualize métricas de uso e descontos aplicados

Os cupons são fundamentais para estratégias de marketing, permitindo oferecer descontos por porcentagem, valor fixo ou frete grátis, com total controle sobre regras de uso e público-alvo.

---

Acessando a Tela de Cupons

A tela de cupons está localizada no menu Catálogo do sistema. Ao acessá-la, você verá uma interface completa de gerenciamento com:

Elementos da Interface

Cabeçalho:

• Título "Cupons"
• Subtítulo "Gerencie os cupons de desconto do catálogo"
• Botão "Novo Cupom" (visível apenas para usuários com permissão de criação)

Área de Filtros e Busca:

• Barra de busca por código do cupom (pressione Enter para buscar)
• Filtro de Status (Todos / Ativo / Inativo)
• Seletor de "Cupons por página" (10, 15, 20, 25, 30)

Tabela de Cupons:

• Listagem organizada de todos os cupons
• Paginação automática (quando há mais cupons que o limite por página)
• Linhas clicáveis para acesso rápido aos detalhes

---

Como Buscar e Filtrar Cupons

Busca por Código

A barra de busca permite encontrar cupons específicos de forma rápida e eficiente:

Como usar:

1. Localize o campo de busca com ícone de lupa
2. Digite o código do cupom (ex: "DESCONTO20", "BLACKFRIDAY")
3. Pressione Enter para executar a busca
4. Os resultados serão filtrados automaticamente
5. A página será redefinida para a primeira página de resultados

Dicas de Busca

• A busca funciona com códigos parciais: digite "DESC" para encontrar cupons que contenham essa sequência
• A busca não diferencia maiúsculas de minúsculas
• Para limpar a busca, apague o texto e pressione Enter novamente
• A busca é realizada apenas após pressionar Enter (não é automática ao digitar)

---

Filtro por Status

O filtro de status permite visualizar cupons em estados específicos:

Status Disponíveis:

• ✅ Ativo (valor: 1): Cupons ativos e disponíveis para uso pelos clientes
• ❌ Inativo (valor: 0): Cupons desativados temporariamente
• 📋 Todos: Exibe todos os cupons independente do status

Como filtrar:

1. Localize o filtro ao lado do ícone de funil (Filter)
2. Clique no seletor de "Status"
3. Escolha uma das opções disponíveis
4. A tabela será atualizada automaticamente
5. A paginação retornará para a primeira página

Comportamento do Filtro

Ao alterar o filtro de status, a página atual é automaticamente redefinida para 1, garantindo que você veja os resultados desde o início.

---

Seletor de Cupons por Página

Controle quantos cupons são exibidos simultaneamente na tabela:

Como usar:

1. Localize o seletor "Cupons por página" no canto direito da barra de filtros
2. Escolha entre as opções: 10, 15, 20, 25 ou 30 cupons por página
3. A visualização será atualizada imediatamente
4. A paginação será recalculada conforme a nova quantidade
5. Você será redirecionado para a primeira página

Quando usar:

• 10 cupons: Para análise mais focada e detalhada
• 15-20 cupons: Visualização balanceada (padrão: 10)
• 25-30 cupons: Para ter uma visão mais ampla do catálogo

Dica de Performance

Se você tem muitos cupons cadastrados, escolher uma quantidade menor por página pode melhorar a velocidade de carregamento.

---

Entendendo a Tabela de Cupons

A tabela apresenta uma visão clara e organizada de todos os cupons cadastrados:

Colunas da Tabela

Coluna	Descrição	Informação Exibida
Código	Código único do cupom	Em destaque e negrito
Tipo	Categoria do cupom	Etiqueta cinza
Desconto	Valor ou percentual do desconto	Texto verde destacado
Status	Estado atual do cupom (Ativo/Inativo)	Etiqueta azul ou cinza

Detalhamento das Colunas

1. Código:

• Exibido em destaque e negrito para fácil identificação
• Exemplos: DESCONTO20, BLACKFRIDAY, VIP50

2. Tipo:

• Mostra a categoria do cupom em uma etiqueta
• Opções:
  • Porcentagem: Para descontos percentuais
  • Valor Fixo: Para descontos em valor específico
  • Frete Grátis: Para isenção de frete

3. Desconto:

• Exibido em verde para destacar o benefício oferecido
• Formatos de exibição:
  • Porcentagem: 20%
  • Valor Fixo: R$ 50
  • Frete Grátis: Frete Grátis

4. Status:

• Etiqueta visual que indica a disponibilidade do cupom
• Ativo: Etiqueta azul - cupom disponível para uso
• Inativo: Etiqueta cinza - cupom desabilitado

Indicadores Visuais e Interatividade

✨ Recursos Visuais:

• Cada tipo de cupom tem etiqueta distintiva para rápida identificação
• Valores de desconto em verde chamam atenção para o benefício
• Status coloridos facilitam identificação de cupons ativos/inativos
• Design que se adapta a diferentes tamanhos de tela

🖱️ Interatividade:

• Ao passar o mouse: As linhas mudam para um fundo cinza claro
• Clique: Clicar em qualquer linha abre a página de detalhes do cupom
• Cursor: O cursor muda para indicar que a linha é clicável

Estados da Tabela

Tabela vazia (sem cupons):

• Ícone de ticket cinza centralizado
• Mensagem: "Nenhum cupom cadastrado" (se não houver filtros)
• Mensagem: "Nenhum cupom encontrado com esse filtro" (se houver filtros ativos)

Carregando:

• Spinner animado circular com borda azul
• Mensagem: "Carregando cupons..."

Erro:

• Ícone de ticket cinza
• Mensagem: "Erro ao carregar cupons. Tente novamente."

Paginação

Quando há mais cupons que o limite por página, um componente de paginação aparece automaticamente:

• Exibido apenas se totalPages > 1
• Mostra página atual, total de itens e itens por página
• Permite navegação entre páginas
• Nome do conteúdo: "Cupom" (usado na exibição de informações)

---

Como Criar um Novo Cupom

O processo de criação de cupons foi aprimorado com recursos avançados de configuração. O modal de criação possui quatro seções principais:

Passo a Passo Completo

Passo 1: Abrindo o Modal de Criação

1. Localize o botão "Novo Cupom" no canto superior direito da tela
2. Este botão só é visível para usuários com permissão de inserção (action="insert")
3. Clique no botão para abrir o modal de criação

Permissões

O botão "Novo Cupom" é protegido por controle de acessoe só aparece se você tiver permissão na aplicação.

---

Passo 2: Seção "Informações Básicas"

Preencha os dados fundamentais do cupom:

1. Código * (obrigatório)

• Campo de texto que converte automaticamente para letras maiúsculas
• Aceita apenas: letras, números e caracteres especiais (%, ., -, _)
• Exemplo: DESCONTO20, BLACKFRIDAY-2024, VIP_50
• Sugestão de preenchimento: "Ex: DESCONTO20"

2. Tipo * (obrigatório)

• Selecione uma das 3 opções disponíveis:
  • Porcentagem: Desconto percentual sobre o valor
  • Valor Fixo: Desconto em reais
  • Frete Grátis: Isenção do frete

3. Desconto (condicional)

• Aparece apenas se o tipo for "Porcentagem" ou "Valor Fixo"
• Não aparece se o tipo for "Frete Grátis"
• Aceita números com até 2 casas decimais
• Para Porcentagem: Digite o valor em % (Ex: 20)
  • Sugestão: "Ex: 20"
  • Campo: "Desconto (%)"
• Para Valor Fixo: Digite o valor em R$ (Ex: 50.00)
  • Sugestão: "Ex: 50.00"
  • Campo: "Desconto (R$)"

4. Status * (obrigatório)

• Valor padrão: "1" (Ativo)
• Opções:
  • Ativo (valor: 1): Cupom disponível para uso imediato
  • Inativo (valor: 0): Cupom desabilitado

5. Descrição (opcional)

• Campo de texto com múltiplas linhas
• Use para detalhar as condições e objetivo da promoção
• Sugestão: "Descreva o cupom e suas condições (opcional)"
• Exemplo: "Cupom de 20% de desconto para primeira compra, válido apenas para produtos selecionados"

Dica de Código

Use códigos claros e memoráveis. Evite sequências complexas que os clientes possam digitar errado.

---

Passo 3: Seção "Restrições e Limites"

Configure as regras de uso e limitações do cupom:

1. Valor Mínimo da Compra (R$) (opcional)

• Define o valor mínimo do carrinho para aplicar o cupom
• Exemplo: 100.00 (cliente precisa ter pelo menos R$ 100,00 no carrinho)
• Sugestão: "Ex: 100.00"
• Se deixado em branco, não há valor mínimo

2. Desconto Máximo (R$) (opcional - apenas para tipo Porcentagem)

• Campo exibido apenas quando o tipo é "Porcentagem"
• Limita o valor máximo de desconto em reais
• Sugestão: "Ex: 200.00"
• Exemplo prático:
  • Cupom de 20% com desconto máximo de R$ 200
  • Compra de R$ 2.000: desconto seria R$ 400 (20%), mas será limitado a R$ 200
  • Compra de R$ 500: desconto será R$ 100 (20%)

3. Limite de Uso Total * (obrigatório)

• Define quantas vezes o cupom pode ser usado no total (por todos os clientes)
• Sugestão: "Ex: 100"
• Informação: "Limite total de usos do cupom"
• Exemplo: 100 (após 100 usos, o cupom para de funcionar)

4. Limite por Usuário (opcional)

• Define quantas vezes cada cliente pode usar este cupom
• Sugestão: "Ex: 1"
• Informação: "Quantas vezes cada usuário pode usar este cupom"
• Exemplo: 1 (cada cliente só pode usar uma vez)
• Se deixado em branco, não há limite por usuário

5. Válido apenas para primeira compra (opção marcável)

• Marque esta opção se desejar que o cupom seja válido apenas para primeira compra
• Quando marcado, o cupom só funciona para clientes em sua primeira compra
• Texto: "Válido apenas para primeira compra"
• Informação: "Este cupom só poderá ser usado por clientes em sua primeira compra"

Estratégia de Limitação

Combine "Limite de Uso Total" com "Limite por Usuário" para controlar campanhas. Exemplo: 100 usos totais + 1 uso por usuário = até 100 clientes diferentes.

---

Passo 4: Seção "Clientes Permitidos"

Configure se o cupom é para todos ou para clientes específicos:

Funcionalidade:

• Por padrão, se nenhum cliente for selecionado, o cupom fica disponível para todos
• Você pode selecionar clientes específicos que poderão usar o cupom

Como selecionar clientes:

1. Clique no botão "Selecionar Clientes"

   • Ícone: Users (ícone de usuários)
   • O botão mostra a quantidade de clientes selecionados: (0), (3), etc.

2. Um modal secundário será aberto com:

   • Título: "Selecionar Clientes"
   • Descrição: "Escolha os clientes que poderão usar este cupom"
   • Campo de busca por nome ou e-mail
   • Lista de clientes com checkboxes

3. Buscar clientes:

   • Digite no campo de busca para filtrar por nome ou e-mail
   • A busca é realizada em tempo real
   • Carrega até 50 clientes ativos por vez

4. Selecionar/desselecionar:

   • Clique no checkbox ou na área do cliente
   • Clientes selecionados ficam marcados
   • Você pode selecionar múltiplos clientes

5. Confirmar seleção:

   • Contador mostra quantos clientes estão selecionados
   • Botão "Cancelar": fecha o modal sem salvar alterações
   • Botão "Confirmar": aplica a seleção e fecha o modal

Visualização dos clientes selecionados:

• Após selecionar, aparece a lista "Clientes selecionados:"
• Cada cliente é exibido em um badge cinza
• Cada badge tem um botão "X" para remover o cliente
• Mostra o nome completo ou razão social conforme tipo de entidade

Estados do modal de clientes:

• Carregando: Spinner com mensagem "Carregando clientes..."
• Vazio: Ícone de usuários + "Nenhum cliente encontrado"
• Com resultados: Lista rolável com os clientes

Clientes Permitidos

Esta funcionalidade é ideal para cupons VIP, promoções exclusivas ou campanhas direcionadas a um grupo específico de clientes.

---

Passo 5: Seção "Período de Validade"

Defina quando o cupom estará ativo:

1. Válido De * (obrigatório)

• Selecione a data e hora de início da validade do cupom
• O cupom não pode ser usado antes desta data/hora

2. Válido Até * (obrigatório)

• Selecione a data e hora de término da validade do cupom
• O cupom não pode ser usado após esta data/hora

Validação de Datas

Certifique-se de que "Válido Até" é posterior a "Válido De". O sistema valida essas datas através do schema de validação.

---

Passo 6: Revisar e Confirmar

Antes de criar:

1. Role todo o formulário e revise todas as informações preenchidas
2. Verifique se todos os campos obrigatórios (marcados com *) estão preenchidos
3. Confirme que as datas estão corretas
4. Valide os valores de desconto e limites

Botões do rodapé:

• Cancelar: Fecha o modal sem salvar (volta para a lista de cupons)
• Criar Cupom: Envia os dados e cria o cupom
  • Durante o processamento, o botão exibe "Criando..."
  • Ambos os botões ficam desabilitados durante a criação

Após a criação bem-sucedida:

1. O formulário é resetado (form.reset())
2. A lista de clientes selecionados é limpa
3. O modal é fechado automaticamente
4. Você é redirecionado para a página de detalhes do cupom criado: /catalog/coupons/{couponId}

Após a Criação

O redirecionamento automático permite que você visualize imediatamente todas as informações do cupom recém-criado, incluindo seu ID, informações de auditoria e status inicial de uso (0 usos).

---

Validações do Formulário

O formulário verifica automaticamente se os dados estão corretos:

• Validação ao digitar: Campos são validados enquanto você preenche
• Mensagens de erro: Aparecem em vermelho abaixo de cada campo com problema
• Botão desabilitado: O botão "Criar Cupom" só fica habilitado quando todos os dados estão corretos
• Campos obrigatórios: Código, Tipo, Status, Limite de Uso, Válido De, Válido Até
• Campos condicionais: Desconto é obrigatório para Porcentagem e Valor Fixo

---

Visualizando Detalhes de um Cupom

A página de detalhes oferece uma visão completa e organizada de todas as informações do cupom.

Como Acessar os Detalhes

1. Na lista de cupons, clique em qualquer linha da tabela
2. Você será automaticamente redirecionado para /catalog/coupons/{couponId}
3. A página carregará todos os detalhes do cupom selecionado

---

Layout da Página

A página de detalhes é organizada em:

• Botão Voltar (topo da página)
• Cabeçalho com informações principais
• Coluna Esquerda (2/3 da largura): Cards de informações principais
• Coluna Direita (1/3 da largura): Cards complementares
• Seção Completa (largura total): Histórico de Uso

---

1. Cabeçalho da Página

Localizado no topo, o cabeçalho apresenta:

Lado Esquerdo:

• 🎫 Ícone de Ticket azul em destaque
• Código do cupom em tamanho grande e negrito
• Etiqueta de Status:
  • Ativo: Etiqueta azul
  • Inativo: Etiqueta cinza
• Subtítulo: "Informações detalhadas do cupom"

Lado Direito (Botões de Ação):

• Botão Editar:
  • Botão com contorno e ícone de lápis
  • Texto: "Editar"
  • Visível apenas se você tiver permissão para editar
• Botão Excluir:
  • Botão vermelho com ícone de lixeira
  • Texto: "Excluir"
  • Visível apenas se você tiver permissão para excluir

---

2. Card "Informações Básicas"

Título: "Informações Básicas" com ícone Info

Conteúdo:

1. ID do Cupom e Código (lado a lado):

   • ID: Campo em cinza apenas para visualização
   • Código: Campo em destaque e negrito

2. Tipo de Cupom:

   • Etiqueta com ícone de tag
   • Opções: "Porcentagem", "Valor Fixo", "Frete Grátis"

3. Descrição:

   • Ícone de documento
   • Se houver descrição: exibida em área destacada
   • Se vazio: texto "Sem descrição" em cinza

4. Restrições de Uso:

   Limite por usuário (se configurado):

   • Área destacada em cinza claro
   • Título em maiúsculas
   • Valor em destaque: "X uso(s)"

   Primeira compra apenas (se ativo):

   • Aviso azul com ícone de sacola
   • Mensagem: "Este cupom é válido apenas para a primeira compra do cliente"

   Clientes Permitidos (se houver):

   • Área com ícone de usuários
   • Mostra até 5 clientes com:
     • Ícone de usuário
     • Nome completo do cliente
     • E-mail do cliente
   • Se houver mais de 5: mostra "+X cliente(s) a mais"

---

3. Card "Valor do Desconto"

Título: "Valor do Desconto" com ícone TrendingUp

Conteúdo:

• Área destacada com fundo cinza claro
• Ícone circular grande com fundo verde claro:
  • Porcentagem: ícone de percentual
  • Valor Fixo: ícone de cifrão
  • Frete Grátis: ícone de pacote
• Valor principal em verde, grande e negrito:
  • Porcentagem: "20%"
  • Valor Fixo: "R$ 50"
  • Frete Grátis: "Frete Grátis"
• Etiqueta do tipo ao lado
• Informação adicional (se porcentagem com desconto máximo):
  • "Desconto máximo: R$ X"

---

4. Card "Uso do Cupom"

Título: "Uso do Cupom" com ícone ShoppingCart

Conteúdo:

Dois cards lado a lado:

1. Total de usos:

   • Fundo cinza claro com borda
   • Título em maiúsculas
   • Valor grande em negrito: "X / Y"

2. Usos disponíveis:

   • Mesmo estilo
   • Valor: usos restantes (Y - X)

Barra de Progresso:

• Cabeçalho: "Progresso de uso" e porcentagem "X%"
• Barra cinza de fundo
• Barra azul que preenche conforme o uso
• Mostra visualmente quantos % do limite foi usado
• Animação suave ao atualizar

Atualização em Tempo Real

Os valores de uso são atualizados automaticamente quando a página é recarregada, refletindo o uso atual do cupom pelos clientes.

---

5. Card "Período de Validade" (Coluna Direita)

Título: "Período de Validade" com ícone Calendar

Conteúdo (dois cards internos):

1. Válido de:

   • Título: "VÁLIDO DE"
   • Valor: formatado como "dd/MM/yyyy às HH:mm"

2. Válido até:

   • Título: "VÁLIDO ATÉ"
   • Valor: formatado como "dd/MM/yyyy às HH:mm"

---

6. Card "Restrições" (Coluna Direita - Condicional)

Título: "Restrições" com ícone DollarSign

Condição de Exibição: Só aparece se minValue OU maxDiscount estiverem definidos

Conteúdo:

1. Valor mínimo da compra (se existir):

   • Título em maiúsculas
   • Valor: "R$ X"

2. Desconto máximo (se existir e tipo for porcentagem):

   • Título em maiúsculas
   • Valor: "R$ X"

Exibição Condicional

Este card só é renderizado quando há pelo menos uma restrição configurada.

---

7. Card "Informações de Auditoria" (Coluna Direita)

Título: "Informações de Auditoria" com ícone User

Seção 1 - Criação (sempre presente):

• Área cinza claro com borda
• Título: "CRIAÇÃO"
• Criado por: Nome do usuário
• Data de criação: Formatada como "dd/MM/yyyy às HH:mm"

Seção 2 - Última Atualização (se houver):

• Só aparece se o cupom já foi atualizado
• Título: "ÚLTIMA ATUALIZAÇÃO"
• Atualizado por: Nome do usuário ou "-"
• Data de atualização: Formatada ou "-"

---

8. Card "Histórico de Uso" (Largura Completa)

Esta é uma seção completamente nova e detalhada que mostra todos os usos do cupom.

Título: "Histórico de Uso" com ícone History (roxo) Subtítulo: "Acompanhe todos os clientes e pedidos que utilizaram este cupom"

Cabeçalho do Card

Lado Esquerdo: Título e subtítulo Lado Direito: Seletor "Registros por página" (10, 15, 20, 25, 30)

Estatísticas Gerais (Três Cards)

Três cards com cores diferentes e ícones:

1. Total de Usos (Azul):

   • Card com fundo azul claro
   • Ícone de usuários em círculo azul
   • Valor grande em negrito
   • Mostra quantas vezes o cupom foi usado

2. Pedidos Gerados (Roxo):

   • Card com fundo roxo claro
   • Ícone de sacola de compras em círculo roxo
   • Mostra quantidade de pedidos que usaram o cupom

3. Desconto Total (Verde):

   • Card com fundo verde claro
   • Ícone de tendência descendente em círculo verde
   • Valor: "R$ X.XX" formatado
   • Mostra o valor total de descontos concedidos

Tabela de Histórico

Colunas:

Coluna	Largura Mínima	Conteúdo
Cliente	200px	Avatar + Nome + ID do cliente
E-mail	250px	E-mail do cliente
Referência do Pedido	200px	Link clicável para o pedido
Desconto Aplicado	140px	Valor em R$ (alinhado à direita)

Linha da Tabela:

• Ao passar o mouse: fundo cinza claro
• Cliente:
  • Avatar circular com fundo azul
  • Ícone de usuários dentro do avatar
  • Nome em negrito
  • ID em texto pequeno
• E-mail:
  • Texto simples
• Referência do Pedido:
  • Botão clicável com ícone de link externo
  • Clique: abre os detalhes do pedido em nova aba
• Desconto Aplicado:
  • Etiqueta verde claro
  • Texto verde escuro e negrito
  • Formato: "R$ X.XX"

Estados do Histórico

Sem registros:

• Ícone ShoppingBag grande e cinza
• Título: "Nenhum uso registrado"
• Subtítulo: "Este cupom ainda não foi utilizado por nenhum cliente"

Carregando:

• Spinner animado azul
• Mensagem: "Carregando histórico..."

Erro:

• Ícone History cinza
• Mensagem: "Erro ao carregar histórico. Tente novamente."

Paginação

• Aparece apenas se totalPages > 1
• Com borda superior cinza
• Nome do conteúdo: "Registro"
• Mostra página atual, total e permite navegação

Navegação para Pedidos

Ao clicar na referência de um pedido, uma nova aba é aberta automaticamente com os detalhes completos do pedido, permitindo análise sem perder a visualização do histórico do cupom.

---

Estados de Carregamento e Erro

Carregando Detalhes:

• Spinner circular animado azul
• Mensagem: "Carregando detalhes do cupom..."

Cupom Não Encontrado:

• Ícone Ticket grande e cinza
• Mensagem: "Cupom não encontrado. Verifique o ID e tente novamente."

Erro ao Carregar:

• Ícone Ticket grande e cinza
• Mensagem: "Erro ao carregar cupons. Tente novamente."

---

Como Editar um Cupom

O processo de edição é similar ao de criação, mas com os dados já preenchidos.

Passo a Passo para Editar

Passo 1: Acessar o Modal de Edição

1. Na lista de cupons, clique no cupom desejado para ver seus detalhes
2. Na página de detalhes, localize o botão "Editar" no canto superior direito
3. O botão só é visível se você tiver permissão de atualização (action="update")
4. Clique no botão para abrir o modal de edição

Permissão

O botão "Editar" é protegido por controle de acesso e só aparece para usuários com permissão de atualização na aplicação CouponsAdministration.

---

Passo 2: Revisar e Modificar os Dados

O modal de edição abre com todos os dados atuais já preenchidos, organizados nas mesmas 4 seções do modal de criação:

1. Seção "Informações Básicas":

• Código do cupom (editável)
• Tipo do cupom (editável)
• Valor do desconto (editável, condicional ao tipo)
• Status (Ativo/Inativo)
• Descrição (opcional)

2. Seção "Restrições e Limites":

• Valor mínimo da compra (R$)
• Desconto máximo (R$) - apenas para porcentagem
• Limite de uso total
• Limite por usuário
• Checkbox "Válido apenas para primeira compra"

3. Seção "Clientes Permitidos":

• Botão "Selecionar Clientes" mostra quantidade atual
• Clientes já selecionados aparecem em badges
• Possibilidade de adicionar ou remover clientes
• Modal secundário para busca e seleção

4. Seção "Período de Validade":

• Válido De (data e hora)
• Válido Até (data e hora)
• Datas são pré-formatadas corretamente do banco

Cuidados ao Editar

• Alterar o tipo pode causar inconsistências se o cupom já foi usado
• Reduzir o limite de uso para menos que o já utilizado pode gerar erros
• Modificar o código pode confundir clientes que já conhecem o cupom
• Alterar clientes permitidos pode frustrar quem já tinha acesso
• Mudar datas pode invalidar campanhas de marketing em andamento

Sempre avalie o impacto antes de editar um cupom ativo!

---

Passo 3: Confirmar as Alterações

Antes de salvar:

1. Revise cuidadosamente todas as modificações
2. Confirme que os campos obrigatórios estão preenchidos
3. Valide que as datas estão corretas
4. Verifique se os limites fazem sentido com o uso atual

Botões do rodapé:

• Cancelar: Fecha o modal sem salvar alterações
• Atualizar Cupom: Salva as modificações
  • Durante o processamento: "Atualizando..."
  • Ambos os botões ficam desabilitados durante a atualização

Após atualização bem-sucedida:

1. O modal é fechado automaticamente
2. A página de detalhes é atualizada com os novos dados
3. Você permanece na mesma página (não há redirecionamento)
4. As informações de auditoria são atualizadas:
   • "Atualizado por": seu nome de usuário
   • "Data de atualização": data e hora atual

Após Editar

Diferente da criação, após editar você permanece na página de detalhes para visualizar imediatamente as alterações aplicadas. O card de auditoria mostrará quem fez a última modificação e quando.

---

Como Excluir um Cupom

Passo a Passo para Excluir

Importante

A exclusão de um cupom é uma ação irreversível. Cupons excluídos não podem ser recuperados.

Passo 1: Acesse os Detalhes

1. Clique no cupom desejado na tabela
2. Na tela de detalhes, clique no botão "Excluir" (vermelho)

Passo 2: Confirme a Exclusão

Um diálogo de confirmação será exibido com:

• Título: "Confirmar exclusão"
• Mensagem: Confirmação com o código do cupom
• Aviso: "Esta ação não pode ser desfeita"

Passo 3: Finalize a Exclusão

1. Leia atentamente o aviso
2. Clique em "Excluir" para confirmar (ou "Cancelar" para desistir)
3. Aguarde o processamento (você verá "Excluindo...")
4. Você será redirecionado para a lista de cupons

---

Casos de Uso Práticos

1. Criar Cupom Exclusivo de Primeira Compra

Situação: Você quer incentivar novos clientes com 15% de desconto apenas em sua primeira compra.

Como fazer:

1. Clique em "Novo Cupom"
2. Seção "Informações Básicas":
   • Código: PRIMEIRA15
   • Tipo: Porcentagem
   • Desconto: 15
   • Status: Ativo
   • Descrição: "15% de desconto exclusivo para primeira compra"
3. Seção "Restrições e Limites":
   • Valor Mínimo: 50.00
   • Desconto Máximo: 100.00
   • Limite de Uso Total: 500
   • Limite por Usuário: 1
   • ✅ Marque "Válido apenas para primeira compra"
4. Seção "Clientes Permitidos":
   • Deixe vazio (disponível para todos)
5. Seção "Período de Validade":
   • Configure início e fim (ex: 30 dias)
6. Clique em "Criar Cupom"

Resultado: Cupom que só pode ser usado uma vez por cliente e apenas em sua primeira compra.

---

2. Criar Cupom de Frete Grátis para Black Friday

Situação: Oferecer frete grátis durante a Black Friday.

Como fazer:

1. Clique em "Novo Cupom"
2. Código: BLACKFRIDAY2024
3. Tipo: Frete Grátis
4. Status: Ativo
5. Descrição: "Frete grátis para toda a loja na Black Friday"
6. Valor Mínimo: 100.00 (apenas compras acima de R$ 100)
7. Limite de Uso: 1000
8. Válido De: 29/11/2024 às 00:00
9. Válido Até: 29/11/2024 às 23:59
10. Clique em "Criar Cupom"

---

3. Criar Cupom VIP para Clientes Específicos

Situação: Dar R$ 50 de desconto exclusivamente para um grupo selecionado de clientes VIP.

Como fazer:

1. Clique em "Novo Cupom"
2. Seção "Informações Básicas":
   • Código: VIP50EXCLUSIVO
   • Tipo: Valor Fixo
   • Desconto: 50.00
   • Status: Ativo
   • Descrição: "R$ 50 de desconto exclusivo para clientes VIP selecionados"
3. Seção "Restrições e Limites":
   • Valor Mínimo: 200.00
   • Limite de Uso Total: 100
   • Limite por Usuário: 2 (cada VIP pode usar 2 vezes)
4. Seção "Clientes Permitidos":
   • Clique em "Selecionar Clientes"
   • Busque e selecione os clientes VIP (ex: 15 clientes)
   • Clique em "Confirmar"
5. Seção "Período de Validade":
   • Configure validade para 30 dias
6. Clique em "Criar Cupom"

Resultado: Cupom exclusivo que só pode ser usado pelos 15 clientes selecionados, até 2 vezes cada.

Dica: Use o histórico de uso para acompanhar quais clientes VIP já utilizaram o cupom.

---

4. Desativar Cupom Temporariamente

Situação: Pausar um cupom sem excluí-lo.

Como fazer:

1. Encontre o cupom na lista
2. Clique para ver os detalhes
3. Clique em "Editar"
4. Altere Status para Inativo
5. Clique em "Atualizar Cupom"

---

5. Analisar Histórico de Uso de um Cupom

Situação: Verificar quais clientes usaram um cupom e em quais pedidos.

Como fazer:

1. Na lista de cupons, clique no cupom desejado
2. Na página de detalhes, role até o card "Histórico de Uso"
3. Visualize as estatísticas gerais:
   • Total de Usos
   • Pedidos Gerados
   • Desconto Total aplicado
4. Na tabela, veja:
   • Nome e ID de cada cliente que usou
   • E-mail do cliente
   • Referência do pedido
   • Valor do desconto aplicado naquele pedido
5. Para ver detalhes de um pedido específico:
   • Clique na referência do pedido
   • Uma nova aba abrirá com os detalhes completos
6. Use o seletor "Registros por página" para ajustar a visualização
7. Navegue entre páginas se houver muitos usos

Resultado: Visão completa de como o cupom foi utilizado, permitindo análise de ROI e identificação de padrões de uso.

---

6. Buscar Cupons Inativos

Situação: Ver todos os cupons que estão desativados.

Como fazer:

1. Na tela principal de cupons
2. Clique no filtro "Status"
3. Selecione "Inativo"
4. Veja todos os cupons inativos na tabela
5. Clique em "Todos" para remover o filtro

---

Problemas Comuns e Soluções

❌ "Nenhum cupom cadastrado"

Problema: A tabela está vazia e não há cupons cadastrados.

Soluções:

• Se for seu primeiro acesso, crie cupons clicando em "Novo Cupom"
• Se você aplicou filtros, remova-os para ver todos os cupons
• Verifique se você tem permissão para visualizar cupons

---

❌ "Nenhum cupom encontrado com esse filtro"

Problema: A busca ou filtro não retornou resultados.

Soluções:

• Verifique a ortografia do código buscado
• Tente códigos mais genéricos (ex: "DESC" em vez de "DESCONTO20COMPLETO")
• Remova o filtro de status se estiver ativo
• Pressione Enter após digitar o código de busca

---

❌ Erro ao criar cupom

Problema: O botão "Criar Cupom" está desabilitado ou apresenta erro.

Soluções:

• Verifique se todos os campos obrigatórios estão preenchidos:
  • ✅ Código
  • ✅ Tipo
  • ✅ Desconto (exceto para Frete Grátis)
  • ✅ Status
  • ✅ Limite de Uso
  • ✅ Válido De
  • ✅ Válido Até
• Certifique-se de que o código segue o formato correto (apenas letras, números e %, ., -, _)
• Verifique se a data "Válido Até" é posterior a "Válido De"
• Verifique se você tem permissão para criar cupons

---

❌ Cupom não pode ser usado pelos clientes

Problema: Clientes reclamam que o cupom não funciona.

Possíveis causas e soluções:

1. Status Inativo: Verifique se o cupom está com status "Ativo"
2. Fora do período de validade: Verifique as datas "Válido De" e "Válido Até"
3. Limite de uso atingido: Verifique o card "Uso do Cupom" nos detalhes
4. Valor mínimo não atingido: Cliente precisa comprar o valor mínimo configurado
5. Código digitado incorretamente: Confirme o código exato com o cliente

---

❌ Não consigo editar um cupom

Problema: O botão "Editar" não aparece ou está desabilitado.

Soluções:

• Verifique se você tem permissão para editar cupons
• Certifique-se de que está na tela de detalhes do cupom
• Recarregue a página e tente novamente
• Entre em contato com o administrador do sistema para verificar suas permissões

---

❌ Erro ao excluir cupom

Problema: A exclusão falha ou retorna erro.

Possíveis causas:

• O cupom pode estar sendo usado ativamente por clientes
• Você pode não ter permissão para excluir cupons
• Pode haver pedidos vinculados a este cupom

Soluções:

• Se o cupom está em uso, considere desativá-lo em vez de excluir
• Verifique suas permissões com o administrador
• Entre em contato com o suporte técnico se o problema persistir

---

Entendendo os Tipos de Cupons

Porcentagem

Quando usar: Para dar desconto percentual sobre o valor da compra.

Características:

• Desconto calculado como % do valor total
• Pode ter desconto máximo em R$ para limitar perdas
• Ideal para promoções gerais
• Exemplos: 10%, 20%, 50%

Cenários ideais:

• Promoções sazonais (Black Friday, Natal)
• Cupons de primeira compra
• Campanhas de aniversário da loja

---

Valor Fixo

Quando usar: Para dar desconto de um valor específico em reais.

Características:

• Desconto de valor fixo independente do total da compra
• Simples e direto para o cliente entender
• Ideal para cupons de boas-vindas ou fidelidade
• Exemplos: R$ 20, R$ 50, R$ 100

Cenários ideais:

• Cupons de boas-vindas
• Recompensas para clientes VIP
• Compensações por problemas

---

Frete Grátis

Quando usar: Para isentar o cliente do custo de frete.

Características:

• Remove completamente o valor do frete
• Não afeta o valor dos produtos
• Altamente atrativo para clientes
• Incentiva compras de maior ticket

Cenários ideais:

• Campanhas de frete grátis
• Incentivar compras acima de determinado valor
• Promoções especiais para produtos com frete alto

---

Boas Práticas

📝 Nomenclatura de Códigos

1. Use códigos claros e memoráveis

   • ✅ PRIMEIRA15, BLACKFRIDAY, FRETEGRATIS
   • ❌ XYZ123, AAA, TEMP

2. Inclua o valor ou tipo no código quando possível

   • ✅ DESC20 (indica 20% de desconto)
   • ✅ 50REAIS (indica R$ 50 de desconto)

3. Use padrões consistentes

   • Se usar PRIMEIRA15, use também SEGUNDA15, TERCEIRA15
   • Mantenha um padrão de nomenclatura em toda a loja

4. Evite caracteres especiais complexos

   • Prefira letras, números e hífens
   • Evite caracteres que possam confundir (0 vs O, 1 vs l)

Exemplos corretos:

• ✅ DESCONTO20
• ✅ NATAL-2024
• ✅ VIP_50
• ✅ FRETE.GRATIS

Exemplos a evitar:

• ❌ dEsCoNtO20 (uso inconsistente de maiúsculas)
• ❌ @#$%! (caracteres especiais não permitidos)
• ❌ a1b2c3 (difícil de lembrar e comunicar)

---

🎯 Configuração de Valores

1. Defina limites claros para cupons de porcentagem

   • Sempre use "Desconto Máximo" para evitar perdas excessivas
   • Exemplo: 20% com máximo de R$ 200

2. Configure valores mínimos estrategicamente

   • Use para aumentar o ticket médio
   • Exemplo: Frete grátis acima de R$ 150

3. Limite o uso adequadamente

   • Campanhas rápidas: limite baixo (50-100 usos)
   • Campanhas longas: limite alto (500-1000 usos)
   • Cupons VIP: limite muito baixo (10-50 usos)

4. Considere o impacto financeiro

   • Calcule o custo total da campanha
   • Monitore o uso em tempo real
   • Ajuste se necessário (desative se uso excessivo)

---

🔄 Gestão de Cupons

1. Revise periodicamente os cupons ativos

   • Desative cupons expirados
   • Remova cupons não utilizados
   • Analise quais tipos têm melhor performance

2. Use descrições detalhadas

   • Explique as condições do cupom
   • Documente o objetivo da campanha
   • Facilita entendimento da equipe

3. Monitore o uso em tempo real

   • Acompanhe o card "Uso do Cupom"
   • Identifique cupons próximos do limite
   • Estenda limite se campanha bem-sucedida

4. Comunique mudanças à equipe

   • Informe quando criar cupons importantes
   • Avise sobre desativações
   • Mantenha todos alinhados

---

⚠️ Cuidados ao Editar

1. Não altere cupons em campanhas ativas

   • Pode causar confusão nos clientes
   • Prefira criar novo cupom

2. Cuidado ao reduzir limite de uso

   • Não reduza para menos que já foi usado
   • Pode impedir uso de clientes que planejavam usar

3. Teste alterações importantes

   • Simule o uso do cupom após editar
   • Verifique se comportamento está correto

4. Documente as mudanças

   • Anote o motivo da alteração
   • Comunique à equipe de marketing

---

📅 Gerenciamento de Períodos

1. Configure períodos realistas

   • Não crie cupons com validade muito longa
   • Revise e renove cupons periódicos

2. Use horários estratégicos

   • Inicie campanhas à meia-noite (00:00)
   • Termine campanhas ao fim do dia (23:59)

3. Planeje com antecedência

   • Crie cupons antes de divulgar
   • Teste antes de campanhas grandes

4. Monitore expirações

   • Verifique cupons próximos de expirar
   • Estenda se campanha bem-sucedida

---

Perguntas Frequentes (FAQ)

Posso ter dois cupons com o mesmo código?

Não é recomendado. Cada código deve ser único para evitar conflitos no sistema e confusão nos clientes. O sistema pode impedir a criação de códigos duplicados.

Posso alterar o tipo de cupom depois de criado?

Sim, mas com muito cuidado. Alterar de Porcentagem para Valor Fixo (ou vice-versa) pode causar problemas se o cupom já estiver em uso. É recomendado criar um novo cupom em vez de alterar o tipo.

O que acontece se o limite de uso for atingido?

Quando o limite de uso é atingido, o cupom não pode mais ser usado pelos clientes, mesmo que ainda esteja dentro do período de validade. Você pode editar o cupom e aumentar o limite se necessário.

Posso excluir um cupom que já foi usado?

Tecnicamente sim, mas não é recomendado. A exclusão pode afetar relatórios e históricos de pedidos. Prefira desativar o cupom alterando o status para "Inativo".

Como funciona o desconto máximo em cupons de porcentagem?

O desconto máximo limita o valor total de desconto. Por exemplo: cupom de 20% com desconto máximo de R$ 100. Se a compra for R$ 1000, o desconto seria R$ 200 (20%), mas será limitado a R$ 100.

Posso criar cupons sem data de expiração?

Não. Todos os cupons devem ter data de início e término configuradas. Isso garante melhor controle das promoções.

Quantos cupons posso criar?

Não há limite técnico, mas é recomendado manter apenas cupons ativos e relevantes para facilitar o gerenciamento.

O cupom pode ser usado múltiplas vezes pelo mesmo cliente?

O limite de uso é global, não por cliente. Se você configurar limite de 100, o cupom pode ser usado 100 vezes no total, independente de quantos clientes diferentes usarem.

---

Suporte

Precisa de Ajuda?

Se você encontrou algum problema ou tem dúvidas:

1. Verifique este manual para soluções comuns
2. Consulte a seção de Problemas Comuns acima
3. Entre em contato com o suporte técnico com as seguintes informações:
   • Print da tela ou descrição do problema
   • Código do cupom (se aplicável)
   • Mensagens de erro exibidas
   • O que você estava tentando fazer

Informações Úteis ao Contatar o Suporte

Tenha em mãos:

• Seu nome de usuário
• Código do cupom relacionado
• Tipo do cupom
• Prints de tela do problema
• Descrição detalhada do que você tentou fazer

---

Glossário

Termo	Significado
Cupom	Código promocional que oferece desconto aos clientes
Código	Identificador único do cupom digitado pelo cliente
Tipo	Categoria do cupom (Porcentagem, Valor Fixo, Frete Grátis)
Desconto	Valor ou percentual de redução no preço
Status	Estado do cupom (Ativo ou Inativo)
Limite de Uso	Quantidade máxima de vezes que o cupom pode ser usado
Valor Mínimo	Valor mínimo da compra para o cupom ser válido
Desconto Máximo	Limite máximo de desconto em reais para cupons de porcentagem
Período de Validade	Intervalo de datas em que o cupom pode ser usado
Uso do Cupom	Quantidade de vezes que o cupom já foi utilizado
Badge	Etiqueta visual que identifica tipo ou status
Auditoria	Registro de quem criou/modificou e quando

---

Próximos Passos

Após dominar os cupons, você pode:

• 📊 Analisar o desempenho dos cupons em relatórios
• 🎯 Criar estratégias de marketing com cupons segmentados
• 💰 Configurar cupons para eventos sazonais (Black Friday, Natal, etc.)
• 🔄 Integrar cupons com campanhas de e-mail marketing
• 📈 Acompanhar métricas de conversão por cupom

Bom uso da ferramenta de cupons! 🎫